Deployement

The deployement is done with Docker and Docker Compose that package everything needed in containers.

The following are thus needed on the production server:

• Docker Engine v20+
• Docker Compose v2.12+

The two Docker Compose files staging.yml and production.yml with correctly configured environment variables give the possibility to have completely separate Docker containers and volumes, so that a staging and a production environment can be run on the same machine independently.

info

The SSL/TLS encryption is not done in one of the Docker layers of this application, so you will have to do it before the traffic hits the Traefik container entry point.

To start the deployement you need to clone the repository on your server:

git clone https://gitlab.com/koena/connect-access/connect-access.git

Environment variables

Most of the configuration is done through environment variables that are loaded by Docker Compose from files in .envs/ folder.

Create the files

First you need to copy .envs/production_template/ for production and staging environments:

cd connect-access
cp -r .envs/production_template .envs/.production
cp -r .envs/production_template .envs/.staging

Fill the values

You have to fill the values for all the 5 configuration files:

Data

DATA_PLATFORM_NAME

The name of the platform that will appear publicly instead of "Connect Access".

DATA_PLATFORM_DOMAIN_NAME

The domain name of your website.

DATA_COMPANY_NAME, DATA_COMPANY_EMAIL

Your company name and email address, used when sending emails.

DATA_ADMIN_NAME, DATA_ADMIN_EMAIL

The name and email of the administrator, to send him/her emails when important errors occur.

DATA_LOGO_FILENAME

The name of the main logo in frontend/src/images/, with a recommended size of 178 x 80 pixels. If it is your own image, you have to add it there. You can let the default value for this environment variable and add your image at path frontend/src/images/logo_custom.png.

DATA_LOGO_FILENAME_SMALL

The name of the small logo in frontend/src/images/. This logo is shown in the admin panel when the menu is collapsed, and should be as square.

Django

DJANGO_SETTINGS_MODULE

The Django settings Python file used. You will probably not need to change that.

DJANGO_SECRET_KEY

A secret key that you have to generate for your application. You can take a look at the Django documentation about this, and you can find a lot of generators on the web.

DJANGO_ADMIN_URL

This is the path of your Django admin panel: yourdomain.com/[DJANGO_ADMIN_URL]/. Thanks to this, the django admin panel is more difficult to find by attackers.

DJANGO_ALLOWED_HOSTS

You can put here all the hostnames that are allowed to send requests to the Django server, separated by commas. You should mainly put here your domain names. This is useful to avoid Cross Site Scripting and Cross-Site Request Forgery attacks. You can find more information in the Django Documentation about ALLOWED_HOSTS.

DJANGO_COOKIE_SECURE

This setting is only used in the production image, and should always be True in a production environment except in specific cases like non secure end to end tests being run.

DJANGO_SERVER_EMAIL

The email address that Django will indicate as sender for error messages to admins.

DJANGO_EMAIL_HOST, DJANGO_EMAIL_USE_TLS, DJANGO_EMAIL_PORT, DJANGO_EMAIL_HOST_USER, DJANGO_EMAIL_HOST_PASSWORD,

The email configuration elements you will find from your email service provided.

WEB_CONCURRENCY

The number of Gunicorn processes spawned to handle requests. You can learn more about this feature on the Gunicorn documentation.

SENTRY_DSN, SENTRY_ENVIRONMENT,

Connect Access is configured to send error logs to Sentry, which is both an open source monitoring tool you can install, and a company running an instance of that tool. The easiest way is to create an account on sentry.io and use the free version to see if this is useful for you. SENTRY_DSN is a URL provided when you create an account, and SENTRY_ENVIRONMENT is for configuration, to make a distinction for production and staging logs for example.

REDIS_URL

In case you would like to use another Redis instance on your server.

CELERY_FLOWER_USER, CELERY_FLOWER_PASSWORD,

A random user and password for the Flower monitoring tool.

MEDIATION_REQUEST_EMAIL

The email address to which an email will be sent everytime a mediation request is created.

Docker

COMPOSE_PROJECT_NAME

This is the project name used by Docker for all containers and volumes, which can have the same names and still be independent thanks to the differing project name. You have to change this everytime you would like to install an independent version of Connect Access: to have a staging and a production instance on the same machine, but also if you run several production instances.

Postgres

POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD,

These information define the PostgreSQL database information that will be used by the backend.

POSTGRES_DB_END_TO_END

This is the database name used by the end to end tests. It is flushed everytime the tests are run. You will probably not need this if you are simply installing a staging / production server.

Traefik

APPLICATION_PORT

The port of the main entry point to the Django application. You will need to redirect the traffic coming to your server there, after handling the SSL/TLS encryption.

FLOWER_PORT

The port of the Flower container. You don't need to change it if you don't use the service.

Create merged files

You can pass only one file containing environment variables to set to docker compose so you have to merge these files everytime you change something. This can be done with the following command:

python merge_production_dotenvs_in_dotenv.py

This will create the two files .env_production and .env_staging that are simply the concatenation of the 5 separate files you configured.

Build and deploy the application

Everytime you would like to execute a command, you have to specify the correct docker compose YAML configuration file and the correct environment variables merged file.

Production

docker compose -f production.yml --env-file .env_production my_command

Staging

docker compose -f staging.yml --env-file .env_staging my_command

To build and start the application, run the following commands:

Production

docker compose -f production.yml --env-file .env_production build
docker compose -f production.yml --env-file .env_production run django python backend/manage.py migrate
docker compose -f production.yml --env-file .env_production up -d

Staging

docker compose -f staging.yml --env-file .env_staging build
docker compose -f staging.yml --env-file .env_staging run django python backend/manage.py migrate
docker compose -f staging.yml --env-file .env_staging up -d

The application will start, and listen on the port specified by the APPLICATION_PORT environment variable.

The migrate command is executed on Django to create initially the database tables.

Configuration

Once the application is running, you can configure some elements through the Django admin panel that will be available at yourdomain.com/[DJANGO_ADMIN_URL]/.

But first you need to create an admin account with the following command (you will need to indicate some basic information like your name, email address and password):

Production

docker compose -f production.yml --env-file .env_production run django python backend/manage.py createsuperuser

Staging

docker compose -f staging.yml --env-file .env_staging run django python backend/manage.py createsuperuser

With the created account you can connect to the admin panel and fill some configuration information :

Information about the organization running the mediation service

Here you can fill information about your company that will appear on the footer of the Connect Access application, in "Contact us" section.

You can also add your terms of service, that will then appear at yourdomain.com/terms-of-service.

About mediation service information

Here you can add links that will appear in the "About" section of the footer. Each entry is one link.

The link's URL have to be either an external absolute URL (beginning with http of https) that will open a new window, or a relative URL that will not open a new window and not reload the page. If you fill the "Terms of service" page content in contact information section, the page URL you use here should be terms-of-service.

Sites

In this section, add an entry for your domain name.