To start Lagun, all you have to do is type a simple command:
cd {LAGUN_DIR}
R -e "renv::load(); shiny::runApp('app.R', port=6023)"
and after a wait, your web browser opens and you can simply begin to use the application. Right. But it can be useful to know what’s going on behind the scenes.
About Lagun itselft
Lagun is a Shiny application. What is Shiny? It is an R package that allows to create interactive web applications.
As a result, Lagun is composed of two parts:
-
a server part, which dynamically generates content of a HTML webpage dedicated to each user and which modifies it in response to user actions;
-
a client part, which renders the HTML webpage that users interact with.
So basically, when Lagun is started, two actions are performed:
-
startup of a server on the user machine, waiting for client connection (and access point is typically port 6023);
-
open the HTML page exposed on port 6023 of the local machine, using default web browser.
This division into two parts is largely hidden from the user, but can be useful to know. Two case studies:
Case 1
You can start the server once and for all, then open a client session (or even several) on your web browser only when necessary.
In this case, the commands to start the Lagun server are (please note the additional argument launch.browser=FALSE):
cd {LAGUN_DIR}
R -e "renv::load(); shiny::runApp('app.R', port=6023, launch.browser=FALSE)"
and the command to open a Lagun session is:
R -e "browseURL('http://localhost:6023')"
Case 2
You can start the server on a dedicated machine of your network and open a client session from your own machine.
In this case, on the dedicated host, the command to start the Lagun server is (please note the additional argument host='0.0.0.0'):
cd {LAGUN_DIR}
R -e "renv::load(); shiny::runApp('app.R', host='0.0.0.0', port=6023, launch.browser=FALSE)"
and on your own machine, the command to open a Lagun session is (where lagun.dedicated.host is the name or the IP address of the dedicated host):
R -e "browseURL('http://lagun.dedicated.host:6023')"
Warning: to avoid any security problems, make sure you deploy Lagun within a company firewall.
Notes:
-
R is a single threaded application which means that Lagun cannot serve two different users at precisely the same time. This is not an issue in most cases because most computations only take tens or hundreds of milliseconds. But for some computations, you may find that the user experience does not meet your expectations (Lagun freezes, no longer responding). A solution is to use shinyapps.io: it allows you to scale Lagun to support multiple simultaneous users. But if you only need to work on two studies simultaneously, a simpler solution is to run two instances of Lagun, each one using its own port.
-
You can’t bookmark Lagun to return to the same place in the future or share your work with someone else with a link in an email. Lagun’s solution to this problem is to allow you to export your work as a file so that you can share it or import it during another session.
About Lagun simulations launcher
Originally, in Lagun, the user had to provide results (Y values) associated to input parameters (X values) by importing results files from the user file system. Later, the possibility of obtaining these results via user defined scripts running on user machine was added. This possibility is provided by an application called « simulations launcher ». Like Lagun, simulations launcher takes the form of a web application to which the Lagun client connects (Lagun server goes through the client to request simulations launcher).
The command to start the simulations launcher is:
cd {SIMULATIONS_LAUNCHER_DIR}
node main
Once the server is started, in a very similar way to Lagun, it is waiting for client connection, where default access point is port 3000. You can open the HTML page exposed on port 3000, it provides a more user-friendly way of defining simulators and can be helpful to monitor simulations.
The command to start the simulations launcher user interface is:
R -e "browseURL('http://localhost:3000')"
Once again, this division into two parts can be useful to know. Two use cases:
Case 1
Start the server once and for all, then open a client session (or even several) on your web browser only when necessary.
Case 2
Start the server on a dedicated machine of your network and open a client session from your local machine.
On the dedicated host, command to start the Simulations Launcher server on a specific port (let’s say 3001) is:
cd {SIMULATIONS_LAUNCHER_DIR}
node main 3001
On your own machine, command to open a simulations launcher session is (where launcher.dedicated.host is the name or the IP address of the dedicated host):
R -e "browseURL('http://launcher.dedicated.host:3001')"
About the link between Lagun and the simulations launcher
By default, Lagun tries to contact the simulations launcher on port 3000 of the local machine. But Lagun can be told which address to use to reach the simulations launcher.
There are two ways to achieve this:
Method 1
Set an environment variable simulations_launcher_url before starting the Lagun server.
On the dedicated host, command to start the Lagun server is (please note the additional item Sys.setenv(simulations_launcher_url = 'http://launcher.dedicated.host:3001')):
cd {LAGUN_DIR}
R -e "renv::load(); Sys.setenv(simulations_launcher_url = 'http://launcher.dedicated.host:3001'); shiny::runApp('app.R', host = '0.0.0.0', port=6023, launch.browser = FALSE)"
Method 2
Open the Lagun page using the usual address, but adding a query string (which corresponds to the part of the address starting by a question mark ?).
R -e "browseURL('http://localhost:6023?simulations_launcher_url=http://launcher.dedicated.host:3001')"
About remote machine used via ssh
With simulations launcher, a simulator can be defined as running on a remote machine accessible via ssh (useful, for example, when you can’t install the simulations launcher on a host, but can connect to it via ssh).
