Servala Documentation

End-user documentation for the Servala Portal, built with Zensical — a modern static site generator.

The published site lives at https://docs.servala.com.

What's in here

Path	Purpose
docs/	Documentation source (Markdown), images and styles
zensical.toml	Site configuration: navigation, theme, branding
pyproject.toml	Python project & dependency definition
uv.lock	Pinned dependency versions (managed by uv)
.forgejo/workflows/	CI: builds and deploys to S3 on push to main
site/	Build output (generated, git-ignored)

The content structure mirrors the navigation defined in zensical.toml: Getting Started, Concepts, How-To Guides, Services, Cloud Providers and API Reference.

Prerequisites

• uv for Python and dependency management
• Python >= 3.12 (uv can install this for you)
• Optionally just as a command runner (see below)

Task runner

A justfile wraps the most common commands. Run just to list them:

Command	What it does
just install	Install/sync dependencies into the local virtual env
just serve	Serve the docs locally with live preview
just build	Build the static site into site/
just clean	Remove the generated site/ output
just upgrade	Upgrade locked dependencies to their latest versions

If you'd rather not use just, the underlying uv commands are shown below.

Getting started

Install dependencies into a local virtual environment:

just install        # or: uv sync

Serve the docs locally with live preview (rebuilds on change):

just serve          # or: uv run zensical serve

Then open the URL printed in the terminal (typically http://localhost:8000).

Building

Produce the static site into site/:

just build          # or: uv run zensical build

This is exactly what CI runs before deploying.

Editing the docs

• Write content as Markdown files under docs/.
• Add new pages to the nav table in zensical.toml so they appear in the navigation.
• Place images under docs/assets/images/ and custom styles in docs/stylesheets/extra.css.

Deployment

Deployment is automated. On every push to main, the .forgejo/workflows/deploy.yaml workflow:

1. Installs dependencies with uv sync --dev
2. Builds the site with uv run zensical build
3. Syncs site/ to the configured S3 bucket with s3cmd

There is no manual deploy step — merge to main and the live site updates.

Updating dependencies

just upgrade        # or: uv lock --upgrade && uv sync

Commit the changed uv.lock afterwards.