Skip to content

Installation

The INJECT Exercise Platform (IXP) comprises two main components: the frontend and the backend. This separation allows for modular development, easier maintenance, and scalability of the platform. Below, we'll walk you through the unified installation process for the frontend and backend.

For a deeper understanding of the overall architecture of the IXP, you can refer to the architecture overview in the documentation.

Prerequisites

Hardware Requirements

Before you begin, ensure that you have the following:

  • a server with at least a 2-core CPU and 8 GB RAM,
  • a 64-bit x86 architecture,
  • root or sudo access to the server,
  • and at least 4 GB of disk space, although more is necessary for long-term storage of exercise data.

These requirements ensure that the backend server can handle data processing efficiently while serving the frontend interface smoothly for the most basic needs.

The performance mainly depends on one factor, which is the number of teams in all currently running exercises. Please refer to the table below for our recommended hardware setups based on this value.

Number of teams CPU Cores (Worker Count) RAM
0 - 20 2 (4) 8GB
21 - 50 4 (8) 16GB
51 - 100 8 (16) 16GB

We cannot give a good recommendation for disk space, as that only depends on the number of exercises and definitions stored at the same time.

Software Requirements

  • Linux operating system: Debian 11 or 12 is recommended
  • Docker Engine with required version v25.0.0 or later
  • Docker Compose with recommended version v2.27.0

Make sure to install Docker and Docker Compose before proceeding with the installation.

Installation

1. Choose a Docker Compose preset and follow the instructions on setting up the TLS certificates:

  • https for a TLS certificate by Let's Encrypt,
  • or https-owncert for setup with your own certificate.

2. Download the source code of the frontend and the backend:

The frontend and backend releases follow a modified version of Semantic Versioning. Each release is tagged with a version number in the format vX.Y.Z, where:

  • X is the major version,
  • Y is the minor version,
  • Z is the patch version.

The major version is incremented for significant changes to the whole platform. Such releases are deployed together with a new version of the documentation and exercise definitions.

The minor version is incremented for changes to the API. Because of this, only the frontend and backend with the same major and minor version are compatible with each other. For example, v3.0.0 of the frontend is compatible with v3.0.0 of the backend but not with v2.0.0 of the backend. Similarly, v3.1.0 of the frontend is compatible with v3.1.0 of the backend, but not with v3.0.0 of the backend.

The patch version is incremented for bug fixes and minor improvements. Such releases are created for the frontend and backend separately. The patch versions of the frontend and backend do not have to match. For example, v3.0.1 of the frontend is compatible with v3.0.0 of the backend, but not with v2.0.0 of the backend.

The releases can be downloaded from the following links:

3. Unzip the downloaded archives, move them inside the compose preset folder (https or https-owncert, depending on which one you chose for generating TLS certificates), and rename the unzipped folders to frontend and backend respectively.

The deployment script expects the source code in folders named frontend and backend.

4. Set up the .env file in the root directory (https or https-owncert).

Follow the setup guide here. Especially make sure that you update these variables:

  • INJECT_DOMAIN is set to your desired hostname (the same one you generated the certificate for)
  • INJECT_SECRET_KEY is changed to a truly random string of characters of at least 50 characters.
  • INJECT_DB_PASS is set to a secure password

5. Make sure the prepared scripts are executable.

The following scripts are used to set up the environment. Make sure they are executable:

  • ./01-substitute-env.sh: you can grant the executable permission via chmod +x 01-substitute-env.sh,
  • ./frontend/substituteEnv.sh: you can grant the executable permission via chmod +x ./frontend/substituteEnv.sh.

6. Run docker compose up, or docker compose up -d to run the containers in the background.

If any errors occur, please refer to the troubleshooting guides.

Disclaimer

If you are upgrading an existing installation, please note that all stored data will be lost during the upgrade process, as we cannot guarantee compatibility between different versions of the platform.

To avoid problems during the upgrade process, please stop the running containers and remove the volumes by executing docker compose down -v. Also, make sure to rebuild the containers by executing docker compose up --build when starting them again.

7. Add an admin account by following these instructions.

Conclusion

By following the installation guide, you'll be able to set up and deploy the IXP. After completing the installation, you may download the Intro Definition and try to upload it to test the platform's functionality.

If you encounter any bugs, please refer to the Known Issues and Fixes page for troubleshooting steps and solutions. If you encounter any other issues, don't hesitate to report them to us through the Report Issue page.

Backup

If you want to back up your IXP installation, it's advised to back up:

  • data located in the inject-data and the inject-pgdata docker volume,
  • and the INJECT_SECRET_KEY variable. This key is critical to ensure proper functioning of AAI: if the same database is used with a different key, users will not be able to log in.

← Home Troubleshooting