Skip to content

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 .env as OLLAMA_BASE_URL (see step 2).
  • uv to 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:

uv run scripts/generate_secrets.py   # populates .secrets/*.gen (gitignored)

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

uv run scripts/generate_secrets.py
then
uv run scripts/generate_env.py

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

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

docker compose run --rm --quiet-build stack-init

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

docker compose up        # foreground
docker compose up -d     # detached

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:

  • list shows them, marking the one /ingester/ signs in with.
  • add adds one. The first turns authentication on: give real accounts admin rights with the soliplex-cli admin-users add command it prints.
  • remove removes one. Removing the last turns authentication off: re-run stack-init to make the no-auth user an admin again.
  • signin chooses 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:

docker compose restart nginx

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:

uv run scripts/init_gitea.py

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:

docker compose up -d backend soliplex-provisioner

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 git origin to it, and push the initial commit. It pushes over Gitea's SSH, so it needs the stack generated with gitea_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:

docker compose exec backend soliplex-tui --url http://localhost:8000

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.