diff --git a/backend b/backend
index 516ba6dcb219a15b8fa5ddcadf4db956edba23b1..f9294b13a2b57a9f49f69bbb4d2f2a46a1d9e5ac 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 516ba6dcb219a15b8fa5ddcadf4db956edba23b1
+Subproject commit f9294b13a2b57a9f49f69bbb4d2f2a46a1d9e5ac
diff --git a/docs/tech/installation/https/base-setup.md b/docs/tech/installation/https/base-setup.md
index 72f2a7d2e27443c512c4ee2aaa672cd6b6592665..320b57c52913485f8d041b0645712df1b1546cb6 100644
--- a/docs/tech/installation/https/base-setup.md
+++ b/docs/tech/installation/https/base-setup.md
@@ -1,37 +1,34 @@
-For version 2.0.0 of IXP, download [Compose preset folder for HTTPS deployment using Let's Encrypt](https://gitlab.fi.muni.cz/inject/docker-deployment/-/package_files/221/download) and follow instructions below.
+For version 3.0.0 of IXP, download the compose preset folder for HTTPS deployment using Let's Encrypt [here](https://gitlab.fi.muni.cz/inject/docker-deployment/-/package_files/229/download), unzip it, set it as your working directory, and follow the instructions below.
## HTTPS Deployment
-For HTTPS deployment, before executing `docker compose up` (see [installation](../overview.md) guide),
-you need to generate HTTPS certificates.
-In this configuration these certificates are generated via [Certbot](https://certbot.eff.org/) by Lets Encrypt.
+For HTTPS deployment, you need to generate HTTPS certificates.
+In this configuration, the certificates are generated via [Certbot](https://certbot.eff.org/) using Lets Encrypt.
-This can be done via `./cert_script.sh` script which automatically generates the certificate in the current directory.
+This can be done via the `./cert_script.sh` script, which automatically generates the certificate in the current directory.
Invoke the script like so, substituting the placeholders for their respective values:
+
```bash
./cert_script.sh <email-address> <domain>
```
+
After the certificate has been generated,
an email will be sent to the provided address with additional information about the certificate.
The same script can be used to renew the certificates.
Example usage:
+
```bash
./cert_script.sh admin@inject.fi.muni.cz inject.fi.muni.cz
```
-Please note that by executing this script you're agreeing to Certbot's TOS and Privacy Policy,
+Please note that by executing this script, you're agreeing to Certbot's TOS and Privacy Policy,
and your email will be used for essential communication about expiration notices.
-After generating the certificates, please ensure that:
-- `INJECT_DOMAIN` is setup to your desired hostname in the `.env` file enclosed in the `docker/nginx/https` directory
-- `INJECT_SECRET_KEY` is changed to a truly random string of characters of at least 50 characters long
-- `01-substitute-env.sh` is executable via `chmod +x 01-substitute-env.sh`.
-
-Then you may execute `docker compose up -d` and your deployment is up and running.
+After adding the certificates, proceed with the installation as described in the [installation guide](../overview.md).
<div class="navigation" markdown>
[← Installation overview](../overview.md){ .md-button }
[HTTPS Owncert](./owncert.md){ .md-button }
-</div>
\ No newline at end of file
+</div>
diff --git a/docs/tech/installation/https/owncert.md b/docs/tech/installation/https/owncert.md
index ec4e51fd47aa403b96bf240185dc63ce22683d1a..348881e7d3268f84639ca7487c210f8574a426ed 100644
--- a/docs/tech/installation/https/owncert.md
+++ b/docs/tech/installation/https/owncert.md
@@ -1,25 +1,14 @@
-For version 2.0.0 of IXP, download Compose preset folder for HTTPS Deployment with your own certificates from [here](https://gitlab.fi.muni.cz/inject/docker-deployment/-/package_files/222/download).
+For version 3.0.0 of IXP, download the compose preset folder for HTTPS Deployment with your own certificates [here](https://gitlab.fi.muni.cz/inject/docker-deployment/-/package_files/230/download), unzip it, set it as your working directory, and follow the instructions below.
## HTTPS Deployment with your own certificates (advanced)
-For HTTPS deployment with your own certificates,
-include `fullchain.pem` and `privkey.pem` into the `docker/nginx/https-owncert/certificates/` directory.
-If the format of the keys or selection of keys does not suffice,
-it's advised to modify the `nginx.conf.template` file and change the related configuration in line `:32-33`.
-Docker compose mounts the `./certificates` folder as `/etc/nginx/certificates/` in the Nginx container.
-All of this has to be done before executing step 5 listed in the main [installation](../overview.md) guide.
-
-Name of the nginx configuration file is intentionally named as such due to `01-substitute-env.sh` script,
-which substitutes `INJECT_DOMAIN` variable with environment variable value.
+For HTTPS deployment with your own certificates, add `fullchain.pem` and `privkey.pem` into the `./certificates` directory. If the format of the keys or selection of keys does not suffice, modify the `nginx.conf.template` file and change the related configuration on line `:32-33`.
-Please ensure that:
-- `INJECT_DOMAIN` is setup to your desired hostname in the `.env` file enclosed in the `docker/nginx/https-owncert` directory
-- `INJECT_SECRET_KEY` is changed to a truly random string of characters of at least 50 characters long
-- `01-substitute-env.sh` is executable via `chmod +x 01-substitute-env.sh`.
+Docker compose mounts the `./certificates` folder as `/etc/nginx/certificates/` in the Nginx container.
-Then you may execute `docker compose up -d` and your deployment is up and running
+After adding the certificates, proceed with the installation as described in the [installation guide](../overview.md).
<div class="navigation" markdown>
[← Installation overview](../overview.md){ .md-button }
[Basic HTTPS](./base-setup.md){ .md-button }
-</div>
\ No newline at end of file
+</div>
diff --git a/docs/tech/installation/overview.md b/docs/tech/installation/overview.md
index 0382041f6353b826837b1c4e221a0936885681c1..70f208d01fe3de1b207027435a4f735a4dfc3eb5 100644
--- a/docs/tech/installation/overview.md
+++ b/docs/tech/installation/overview.md
@@ -13,43 +13,55 @@ you can refer to the [architecture overview](../architecture/overview.md) in the
Before you begin, ensure that you have the following:
-* A server with at least 2 core CPU and 4 GB RAM
-* A 64-bit x86 architecture
-* Root or sudo access to the server
-* Approximately 0.5 GB of disk space for both the platform and files needed for exercises
+- A server with at least 2 core CPU and 6 GB RAM
+- A 64-bit x86 architecture
+- Root or sudo access to the server
+- At least 3 GB of disk space, although more might be necessary to hold files uploaded during exercises
These requirements ensure that the backend server can handle data processing efficiently while serving the frontend interface smoothly.
### Software Requirements
-* Linux operating system: Debian 11 or 12 is recommended
-* [Docker Engine](https://docs.docker.com/engine/install/).
-* [Docker Compose](https://docs.docker.com/compose/install/linux/) with recommended version v2.27.0
+- Linux operating system: Debian 11 or 12 is recommended
+- [Docker Engine](https://docs.docker.com/engine/install/).
+- [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.
+Make sure to install Docker and Docker Compose before proceeding with the installation.
-## Installation (Docker)
+## Installation
-Start with choosing Docker Compose preset [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.
-After choosing one and downloading it continue with downloading backend and frontend source code to the Compose preset folders.
+### 1. Choose a Docker Compose preset and follow the instructions on setting up the TLS certificates:
-Source code for frontend and backend can be downloaded in these following URLs
-- [Frontend](https://gitlab.fi.muni.cz/inject/frontend/-/releases)
-- [Backend](https://gitlab.fi.muni.cz/inject/backend/-/releases)
+- [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:
-### Compatibility
+- [frontend](https://gitlab.fi.muni.cz/inject/frontend/-/releases)
+- [backend](https://gitlab.fi.muni.cz/inject/backend/-/releases)
To ensure that the downloaded versions of frontend and backend work correctly,
check that they have the same version in the name on their respective `Releases` pages.
E.g. `v2.0.0` of the frontend is fully compatible with `v2.0.0` of the backend.
-1. Unzip the individual archives.
-1. Rename the unzipped directories to `frontend` and `backend` respectively.
-1. Ensure that the `.env` file in the root directory is set up correctly as per the [setup guide](./setup.md).
-1. Run `docker compose up`, if any errors occur please refer to the troubleshooting guides.
-1. Add admin (superuser) account by following [these instructions](./users.md).
+### 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.
+
+Having the source code available in folders named `frontend` and `backend` is crucial for the deployment script to work.
+
+### 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:
+
+- `INJECT_DOMAIN` is set to your desired hostname (the same one you generated the certificate for),
+- and `INJECT_SECRET_KEY` is changed to a truly random string of characters of at least 50 characters.
+
+### 5. Make sure the `01-substitute-env.sh` script is executable. You can grant the executable permission via `chmod +x 01-substitute-env.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).
+
+### 7. Add an admin (superuser) account by following [these instructions](./users.md).
## Conclusion
diff --git a/docs/tech/installation/setup.md b/docs/tech/installation/setup.md
index b4a6c75b402900967c249df011ffbdc657a2b7b3..4293948d77e8127d22447a17c2f25b435aeb4c44 100644
--- a/docs/tech/installation/setup.md
+++ b/docs/tech/installation/setup.md
@@ -1,25 +1,25 @@
## Deployment using Docker/Nginx
-INJECT Exercise Platform provides a simplified deployment method via Docker Compose.
+INJECT Exercise Platform provides a simplified deployment method via Docker Compose.
This method simplifies the deployment by creating necessary settings and pairings between the frontend and backend.
-It also creates a singular endpoint for accessing INJECT Exercise Platform.
+It also creates a singular endpoint for accessing IXP.
### Docker Setup
This solution consists of 5 containers: frontend, backend, redict, database and reverse proxy server.
-Frontend and Backend are set up to communicate under a single endpoint handled by the reverse-proxy server (Nginx).
-PostgresSQL database handles management of user/exercise data.
+Frontend and Backend are set up to communicate under a single endpoint handled by the reverse-proxy server (Nginx).
+PostgreSQL database handles the management of user/exercise data.
Redict is used to allow multiple workers on the backend.
-User-uploaded files, images and definition relevant content is stored on the Backend.
-The reverse-proxy forwards requests either to Frontend or Backend.
+User-uploaded files, images and definition-related content are stored on the Backend.
+The reverse proxy forwards requests either to Frontend or Backend.
Deployment is set up with persistent storage under two Docker Compose volumes called `inject-data` and `inject-pgdata`.
-This volume contains any data generated by INJECT and current configuration of the platform.
-At current state the platform can be effectively backed up assuming you back both volumes and `INJECT_SECRET_KEY` environment variable.
+This volume contains any data generated by IXP and the current configuration of the platform.
+At the current state, the platform can be effectively backed up, assuming you back up both volumes and the `INJECT_SECRET_KEY` environment variable.
-For HTTPS deployment it's needed to have HTTPS certificates.
-At current state, there is a prepared configuration and script for deployment via Let's Encrypt certificates.
+For HTTPS deployment, HTTPS certificates are needed.
+At the current state, there is a prepared configuration and script for deployment via Let's Encrypt certificates.
This script necessitates downtime of IXP to fully refresh or instantiate new SSL certificates.
### Environment Variables
@@ -29,34 +29,42 @@ These are prefixed under `INJECT_`.
Some additional variables are included, however these are inferred from the `INJECT_` prefixed environment variables,
which means that these do not have to be changed manually.
-#### General Configuration
+The available variables are:
+
+- `INJECT_DOMAIN` - Domain where your instance of IXP is available.
+- `INJECT_SECRET_KEY` - Used to provide cryptographic signing. Must be at least 50 long characters string.
+- `INJECT_HOST_ADDRESSES` - A comma-separated list of allowed hosts.
+- `VITE_HTTPS_HOST` - Defines the HTTPS host for which the frontend application should connect to, the hostname should point to an instance of Backend application.
+- `CORS_ALLOWED_ORIGINS` - A comma-separated list of allowed origins for Cross-Origin Resource Sharing (CORS).
+- `INJECT_EMAIL_HOST` - SMTP server address.
+- `INJECT_EMAIL_PORT` - Port to use for the SMTP server defined in INJECT_EMAIL_HOST.
+- `INJECT_EMAIL_HOST_USER` - Username to use for authentication to the SMTP server defined in INJECT_EMAIL_HOST.
+- `INJECT_EMAIL_HOST_PASSWORD` - Password to use for the SMTP server defined in INJECT_EMAIL_HOST. This setting is used in conjunction with INJECT_EMAIL_HOST_USER when authenticating to the SMTP server.
+- `INJECT_EMAIL_SENDER_ADDRESS` - The sender address for automatic emails.
+- `INJECT_EMAIL_PROTOCOL` - Optional variable for defining the preferred protocol for communication with SMTP server. The choices (values) can be ssl or tls (case insensitive). This variable can also be left undefined - no encryption will be used.
+- `INJECT_HOMEPAGE` - The URL of the homepage.
+- `INJECT_LOGS` - Path to a file where to save logs.
+- `INJECT_DB_HOST` - Host address of the database server.
+- `INJECT_DB_USER` - Username for the database.
+- `INJECT_DB_PASS` - Password for the database.
+- `INJECT_REDICT_HOST` - If set, enables Redict. Host address where Redict is running.
+- `INJECT_WORKER_COUNT` - Number of worker processes to run. This can impact performance and resource utilization.
+
+You can use the default `.env` file to set up your configuration:
```
-# sets up an appropriate hostname for the Nginx server
+# sets up appropriate hostname for the Nginx server
INJECT_DOMAIN=inject.localhost
# Secret key for cryptographic signing
INJECT_SECRET_KEY=your-at-least-fifty-or-more-characters-long-secret-key
-```
-
-
-- INJECT_DOMAIN: Defines the hostname for the Nginx server. This should be set to the **domain name** that points to your server's IP address.
-- INJECT_SECRET_KEY: Used to provide cryptographic signing. Must be at least 50 characters long. Can be anything.
-- INJECT_HOMEPAGE: The URL (link) of the deployed instance fo the INJECT platform.
- The following URL is an example: _https://my-inject-domain.com_.
- This link is used in the welcome email.
-- INJECT_MAX_UPLOAD_SIZE: Specifies the maximum body size of requests, including definition and file uploads.
- The unit of this variable is bytes.
- The default value is set to 10MB (10485760 bytes).
-
-#### Authentication, Authorization and Identification (AAI)
-
-AAI modules ensures user authentication and sending of user credentials via email invitations.
-The emails are sent out using an external SMTP server.
-The settings for sending emails is configured via the following environment variables.
+# host parameters that should be setup for client and server to interact correctly,
+# do not touch unless you know what you are doing
+INJECT_HOST_ADDRESSES=$INJECT_DOMAIN
+VITE_HTTPS_HOST=$INJECT_DOMAIN
+CORS_ALLOWED_ORIGINS=https://$INJECT_DOMAIN
-```
# uncomment and set appropriate values email to enable sending of AAI mails
# INJECT_EMAIL_HOST=
# INJECT_EMAIL_PORT=
@@ -64,90 +72,34 @@ The settings for sending emails is configured via the following environment vari
# INJECT_EMAIL_HOST_PASSWORD=
# INJECT_EMAIL_SENDER_ADDRESS=
# INJECT_EMAIL_PROTOCOL=
-```
+INJECT_HOMEPAGE=https://${INJECT_DOMAIN}/
+# redirect logs to the `data` directory
+INJECT_LOGS=data/backend-logs.log
-- INJECT_EMAIL_HOST: SMTP server address for sending emails.
-- INJECT_EMAIL_PORT: Port for the SMTP server. Port must be always set.
-- INJECT_EMAIL_HOST_USER: Username for the SMTP server.
-- INJECT_EMAIL_HOST_PASSWORD: Password for the SMTP server.
-- INJECT_EMAIL_SENDER_ADDRESS: Email address used as the sender for outgoing emails.
-- INJECT_EMAIL_PROTOCOL: Preferred protocol for communication with SMTP server.
- The choices (values) can be _ssl_ or _tls_ (case-insensitive).
- This variable can also be left undefined - no encryption will be used.
- Please note, that setting of `INJECT_EMAIL_PROTOCOL` does not automatically set the port and port must be always set.
-- INJECT_EMAIL_TIMEOUT: Specifies a timeout in seconds for blocking operations tied to emails like the connection attempt to SMTP.
- The default value is 10 seconds.
+# inject postgres DB host, this HOST is preset to hostname as set in compose.yml
+INJECT_DB_HOST=inject-postgres
-#### Logging and Debugging
-
-The backend logs various actions and possible errors in a special log file.
-The location of the logfile can be changed by setting the `INJECT_LOGS` variable to a new path to a _file_.
-This path is relative from the `/backend` directory in the Docker container.
-
-```
-# enable logging to a specific file
-# INJECT_LOGS=data/backend-logs.log
-```
-
-- INJECT_LOGS: Path to the log file. Set to `backend-logs.log` by default.
-
-#### Host and Connection Settings
-
-These parameters are set up by default in the `.env` file, it's advised to not modify them,
-unless you want to specifically modify how IXP interacts with Frontend and Backend.
-Individual Docker compose setups these settings setup accordingly to the set level of communication.
-
-```
-# host parameters that should be set up for the client and server to interact correctly
-INJECT_HOST_ADDRESSES=$INJECT_DOMAIN
-VITE_HTTPS_HOST=$INJECT_DOMAIN
-CORS_ALLOWED_ORIGINS=https://$INJECT_DOMAIN
-```
-
-- INJECT_HOST_ADDRESSES: Comma-separated list of addresses where the backend can be reached.
- Misconfiguration may lead to an inaccessible Backend instance.
-- VITE_HTTPS_HOST: Defines the HTTP/S host for which the frontend application should connect to,
- the hostname should point to an instance of Backend application.
-- CORS_ALLOWED_ORIGINS: Comma-separated list of origins allowed for Cross-Origin Resource Sharing (CORS).
- Example value: `https://inject.muni.cz,https://alternative-inject.muni.cz`.
- Implicitly set-up values by backend include: `http://localhost:5173`, `http://127.0.0.1:5173`, `http://localhost:8000`, `http://127.0.0.1:8000`.
- Misconfiguration may lead to issues stemming from CORS policies setup in the web browser.
-
-#### Database settings
-
-```
-INJECT_DB_PASS=a-reasonably-secure-and-long-password
+# database authentication settings, please setup appropriate and secure password in INJECT_DB_PASS
INJECT_DB_USER=inject
-```
-
-- INJECT_DB_PASS: PostgresSQL user password for which the IXP Backend has to log in to
-- INJECT_DB_USER: PostgresSQL username for which the IXP Backend has to log in to
-
-#### Redict settings
+INJECT_DB_PASS=a-reasonably-secure-and-long-password
-```
+# redict settings, used from backend v2.4.0
INJECT_REDICT_HOST=inject-redict
-```
-
-- INJECT_REDICT_HOST: Host address where Redict is served.
-#### Backend settings
-
-```
+# set the number of workers for backend
+# it is recommended to use 2 x CPU_COUNT number of workers
+# used from backend v2.5.0
INJECT_WORKER_COUNT=4
```
-- INJECT_WORKER_COUNT: Number of workers to use for deployment.
- If unspecified, uses only 1 worker.
- It is recommended to use `2 x CPU_COUNT` number of workers.
+## Backup
-## Good practices
+It's advised to back up:
-At current state it's advised:
-- to back up data located in `inject-data` and `inject-pgdata` volume
-- to back up `INJECT_SECRET_KEY`, 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
+- 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>
[← Installation overview](./overview.md){ .md-button }