<!-- Note: This file is primarily defined to be used in the IXP documentation. However, it is also provided in the docker-deployment repository for reference. If you accessed this file from the docker-deployment repository, please be aware that the links used in this file may not work as expected. -->

# 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](../architecture/overview.md) in the
documentation.

## Prerequisites

### Hardware Requirements

Before you begin, ensure that you have the following:

- a server with at least a 4-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](https://docs.docker.com/engine/install/) with required version
    v25.0.0 or later
- [Docker Compose](https://docs.docker.com/compose/install/linux/) 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](./https/base-setup.md) for a TLS certificate by Let's Encrypt,
- or [https-owncert](./https/owncert.md) 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](https://semver.org/). 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:

- [frontend](https://gitlab.fi.muni.cz/inject/frontend/-/releases)
- [backend](https://gitlab.fi.muni.cz/inject/backend/-/releases)

### 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](./setup.md#environment-variables).
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](./troubleshooting.md).

!!! 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](./users.md).

## 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](https://gitlab.fi.muni.cz/inject/inject-docs/-/raw/dux/files-from-repos/intro-definition.zip?ref_type=heads&inline=false)
and try to upload it to test the platform's functionality.

If you encounter any bugs, please refer to the
[Known Issues and Fixes](../../known-issues.md) page for troubleshooting steps
and solutions. If you encounter any other issues, don't hesitate to report them
to us through the [Report Issue](../../report-issue.md) 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.

<div class="navigation" markdown>
 [&larr; Home](../../index.md){ .md-button }
 [Troubleshooting](troubleshooting.md){ .md-button }
</div>
