Docker

This page provides an overview of our project's Docker integration, including instructions on building Docker images, details on the automated build process via GitHub Actions, and information on environment variables and volumes.

Building Docker Images

To build a Docker image for MAGI, you will need to have Docker installed on your machine. Once installed, you can build the image by navigating to the project's root directory and running the following command:

docker build -t magi:tag .

Replace tag with your desired tag, such as latest or a version number. This command reads the Dockerfile in the project's root directory and builds an image according to the instructions defined therein.

Automated Builds with GitHub Actions

MAGI uses GitHub Actions to automate the building of Docker images upon pushing changes to the master branch. This CI/CD pipeline ensures that the Docker image is always up to date with the latest codebase. The action is defined in the .github/workflows directory. It triggers the build process, tags the image with the commit SHA, and pushes the image to a Docker registry. This automation streamlines the deployment process and ensures consistency across environments.

Environment Variables

The Docker image supports various environment variables to customize the behavior of the application. These variables can be passed to the Docker container at runtime using the -e or --env flag in the docker run command. For example:

docker run -e VARIABLE_NAME=value magi

Refer to the project documentation for a list of all supported environment variables and their purposes.

Volumes and Settings Preservation

Settings Folder

The application uses a mounted volume for the settings folder, allowing users to preserve settings across containers. This feature is particularly useful for maintaining consistent configurations and data without manual intervention every time a container is restarted or updated. To use this feature, specify the volume mount when running the container:

docker run -v /path/on/host/settings:/app/settings your-image-name:tag

This command mounts the host directory /path/on/host/settings to the settings folder inside the container. Any changes made to the settings within this folder will persist across container instances.

Important Note on Breaking Changes

When updating to a new version of the application, be aware that there may be breaking changes that could affect your settings. If you encounter issues after an update, it may be necessary to delete the settings folder on your host to reset the configurations. However, exercise caution and ensure you have backups of any important data before doing so.

Non-Persistent Settings Files

Please note that some settings files that are not located within the settings folder may not be preserved across container updates. It is important to regularly back up any critical configuration files or consider incorporating them into the settings folder if persistent storage is required.