Skip to content

02. Start the application

Jump to bottom
Drikus Roor edited this page Mar 12, 2024 · 10 revisions

Before installation

We recommend downloading a code editor, for instance Visual Studio Code, and to use git to copy this repository to your machine, as this makes it easier to keep your local copy up to date.

Installation with Docker

The easiest way to run the application locally is through Docker. Docker is an application which runs a network of virtual machines ("containers") and is therefore (mostly) platform independent.

Mac OS X or Windows 10

Install Docker Desktop.

Linux

As of April 2022, Docker Desktop for Linux is still in Beta and have not been tested by us.

Development server

Make a copy of the file .env.dist (in the same directory as this README) and rename it to .env. This file contains variables used by Docker to start up a container network serving MUSCLE.

Start Docker (the app icon is a whale carrying containers). Then, open a terminal and run docker-compose up (add sudo on Linux). This command starts up the containers defined in docker-compose.yaml:

  • a PostgreSQL container, for storing experiment/user/playlist data, saved on the host machine in the Docker user data, represented in the volume db_data. Data added to the database will persist if the container is shut down.
  • a ip2country container, which provides country codes for ip addresses, used for demographic information of users.
  • a container of the server, defined in DockerfileDevelop in backend. The Dockerfile defines the Python version and installs development dependencies. The startup command runs migrations, adds a superuser (as defined in the .env file), playlist and basic experiment and then starts up a Django development server.
  • a container of the client, defined in DockerfileDevelop in frontend. The Dockerfile defines the node version and installs node modules. The startup command kicks off a React development server.
  • a Traefik container*, which acts as a reverse proxy and allows you to reach the admin interface and the user interface on the following local domains (which are easier to remember):
    • http://muscle.local - The front-facing user interface that participants will use.
    • http://backend.muscle.local - The admin interface that researchers and developers use to configure experiments.

* You will also need to add these domains to your "hosts" file. You can automatically do this by executing the following script:

./scripts/add-hosts-entries

or by manually adding the following host entries to your hosts file:

# The hosts file is usually located in /etc/hosts
127.0.0.1 muscle.local
127.0.0.1 backend.muscle.local

Navigate to the admin and user interface

Once you see all containers have started up, open your browser and navigate to localhost:3000 or http://muscle.local. You should now be able to see the first screen of the Goldsmiths Musical Sophistication Index questionnaire.

To see the admin interface, navigate to http://localhost:8000/admin or http://backend.muscle.local.

Since the docker-compose.yaml defines bind mounts for backend and frontend, any changes to the files on the host are immediately reflected in the containers, which means code watching works and hot reload works in the same way as with a native node or Django server.

To stop the containers, press ctrl-c or (in another terminal) run docker-compose down.

Production build

A production build should define its own docker-compose.yaml, making use of the Dockerfile of the backend and frontend environments. It should also define a custom .env file, with safe passwords for the SQL database and the Python backend. Instead of mounting the entire backend and frontend directory and using the development servers, the backend should serve with gunicorn, and the frontend should use a build script to compile static html, css and JavaScript.

>Next

Updating the application

The MUSCLE platform is continuous development and new features and bug fixes are added to the codebase from time to time. To update the platform, checkout the main branch (which is contains the latest stable release) or the develop branch (which contains not yet released features), pull the latest changes using git pull, and rebuild the docker containers using docker-compose up --build. Additionally, before rebuilding the containers, you might want to check if new or updated environment variables should be updated by comparing your .env file with the .env.dist, which contains the environment variables that can or should be used.

In short:

# 1. Checkout the main or develop branch
git checkout main # or develop

# 2. Pull the latest features, bug fixes, and other changes.
git pull

# 3. Compare your .env file with the .env.dist file and update your environment variables accordingly

# 4. Rebuild & restart the containers
docker compose up --build
Clone this wiki locally