Docker¶
The best way to install the MUSCLE application is with using docker. This way it can easily be maintained.
It’s recommended that you set up a reverse proxy server in front of the docker image to expose your MUSCLE app to the Internet.
Install docker on your system and do the following steps.
Download Docker Image¶
Note
Currently the docker registry for the muscle docker image is not public. Therefore, you have to login into the registry first to pull the image. Use your BFH credential to login, an access or deploy token (recommended).
Warning
It’s recommended not to use the latest tag but a fixed tag version to ensure compatibility between the muscle application and your devices.
Login into the registry hub of the BFH Gitlab instance -> use your credentials
docker login registry.gitlab.ti.bfh.ch/muscle/muscle
Download image and extract.
docker pull registry.gitlab.ti.bfh.ch/muscle/muscle/muscle:latest
Docker Compose¶
To start the container, we use a docker-compose file.
A simple docker configuration may look like this docker-compose.yml:
version: "3.2"
services:
muscle:
container_name: muscle
# muscle docker image
image: registry.gitlab.ti.bfh.ch/muscle/muscle/muscle:latest
restart: always
ports:
# map the port 80 from the host to the port 80 of the container
# You may need to configure a proxy server with certificate generation for MUSCLE
- 80:80
volumes:
# mount the database directory into the container
- ${PATH_TO_DATA}/database/:/var/www/muscle/backend/database/
# mount the application config into the container
# (alternatively supply it via the MUSCLE_FRONTEND_CONFIG environment variable, see below)
- ${PATH_TO_CONFIG}/application.config.json:/var/www/muscle/frontend/config/application.config.json
Please refer to the docker documentation for information of the configuration used in this file.
Note
The values inside the parantheses ${} can be placed inside a file called .env in the same directory like the docker-compose.yml itself. In this file the values can be exported:
PATH_TO_DATA=/path
PATH_TO_CONFIG=/other_path
Replace /path and /other_path with the corresponding path on your system.
Volumes¶
The listed volumes in the file will make the data of MUSCLE persist even when the container gets removed or updated. Not doing so will place the files in the default docker mount directory somewhere under /var/lib/docker/volumes.
database¶
The database of MUSCLE is located at /var/www/muscle/backend/database/ to make it easy to back it up and persist it, mount it outside of the container.
mkdir <PATH_TO_DATA>/database
Note
The ownership of the database directory is adjusted automatically by the container on startup.
application.config.json¶
The configuration for the MUSCLE webapp. Refer to the frontend configuration documentation for the contents of this file.
Note
In most cases it is not necessary to change this file when using the docker image. It has already everything setup to work. Only change this configuration if you know what you are doing.
Configure the Application¶
To configure the application, environment variables can be easily set in the compose file. To do so create a new key environment under the muscle image. The configurable options can then be defined like this:
services:
muscle:
#...
environment:
- MUSCLE_USER_DEFAULT_PWD=${DEFAULT_PWD}
- MUSCLE_BRAND_NAME=${BRAND_NAME}
#...
A description of configuration variables can be found here
MUSCLE_FRONTEND_CONFIG¶
Instead of mounting application.config.json as a volume, the content of the frontend configuration can also be supplied directly with the environment variable MUSCLE_FRONTEND_CONFIG. If it is set, its content is written to /var/www/muscle/frontend/config/application.config.json when the container starts.
services:
muscle:
#...
environment:
- 'MUSCLE_FRONTEND_CONFIG={"device": {"defaultAPIVersion": "v2"}}'
The content must be the full JSON configuration as described in the frontend configuration.
Note
Use either the environment variable or the volume mount, not both. Since the environment variable overwrites the configuration file on startup, it would also overwrite the content of a mounted file.
Note
It’s not recommended to change paths inside the docker container with variables like MUSCLE_DB_PATH since they are inside the container. You can already adjust the path on your host when mounting the volume. However if you change them make sure to also specify the correct volume inside the container when mounting e.g.
environment:
- MUSCLE_DB_PATH=/example/path/
volumes:
- ${PATH_TO_DATA}/database/:/example/path/