158 lines
No EOL
6.1 KiB
Markdown
158 lines
No EOL
6.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
docker-compose -f deploy/dev/docker-compose.yml up --build
|
|
```
|
|
|
|
The page should be available at [localhost:8080](http://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
|
|
|
|
```bash
|
|
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](https://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](https://staging.c3lf.de) |
|
|
|----------------|--------------------------------------------|
|
|
| **Branch** | testing |
|
|
| **Host** | andromeda.lab.or.it |
|
|
| **Debug Mode** | on |
|
|
|
|
This system ist automatically updated by [git.hannover.ccc.de](https://git.hannover.ccc.de/c3lf/c3lf-system-3/) 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`** |