=========== 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: .. code:: bash 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: .. code:: bash 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 :code:`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: .. code:: bash 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:: 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 :code:`docker compose exec backend /bin/bash` to open a terminal on the development `backend`. .. 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`: .. code:: yaml services: frontend: build: context: ../../ dockerfile: .devcontainer/dev/Dockerfile restart: always ports: - :5173 volumes: - ../../src:/frontend/src:cached