Development

For development, we have configured development containers as docker compose services. You can launch them in the background, then attach to them to open files, run tests or else from your IDE.

Warning

VS Code devcontainer.json configurations are not working though. Development containers need to be launched manually for now.

We have added a pre-commit hook to make sure following tests pas before validating a commit:

backend linters: make backend-lint
doc build: make doc

Also the Gitlab CI/CD pipeline publish the following:

documentation

You can activate it by copying it in the .git/hooks/ directory:

cp pre-commit ./git/hooks/.

Note

Even if it is bad practice, you can bypass the pre-commit hook with the following commit command: git commit –no-verify

Whole stack

A docker compose configuration is available at .devcontainer. For now, it can only be launched by going to that directory and running docker compose:

docker compose up -d

It will run the whole stack in development mode, binding the code to the development containers. For the moment, only the backend and worker containers are run this way.

The backend container runs uwsgi with automatic reload on source code changes. So does the worker container with the celery worker (using watchdog`).

Note

The container does a copy of the backend folder, and updates if any change is applied to that folder. You will need to supply it with a working instance/config.py. The repository supplies one as an example in instance-example/config.py that is working with the dev containers. You will also need to create the PostgreSQL tables and build the sandbox docker image (if you need to test it) yourself. See backend-entrypoint.sh for a complete list of installation commands run by the production backend on startup. You can use the command docker compose exec backend /bin/bash to open a terminal on the development backend.

It uses a different docker image than the production one, and uses a non-root user called “non-root” to be mapped with the local user when mounting workspace in the container (with UID 1000).

If your local user is not the UID 1000, you will need to customize the docker-compose.yml file. To that end simply modify:

the USER_UID build argument in the devcontainer docker compose file (in the 3 containers that have it)

The global architecture in development is different from the production one because of the frontend. In production mode, the built version is used, so nginx and frontend are packed up in the web container. In development mode, a dev server is launched, which permits to do automatic reload on source code changes. Because of that, web container is replaced by two other containers :

nginx: Runs the reverse proxy, putting frontend and backend servers behind it (port: 80)
frontend: Runs the dev server of the frontend (port: 5173)

Backend

A docker compose configuration is available at backend/.devcontainer. For now, it can only be launched by going to that directory and running docker compose:

docker compose up -d

It will run only the backend software in its development state, binding the api code with the code present in your local workspace. The backend container is the main one and simply launches the backend with flask and serves it on port 5000.

Note

Warning

The flask application serves the backend directly on / (no /api prefix), and on port 5000.

Warning

The flask command running on the backend container will relaod when detecting changes to the source code. The celery worker will reload too (thanks to the watchdog wrapping it).

It uses a different docker image than the production one, and uses a non-root user called “non-root” to be mapped with the local user when mounting workspace in the container (with UID 1000).

If your local user is not the UID 1000, you will need to customize the docker-compose.yml file. To that end simply modify:

the USER_UID build argument in the devcontainer docker compose file (in the 3 containers that have it)

Frontend

The container does a copy of the frontend folder, and updates if any change is applied to that folder. You will need to supply it with a working instance/config.json in the frontend folder. The repository supplies one as an example in instance-example/config.json that is working with the dev containers.

Also, the dev server rebuild at any change in this folder, which permits to have a fluid dev loop. Refresh the web page to see those changes.

The frontend is using vite.js to build the prod version and to create the dev server. By default, the port used by vite.js for the dev server is 5173.

Because it has to serve a dev server instead of a built version of the frontend, nginx container is using a different configuration file in dev mode: nginx_dev.conf.

Error

There is no docker-compose.yml file for the frontend/.devcontainer. It is complicated to test a frontend when there is no functional backend.

If, in the development, it is needed to have a standalone container for the frontend, you can still create your own, using this modified extract from .devcontainer/docker-compose.yml:

services:
    frontend:
        build:
            context: ../../
            dockerfile: .devcontainer/dev/Dockerfile
        restart: always
        ports:
            - <YOUR_PORT>:5173
        volumes:
            - ../../src:/frontend/src:cached