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 and built with Antora. 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 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:

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:

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 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:

uv run --env-file=.env pytest

Docker

The project provides a Dockerfile which builds a production-ready container image. It uses Caddy to serve static files and connect to Gunicorn, the Python WSGI application server.

Building:

docker build -t local/servala-portal .

Running:

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 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 helps us to automate the process.

To cut a new release run the following command to check what will happen:

uv run bumpver update -d

The run the following command to create a release:

uv run bumpver update

Maintenance and management commands

You can interface with the Django server and project by running commands like this:

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.