servala-portal/README.md

# Servala Portal

![Servala Logo](/docs/modules/ROOT/assets/images/servala.png)

The Servala Self-Service Portal

## 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 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.

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

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.

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`.

## Testing

TODO