Tobias Brunner
f3762a6a35
All checks were successful
Build and Deploy Staging / build (push) Successful in 54s
Tests / test (push) Successful in 24s
Build and Deploy Staging / deploy (push) Successful in 7s
Build and Deploy Production / build (push) Successful in 56s
Build and Deploy Production / deploy (push) Successful in 18s
140 lines
4.7 KiB
Markdown
140 lines
4.7 KiB
Markdown
# Servala Portal
|
||
|
||
|
||
|
||
The Servala Self-Service Portal
|
||
|
||
Latest release: 2025.04.14-1
|
||
|
||
## Documentation
|
||
|
||
Available at https://docs.servala.com/.
|
||
|
||
The project documentation is written in [AsciiDoc](https://docs.asciidoctor.org/asciidoc/latest/) and built with [Antora](https://docs.antora.org/antora/latest/).
|
||
It's automatically packaged and deployed by the CI/CD pipeline found in `.forgejo/workflows/docs.yaml`.
|
||
|
||
Paths:
|
||
|
||
* `docs/modules/ROOT/pages`: Documentation pages
|
||
* `docs/modules/ROOT/assets/images`: Images to be included in the documentation pages
|
||
* `docs/modules/ROOT/nav.adoc`: Site navigation (new pages need to be added there)
|
||
|
||
Writing documentation is best done by running `make docs-preview` and connecting to the site at http://localhost:2020/.
|
||
The browser add-on [LiveReload - Web extension](https://addons.mozilla.org/en-US/firefox/addon/livereload-web-extension/) will help while editing with automated page reload in the browser.
|
||
|
||
## Development setup
|
||
|
||
First, copy the ``.env.example`` file to ``.env`` and adjust the settings to your needs.
|
||
Make sure to source the file before running any commands.
|
||
|
||
Then use ``uv`` to install the project and run its commands while you’re developing:
|
||
|
||
```bash
|
||
uv sync --dev
|
||
uv run --env-file=.env src/manage.py migrate
|
||
uv run --env-file=.env src/manage.py createcachetable
|
||
uv run --env-file=.env src/manage.py runserver
|
||
```
|
||
|
||
This will start the development server on http://localhost:8000.
|
||
|
||
## Configuration
|
||
|
||
Configuration happens using environment variables.
|
||
See the available parameters in `.env.example`.
|
||
|
||
## Code style and linting
|
||
|
||
Servala uses several linters / formatters to keep the project style consistent for you.
|
||
Run them like this:
|
||
|
||
```bash
|
||
uv run black src/ # Code formatting; -c to just check
|
||
uv run isort src/ # Import ordering; -c to just check
|
||
uv run djlint src/ --reformat --format-js --format-css # Format templates, JS and CSS, --check to just check
|
||
uv run flake8 src/ # Python linter
|
||
```
|
||
|
||
The repository features a [pre-commit](https://pre-commit.com/) configuration which helps to properly format the source code before committing.
|
||
It's recommended to install and use it.
|
||
|
||
### Tests
|
||
|
||
Servala is tested via pytest. Run tests like this:
|
||
|
||
```bash
|
||
uv run --env-file=.env pytest
|
||
```
|
||
|
||
## Docker
|
||
|
||
The project provides a Dockerfile which builds a production-ready container image.
|
||
It uses [Caddy](https://caddyserver.com/) to serve static files and connect to [Gunicorn](https://gunicorn.org/), the Python WSGI application server.
|
||
|
||
Building:
|
||
|
||
```bash
|
||
docker build -t local/servala-portal .
|
||
```
|
||
|
||
Running:
|
||
|
||
```bash
|
||
docker run --rm -ti -p 8080:8080 --name=servala-portal --rm --env-file .env local/servala-portal
|
||
docker exec -it servala-portal uv run src/manage.py createsuperuser
|
||
```
|
||
|
||
Then access it with http://localhost:8080/ and the Django admin with http://localhost:8080/admin
|
||
|
||
## Deployment
|
||
|
||
Deployment files are in the `deployment/kustomize` folder and makes use of [Kustomize](https://kustomize.io/) to account for differences between the deployment stages.
|
||
Stages are configured with overlays in `deployment/kustomize/overlays/$environment`.
|
||
|
||
### Staging
|
||
|
||
The code is automatically built and deployed on a push to the main branch.
|
||
See `.forgejo/workflows/build-deploy-staging.yaml` for the actual workflow.
|
||
|
||
### Production
|
||
|
||
Building and deployment for production happens when a Git tag is pushed.
|
||
See `.forgejo/workflows/build-deploy-prod.yaml` for the actual workflow.
|
||
|
||
### Versioning
|
||
|
||
We're using `CalVer` as the versioning scheme.
|
||
The tool [bumpver](https://github.com/mbarkhau/bumpver) helps us to automate the process.
|
||
|
||
To cut a new release run the following command to check what will happen:
|
||
|
||
```bash
|
||
uv run bumpver update -d
|
||
```
|
||
|
||
The run the following command to create a release:
|
||
|
||
```bash
|
||
uv run bumpver update
|
||
```
|
||
|
||
## Maintenance and management commands
|
||
|
||
You can interface with the Django server and project by running commands like this:
|
||
|
||
```bash
|
||
uv run --env-file=.env src/manage.py COMMAND
|
||
```
|
||
|
||
Useful commands:
|
||
|
||
- ``migrate``: Make sure database migrations are applied.
|
||
- ``showmigrations``: Show current database migrations status. Good for debugging.
|
||
- ``runserver``: Run development server
|
||
- ``clearsessions``: Clear away expired user sessions. Recommended to run regularly, e.g. weekly or monthly (doesn’t
|
||
need to be frequent, but otherwise, the database is going to bloat eventually)
|
||
- ``reencrypt_fields``: Run after you changed your ``SERVALA_SECRET_KEY`` or ``SERVALA_SALT_KEY`` in order to use the
|
||
new keys, and be able to retire the previous ones.
|
||
- ``make_staff_user``: Mark one or multiple users as staff users. Use ``--substring`` flag to e.g. match
|
||
entire email domains.
|
||
- ``make_superuser``: Mark one given user (by email address) as superuser.
|