Service graph
About this page
This documents a stack generated from soliplex-template. A generated
project ships its own copy of this page without this note.
The stack is defined in docker-compose.yml. Browsers reach every service
through nginx, which routes each path prefix to the service behind it.
In the diagrams, dashed outlines mark what is not always a stack service:
Authelia exists only once installed, and Ollama runs outside the stack.
The TUI and Gitea are dashed too: a project includes each only when generated with it.
flowchart LR
browser([Browser]) -->|"${nginx_http} / ${nginx_https}"| nginx
nginx -->|"/api/ /mcp/"| backend
nginx -->|"/ingester/"| ingester[haiku-ingester]
nginx -.->|"/authelia/"| authelia["authelia<br/>(if installed)"]
%% if:tui
nginx -->|"/tui/"| tui
tui -->|API| backend
%% endif
%% if:gitea
nginx -->|"/gitea/"| gitea
%% endif
classDef optional stroke-dasharray: 5 5
class authelia optional
%% site-only
class tui,gitea optional
%% endsite-only
Behind nginx, the services share Postgres (each with its own database) and
two stores on disk: the backend reads the RAG vector store the ingester
writes, and the ingester reads the room fragments the provisioner commits.
Both the backend and the ingester reach Ollama at OLLAMA_BASE_URL.
flowchart TB
authelia["authelia<br/>(if installed)"]
backend
ingester[haiku-ingester]
provisioner[soliplex-provisioner]
backend -.->|OIDC| authelia
backend -->|LLM + embed| ollama{{"Ollama<br/>(external)"}}
ingester -->|embed| ollama
backend -->|reads| ragdb[("rag/db<br/>(LanceDB)")]
ingester -->|writes| ragdb
ingester --> docling[docling-serve]
ingester --> rooms[("provisioned rooms<br/>(src/ clone)")]
provisioner -->|commits| rooms
%% if:gitea
provisioner --> gitea
backend --> gitea
%% endif
authelia -.-> postgres[(postgres)]
backend --> postgres
ingester --> postgres
provisioner --> postgres
%% if:gitea
gitea --> postgres
%% endif
classDef optional stroke-dasharray: 5 5
class authelia,ollama optional
%% site-only
class gitea optional
%% endsite-only
nginx
-
Serves the Flutter web frontend.
-
Reverse-proxies
/api/and/mcp/tobackend:8000. -
Reverse-proxies
/ingester/tohaiku-ingester:8765(see Ingester control plane). -
An installed Authelia provider is reverse-proxied at
/authelia/(see Sign-in: choosing and running an identity provider). -
The web client is copied in
nginx/Dockerfilefrom the publishedghcr.io/soliplex/frontend-webimage, whose tag picks the release -
Its assets sit under a
v<release-tag>/directory, whichnginx/nginx.confcaches for a year -
index.htmlis never cached, so a new release reaches browsers on their next load. -
Terminates TLS on host port ${nginx_https} with a self-signed cert.
-
Both servers include every
nginx/conf.d/*.conffragment, which skill scripts add and remove (seenginx/conf.d/README.md). nginx reads them only at start:docker compose restart nginxafter a change.
backend
Runs soliplex-cli serve /environment, from an image built on the published
soliplex release image (see Backend image & dependencies).
Authentication follows backend/environment/oidc/config.yaml: with no
OIDC provider there, the backend runs without authentication (see
Sign-in and admins). The --reload=config
flag means edits under backend/environment/ take effect without a rebuild,
and one --reload-dirs flag per project on its PYTHONPATH (this project's
own package, plus any added with src_projects.py) restarts it when their
code changes.
soliplex-dev
A one-shot task runner, not a long-running service: profiles: ["devmode"]
keeps it out of docker compose up. It exists for commands that need the
stack's config, secrets and databases and write access to the project
directories under src/.
It is built on the backend's own image (soliplex-dev/Dockerfile, with
compose passing the backend's image in as service:backend), plus every
src/ project's dev dependency group, so a project's tests run here against
the backend's versions (see
Custom Python package). It
mirrors the backend's secrets, mounts and environment — the same /app/src
paths, and the very same PYTHONPATH (a YAML alias, so the two cannot
drift). So an audit run here sees exactly what the backend sees:
The one difference is that src/ is mounted read-write (the backend
mounts the same tree read-only). Pass -w /app/src/<project> for anything
that must run from a project's own root — alembic writes into its
versions/ directory and prepends . to sys.path:
docker compose run --rm -w /app/src/soliplex soliplex-dev \
/app/.venv/bin/alembic -x soliplex.installation_path=/environment \
revision --autogenerate -m "add a column"
Any project directory under src/ works, not just a soliplex checkout.
soliplex-provisioner
The room provisioner's HTTP service (see
Room provisioning):
it creates rooms on a requester's behalf, for callers holding the stack's
url_safe_token_secret. It runs with docker compose up, listening on the
compose network only, at http://soliplex-provisioner:8090.
It shares soliplex-dev's image, secrets, environment and mounts (YAML
aliases in docker-compose.yml), including its read-write src/, where
the provisioner commits each room and its database fragment to the
provisioned-rooms clone. The ingester mounts that clone read-only, and its
config includes the fragments.
stack-init
A one-shot setup run, held out of docker compose up by
profiles: ["init"]. Run it before the stack first comes up, and again after
adding a part of the stack that brings its own setup step:
It shares soliplex-dev's image, secrets and environment. stack-init/run.sh
brings the Soliplex databases to their current schema
(soliplex-cli database upgrade), then runs every step in
stack-init/init.d/, in name order. Each step is safe to re-run.
authelia
The in-stack OIDC provider, installed after generation with
scripts/install_authelia.py and absent from stacks that never installed it
(see Sign-in: choosing and running an identity
provider). The pinned Authelia image serves its own
TLS on the HTTPS port at /authelia/, with a network alias so the backend
reaches the issuer URL directly; nginx reverse-proxies the same path for
browsers. Its state lives in the soliplex_authelia Postgres database; its
configuration is bind-mounted from authelia/ (configuration.yml, the
gitignored users.yml and notification.txt, and the committed
identifiers.yml). The service and its secrets live in a separate
fragment, compose.authelia.yaml, pulled in by a top-level include: in
docker-compose.yml.
haiku-ingester
The writer for the LanceDB at rag/db/.
Runs haiku-ingester serve --root-path /ingester with a Postgres-backed
job queue (its own soliplex_ingester database), an async worker pool,
retries + a dead-letter queue, and an HTTP control plane.
Secrets handling:
-
The service entrypoint exports
INGESTER_DB_PASSWORDandINGESTER_TOKENfrom Docker secrets files; -
The
haiku-ragconfig machinery interpolates them intohaiku.rag.yaml
There is a single-writer constraint: only one ingester per LanceDB.
Reads are safe while the stack is up; writing a store the ingester
owns needs docker compose stop haiku-ingester first.
The backend reads the same store through a bind mount. See RAG pipeline and Ingester control plane.
haiku-rag
A one-shot runner for the haiku-rag CLI, held out of
docker compose up by profiles: ["tools"] (docker compose run enables the
profile itself). It shares the ingester's image, mounts, environment and
queue-password secret, and passes whatever follows the service name straight to
the CLI:
Uses the same secrets interpolation as haiku-ingester.
docling-serve
A stateless document converter. Runs the upstream -cpu image
directly; its variant/version are chosen at generation and baked
into docker-compose.yml — re-point by editing that line and
committing (see the stack's docling-serve/README.md for the
variants, the tagging policy, and a local-build recipe).
tui
Soliplex's Textual terminal client, served
as a web app over textual-serve; nginx proxies it at /tui/, so open
https://${server_name}:${nginx_https}/tui/. The same client is bundled in
the backend image — to run it from the command line, see
Using the TUI.
postgres
Creates the stack's databases on first boot via postgres/config/init.sh:
${agui_db}(thread persistence)${authz_db}(authorization policy)-
soliplex_ingester(the haiku-ingester job queue) -
soliplex_gitea(Gitea's backing store)
Each gets a dedicated low-privilege role whose password is a Docker secret.
Init runs only on an empty data volume; to re-run it,
docker compose down -v first.
gitea
A local Gitea instance (rootless image), backed by
the soliplex_gitea Postgres database. nginx reverse-proxies it under /gitea/
on the HTTPS port — open https://${server_name}:${nginx_https}/gitea/. Its
built-in SSH and HTTP are unpublished by default; set gitea_ssh_port
(git-over-SSH clones from the host) or gitea_http_port (direct web/HTTP) to
publish. State lives in the gitea_data / gitea_config named volumes.
Provision it after first boot with scripts/init_gitea.py — see
Provision Gitea.
Two of its settings serve the concierge's tracking issues:
- it accepts YAML attachments, beside Gitea's stock types: each requester's
profile is attached as
user-profile.yaml - it builds links from its public URL, whichever host a request came
through: the backend and the room provisioner call it at
http://gitea:3000, and the issue links they show users point at/gitea/