C3LF System3

the third try to automate lost&found organization for chaos events. not a complete rewrite, but instead building on top of the web frontend of version 2. everything else is new but still API compatible. now with more monorepo.

Architecture

C3LF System3 integrates a Django-Rest-Framework + WebSocket backend, Vue.js frontend SPA and a minimal LMTP mail server integrated with the Django backend. It is additionally deployed with a Postfix mail server as Proxy in front of the LMTP socket, a MariaDB database, a Redis cache and an Nginx reverse proxy that serves the static SPA frontend, proxies the API requests to the backend and serves the media files in cooperation with the Django backend using the X-Accel-Redirect header.

The production deployment is automated using Ansible and there are some Docker Compose configurations for development.

Project Structure

• core/ Contains the Django backend with database models, API endpoints, migrations, API tests, and mail server functionalities.
• web/ Contains the Vue.js frontend application.
• deploy/ Contains deployment configurations and Docker scripts for various development modes.

For more information, see the README.md files in the respective directories.

Development Modes

There are currently 4 development modes for this Project:

• Frontend-Only
• Backend-API-Only
• Full-Stack-Lite 'dev' (docker)
• [WIP] Full-Stack 'testing' (docker)

Choose the one that is most suited to the feature you want to work on or ist easiest for you to set up ;)

For all modes it is assumed that you have git installed, have cloned the repository and are in the root directory of the project. Use git clone https://git.hannover.ccc.de/c3lf/c3lf-system-3.git to get the official upstream repository. The required packages for each mode are listed separately and also state the specific package name for Debian 12.

Frontend-Only

This mode is for developing the frontend only. It uses the vue-cli-service (webpack) to serve the frontend and watches for changes in the source code to provide hot reloading. The API requests are proxied to the staging backend.

Requirements

• Node.js (~20.19.0) (nodejs)
• npm (~9.2.0) (npm)

Note: The versions are not strict, but these are tested. Other versions might work as well.

Steps

cd web
npm intall
npm run serve

Now you can access the frontend at localhost:8080 and start editing the code in the web directory. For more information, see the README.md file in the web directory.

Backend-API-Only

This mode is for developing the backend API only. It also specifically excludes most WebSockets and mail server functionalities. Use this mode to focus on the backend API and Database models.

Requirements

• Python (~3.11) (python3)
• pip (python3-pip)
• virtualenv (python3-venv)

Note: The versions are not strict, but these are tested. Other versions might work as well.

Steps

python -m venv venv
source venv/bin/activate
pip install -r core/requirements.dev.txt
cd core
python manage.py test

The tests should run successfully to start and you can now start the TDD workflow by adding new failing tests. For more information about the backend and TDD, see the README.md file in the core directory.

Full-Stack-Lite 'dev' (docker)

This mode is for developing the both frontend and backend backend at the same time in a containerized environment. It uses the docker-compose command to build and run the application in a container. It specifically excludes all mail server and most WebSocket functionalities.

Requirements

• Docker (docker.io)
• Docker Compose (docker-compose)

Note: Depending on your system, the docker compose command might be included in general docker or docker-ce package, or you might want to use podman instead.

Steps

docker-compose -f deploy/dev/docker-compose.yml up --build

The page should be available at localhost:8080 This Mode provides a minimal set of testdata, including a user testuser with password testuser. The test dataset is defined in deploy/testdata.py and can be extended there.

You can now edit code in /web and /core and changes will be applied to the running page as soon as the file is saved.

For details about each part, read /web/README.md and /core/README.md respectively. To execute commands in the container context use 'exec' like

docker exec -it c3lf-sys3-dev-core-1 ./manage.py test`

Full-Stack 'testing' (docker)

WORK IN PROGRESS

will include postfix, mariadb, redis, nginx and the ability to test sending mails, receiving mail and websocket based realiteme updates in the frontend. the last step in verification before deploying to the staging system using ansible

Online Instances

These are deployed using deploy/ansible/playbooks/deploy-c3lf-sys3.yml and follow a specific git branch.

'live'

URL	c3lf.de
Branch	live
Host	polaris.lab.or.it
Debug Mode	off

This is the 'production' system and should strictly follow the staging system after all changes have been validated.

'staging'

URL	staging.c3lf.de
Branch	testing
Host	andromeda.lab.or.it
Debug Mode	on

This system ist automatically updated by git.hannover.ccc.de whenever a commit is pushed to the 'testing' branch and the backend tests passed.

WARNING: allthough this is the staging system, it is fully functional and contains a copy of the 'production' data, so do not for example reply to tickets for testing purposes as the system WILL SEND AN EMAIL to the person who originally created it. If you want to test something like that, first create you own test ticket by sending an email to <event>@staging.c3lf.de