Installation
About this page
This documents a stack generated from soliplex-template. A generated
project ships its own copy of this page without this note.
This project was scaffolded by the soliplex-template generator, so most setup
is already done. Bringing the stack up takes three steps.
Prerequisites
- Docker with the Compose plugin (
docker compose version). - An Ollama server reachable from the containers, serving the models named
in
backend/environment/installation.yaml. Its URL is recorded in.envasOLLAMA_BASE_URL(see step 2). uvto run the secrets script (scripts/generate_secrets.py).
1. Generate secrets
The Postgres roles and the backend read their credentials from Docker secrets.
Generate them before the first up:
Don't hand-edit .secrets/*.gen
The script only fills missing files by default; it never rewrites an
existing one. Deleting one after the Postgres volume already exists
breaks the backend's auth to the database -- rotate the credential with
--rotate instead. See Secrets.
The generated .env records PUID / PGID — the uid/gid the containers run
as and that owns these secret files (defaulted to the operator who scaffolded
the project). If you run services as a different account, set them explicitly
and rebuild; see Secrets.
Just clone this stack from another one?
.env and the .secrets/*.gen files are gitignored, so a fresh
clone of this project (a checkout made later, run as another stack)
starts without both.
Recreate them with the generator pair as described in the project README's "First-time setup":
then2. Confirm OLLAMA_BASE_URL
The generator wrote .env with the OLLAMA_BASE_URL you supplied. Confirm it
points at your Ollama server and adjust if needed.
3. Decide whether to require sign-in
The stack starts with no OIDC provider, and so without authentication: anyone who can reach nginx uses it as Soliplex's fixed no-auth user. That is fine on a workstation; before you expose the stack, add a provider. The two ways:
- an in-stack Authelia provider, which the skill's
scripts/install_authelia.pyinstalls — see Sign-in: choosing and running an identity provider; - an external provider registered with whoever runs your IdP:
python3 <skill>/scripts/oidc_providers.py add --id <id> --title "<label>" \
--server-url <issuer URL> --client-id <client id> \
--pem-file <the provider's token-signing public key>
Adding the first provider turns authentication on; the script then prints the command that gives your own account admin rights. Adding one before the next step means the no-auth user never becomes an admin. See Sign-in: choosing and running an identity provider.
4. Prepare the databases
stack-init brings the Soliplex databases to their current schema, then
runs the setup steps in stack-init/init.d/ (see stack-init/README.md).
Every step is safe to re-run.
5. Bring the stack up
The first run builds the nginx and backend images and initializes Postgres;
it takes a few minutes. Subsequent runs are fast.
Exposed ports
| Port | Service | Purpose |
|---|---|---|
${nginx_http} |
nginx | HTTP — the web frontend |
${nginx_https} |
nginx | HTTPS (self-signed cert) |
Only nginx is published by default. Every other service binds only the
compose network; set its *_port parameter
(ingester_port, docling_port, postgres_port, backend_port,
gitea_http_port, gitea_ssh_port) to publish a host port for it.
The direct-access rows below render only for ports you published:
| ${backend_port} | backend | Soliplex backend, direct |
| ${ingester_port} | haiku-ingester | Control plane + dashboard (direct: bearer required) |
| ${docling_port} | docling-serve | Document converter |
| ${postgres_port} | postgres | Database |
| ${gitea_http_port} | gitea | Gitea HTTP (direct) -- nginx already serves the forge at /gitea/ |
| ${gitea_ssh_port} | gitea | Gitea SSH (for git-over-SSH clones from the host) |
(Container-internal ports are fixed; these are the host-published sides.)
Sign-in and admins
Authentication follows backend/environment/oidc/config.yaml. With no
auth_systems there, the backend runs without authentication, and treats
every request as Soliplex's no-auth user (phreddy@example.com).
stack-init makes that user an admin while there is no provider, so
admin-only routes such as /ingester/ admit it.
Providers come in two sorts, both added from the soliplex-template skill:
an in-stack Authelia installed with scripts/install_authelia.py and
managed day to day with scripts/authelia_users.py, or external IdPs
managed by the scripts/oidc_providers.py below. See
Sign-in: choosing and running an identity provider for
the commands and what they print.
scripts/oidc_providers.py (in the soliplex-template skill) manages the
external providers:
listshows them, marking the one/ingester/signs in with.addadds one. The first turns authentication on: give real accounts admin rights with thesoliplex-cli admin-users addcommand it prints.removeremoves one. Removing the last turns authentication off: re-runstack-initto make the no-auth user an admin again.signinchooses the provider/ingester/signs in with.
The backend picks up a change by itself. nginx reads its sign-in fragment
(nginx/conf.d/signin-provider.conf) only at start, so restart it when the
script says so:
Verify the stack
docker compose ps
<!-- ifp:ingester_port -->
curl -fsS -H "Authorization: Bearer $(cat .secrets/ingester_bearer.gen)" \
http://localhost:${ingester_port}/ingester/health
<!-- endif -->
docker compose logs -f backend
Then open http://localhost:${nginx_http} for the web frontend.
Provision Gitea
This stack includes a local Gitea, reverse-proxied at /gitea/. After the
stack is up, provision it:
This creates a rotating service account (its password is never persisted),
and writes GITEA_HOST / GITEA_ACCESS_TOKEN into .env. It also creates
the tracking repository's provision-status labels (provision-start,
provision-complete, provision-incomplete, provision-failed; see
Room provisioning). It reaches Gitea
through nginx's /gitea/, trusting only the stack's own certificate (or
through gitea_http_port, when that is set). Then recreate the services that
read .env:
Useful flags:
--admin-user NAME— also create a distinct web-UI admin login (you are prompted for its password).--push-to-gitea— register your SSH key(s), create a repo, set this stack's gitoriginto it, and push the initial commit. It pushes over Gitea's SSH, so it needs the stack generated withgitea_ssh_port.
Open Gitea at https://${server_name}:${nginx_https}/gitea/.
Using the TUI
Soliplex includes an interactive terminal client. The backend image bundles it, so you can run it against the running stack without installing anything on the host:
This stack also serves the same client as a web app via the tui service;
nginx proxies it at https://${server_name}:${nginx_https}/tui/.
Everyday commands
docker compose build <service> # rebuild one image (backend, nginx, …)
docker compose down # stop (keeps the postgres_data volume)
docker compose down -v # stop AND wipe the postgres volume
down -v is destructive
docker compose down -v drops the postgres_data volume — chat threads,
authorization grants, and the ingester's job queue (now its own Postgres
database) all go with it. The RAG vector store and your documents live
under rag/db/ (a bind mount), so they survive a down -v.