First Run Guide
Are you interested in creating your own instance of LogUI server for your experiments and other interaction logging tasks? Great, we're thrilled that you are! This page will present to you everything you need to know to get an instance of LogUI server up and running.
Note that where you are required to issue a command to a terminal/Command Prompt instance, we precede the command with a dollar sign (
$). You're not required to enter this; this is a standard symbol to denote a terminal command is following. If you were asked to run$ cd scripts, you'd entercd scripts.
One of the most important motivations behind designing LogUI server the way we did is portability. Setting up your environment by installing all kinds of software can be a nightmare, so by developing LogUI server in a containerised environment, we have taken 99% of the hassle of setting up out of the equation for you. You can thank us later.
As we're using a containerised architecture, you'll need to make sure that you have Docker installed on the computer you're going to host LogUI server on. You'll also need to make sure you have a TCP port exposed on that computer to your private network (if you are running things internally at your institution) or to the wider Internet if you are going to be crowdsourcing participants, for example. Ideally, you'll have TCP port 80 free (we haven't implemented HTTPS/WSS functionality yet) — but any port will do.
We developed LogUI server using version 19.03 of Docker. This version or greater should work fine; any version of Docker below 19.03 may not have all the required functionality. These have not been tested by us; use any older version of Docker at your own risk and expect issues. If you don't have Docker, you can follow the instructions on the Docker website to download and install it for your platform.
In addition to Docker, you'll also need docker-compose. docker-compose is a helper that deals with the orchestration and management of the containers that LogUI server is comprised of. Instead of you having to create a proxy container and worker container, docker-compose handles all of this for you in one go. If you have Docker Desktop for Windows or macOS, you'll already have docker-compose installed. On a Linux distribution, you may need to install it separately — again, look at the Docker website for instructions on how to do this. We require that you have at least version 1.18.0 of docker-compose installed; any version that supports a compile file of version 3.0 should work fine.
You'll also require git to be installed on your system to clone the LogUI server repository, unless you download the code directly from the GitHub website.
To summarise, make sure you have the following software installed.
- Docker, at least version
19.03. -
docker-compose, at least version1.18.0. - Git (if cloning the repository).
Once you've confirmed that everything is installed, you can download the code for LogUI server. Find somewhere on your filesystem where you'd like the code to live, and then use git to clone the repository.
$ git clone https://github.com/logui-framework/server
This creates a server directory with the LogUI server code. If you want something a bit more descriptive for a directory name, try the following git clone command instead.
$ git clone https://github.com/logui-framework/server logui-server
This clones the LogUI server code into a logui-server directory. It doesn't matter what name you provide for this directory.
Alternatively, if you don't want to use git, then just go to GitHub and download the code at https://github.com/logui-framework/server/. Click the green Code button, and then the Download ZIP link. Extract the ZIP file and place the server-main directory wherever you want it to live. Of course, you can also rename this directory to something more descriptive if you like.
Wherever you store the LogUI server code, we'll refer to this as the root directory from now on. For the avoidance of doubt, this is the directory with the empty LOGUI-ROOT file in it.
Once you have a copy of LogUI server on your computer, you'll need to open a terminal/Command Prompt and change into the scripts directory, which lives in the root directory.
$ cd scripts
There's several scripts in this directory to make setting up LogUI server easy. The first script we'll need to run is the create_env script. This creates a .env file in the root directory, containing several variables that are used by Docker when instantiating LogUI server.
We ask you to read the Environment Configuration Wiki page carefully to understand what variables should be present within this file.
To run the create_env script, simply issue the following command from your terminal.
$ ./create_env.sh
If you are using the Windows Command Prompt, run the following Batch script instead.
create_env.bat
Both have the same effect — they create the .env file in the root directory with basic configuration options. Once this file has been created, we ask you to open the newly created file and check (and change where necessary) any values where required. Note that on macOS or Linux, you may not be able to see this file by default in your Finder or file explorer. In the terminal, try the following commands from the root directory (i.e., $ cd .. back up one level first).
$ nano .env
This will open the nano text editor with the file.
Again, we ask you to read the Environment Configuration Wiki page carefully to understand what variables should be present within this file.
Note that the create_env script should only be used when setting up LogUI server. Once you have started LogUI server at least once, do not change the SECRET_KEY variable's value. If you do this, you'll break the encryption functionality for LogUI server. Any applications set up to be tracked with your server instance will then fail authentication. The SECRET_KEY is used to encrypt the authorisation tokens! You can however change the port number (PROXY_LISTEN_ON) at a later date after first setup.
Good! You have the LogUI server code on your computer, and a complete .env file that Docker will use to set everything up for you. Now it's time to build the LogUI server Docker images, as well as pull pre-made images from the Docker registry (for the databases that LogUI server uses).
From the root directory, you should issue the following command.
$ docker-compose -p logui build
This builds all of the containers necessary for LogUI server to function. Depending on your computer, it should take somewhere between 5 and 10 minutes to do this.
You then should pull prebuilt Docker images from the Docker registry (for services like MongoDB and Postgres). Do this with the command
$ docker-compose -p logui pull
In total, both these commands will download around 400MB of images to your disk.
Start the LogUI server with the following command.
$ docker-compose -p logui up
This will start the images. Note that here, the LogUI server HTTP worker will compile the control app. This will take about 10-15 seconds to do. You will see the following line in the output when this process is complete.
LogUI HTTP server is running
This should come from the container http-worker_1, which is responsible for serving the LogUI server control application.
Once you see this message, navigate to the address where you have configured LogUI to run (e.g., http://localhost:8000) in your favourite browser. If you see the LogUI control app, you are almost there!
In another terminal, run the create_user.sh script. Only do this when LogUI server is running; it will fail otherwise.
cd scripts
./create_user.sh david
If you want to create an account with name david. Enter an e-mail address (just push ENTER to skip), and type a password. Repeat the password. If you are prompted that the password is common, you can either push n to try a different one, or just accept what you have typed with y.
You can then login to the LogUI server control application with the details you supplied at step 6.
When you want to bring LogUI server down, you should use docker-compose to do so.
docker-compose -p logui down
This will shut down all containers, but it will not remove your data in the database volumes, nor will it remove built images. You can start LogUI server again from this state again at a later stage, as in step 5, with the command
docker-compose -p logui up