Provision rooms on request
Part of Upgrading an existing stack.
Walk this rung with the v0.20 skill release —
its generator produces the rung's end state. The stack being upgraded names
the release that generated it in its own [tool.soliplex-template] manifest —
use that one when climbing from an older shape.
This rung moves the stack to soliplex 0.89 and haiku.rag-slim 0.104.0,
and adds the room provisioner. What changes:
- the releases: soliplex
0.87.0to the moving0.89image tag, and the ingester fromhaiku.rag-slim0.101.0to0.104.0; neither brings a RAG store migration, and the backend migrates its own databases on startup - the web client: frontend
0.110to0.114 - the image builds freeze the soliplex image's packages as version pins, so an extra package that depends on soliplex installs
- room uploads move from
backend/uploads/to a top-leveluploads/ - the room provisioner: a
soliplex-provisionerservice, the provisioned rooms' clone undersrc/rooms-provisioned, their sharedprovisioned_ragagent, and their database fragments, which the ingester includes - healthchecks check starting services every 2 seconds
- in stacks with Gitea, its settings for the concierge's tracking issues
Skip the steps that do not apply. Each names what the current template has; compare against a stack the rung's release generates.
-
Stop the stack with
docker compose down, and back up the Postgres databases andrag/db/(see Before you start). -
Bump the releases.
- the
FROMline inbackend/Dockerfile:soliplex-postgres:0.87.0becomessoliplex-postgres:0.89(and intui/Dockerfile, if the stack ships the TUI,soliplex-tui:0.89) - the ingester image in
docker-compose.yml(the&haiku_rag_imageanchor):haiku.rag-slim:0.101.0becomeshaiku.rag-slim:0.104.0 - the
FROMline innginx/Dockerfile:frontend-web:0.110becomesfrontend-web:0.114 - the manifest in
pyproject.toml:soliplex_image_tag = "0.89",soliplex_dev_constraint = ">= 0.89, < 0.90",haiku_rag_version = "0.104.0"andfrontend_version = "0.114" - the
soliplexrequirement in the root and packagepyproject.tomlfiles:>= 0.89, < 0.90; then runuv lockin each project
- the
-
Freeze the image's packages as version pins. In
backend/Dockerfile, and twice insoliplex-dev/Dockerfile, the constraints step changes fromto
-
Move room uploads to the top level.
Then, in
docker-compose.yml:- in the
backendservice, the uploads bind'ssource: "backend/uploads"becomessource: "uploads" - in the
soliplex-devservice,./backend/uploads:/uploads/becomes./uploads:/uploads/
And in
.gitignore, the fourbackend/uploads/...lines become: - in the
-
Update
backend/environment/installation.yaml.-
The
URL_SAFE_TOKEN_SECRETsecret reads the stack'surl_safe_token_secretDocker secret first, so the backend and the provisioner sign and verify service tokens with one key. Add this source above itsenv_varsource: -
Add the provisioned rooms' agent to
agent_configs, before thetitleentry (with the stack's own chat model): -
Add the provisioned rooms' clone to
room_paths:
-
-
Let the ingester include the provisioned rooms' fragments. In
haiku.rag/haiku.rag.yaml, add, after theingester:section:lancedb: databases: haiku.rag: /data/haiku.rag.lancedb databases_include: rooms-provisioned/databases.dIf the file has a
lancedb.databasesmap already (see Ingesting multiple databases), keep it, and make sure it lists every database iningester.databases,haiku.ragincluded: haiku.rag requires that once the fragments place theirs. -
Give
soliplex-devthe provisioner. Insoliplex-dev/Dockerfile, afterFROM backend:and, after
USER root:RUN apt-get update && \ apt-get install -y --no-install-recommends git && \ rm -rf /var/lib/apt/lists/* RUN --mount=from=uv,source=/uv,target=/usr/local/bin/uv \ --mount=type=cache,target=/root/.cache/uv \ uv pip list --format freeze --python /app/.venv/bin/python \ > /tmp/base-constraints.txt && \ uv pip install --python /app/.venv/bin/python \ --constraints /tmp/base-constraints.txt \ "$SOLIPLEX_TEMPLATE" -
Wire the provisioner into
docker-compose.yml.-
In the
soliplex-devservice, name itsbuild,secretsandvolumeswith anchors, so the new service can share them; add theingester_bearersecret; and mount the ingester's config read-only:build: &soliplex_dev_build context: soliplex-dev additional_contexts: backend: "service:backend" secrets: &soliplex_dev_secrets - agui_db_password - authz_db_password - url_safe_token_secret # The room provisioner's credential for the ingester's '/reload'. - ingester_bearer volumes: &soliplex_dev_volumes - ./backend/environment:/environment/ - ./backend/sandbox/workdirs:/sandbox/workdirs - ./uploads:/uploads/ - ./rag/db:/db # src/ read-WRITE; the backend mounts the same tree read-only. - ./src:/app/src # The ingester's config: the room provisioner checks that it # includes the provisioned rooms' database fragments. - ./haiku.rag/haiku.rag.yaml:/app/haiku.rag.yaml:ro -
Add the
soliplex-provisionerservice, aftersoliplex-dev:soliplex-provisioner: build: *soliplex_dev_build env_file: ".env" user: "${PUID:-1000}:${PGID:-1000}" working_dir: /app/src command: - /app/.venv/bin/uvicorn - --factory - soliplex_template.provision_service:create_app - --host=0.0.0.0 - --port=8090 depends_on: postgres: condition: service_healthy healthcheck: test: - "CMD" - "python" - "-c" - "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8090/ok', timeout=5).status == 200 else 1)" interval: 30s timeout: 10s retries: 4 start_period: 60s start_interval: 2s restart: unless-stopped secrets: *soliplex_dev_secrets environment: *backend_environment volumes: *soliplex_dev_volumes -
In the
haiku-ingesterservice's volumes (the&haiku_rag_volumesanchor, which the one-shothaiku-ragservice shares), add the provisioned rooms' clone and the room uploads: -
Check starting services often: add to the
backendhealthcheckand to the
postgreshealthcheck -
In stacks with Gitea, add to the
giteaservice'senvironment(afterGITEA__server__ROOT_URL):GITEA__server__PUBLIC_URL_DETECTION: "legacy" GITEA__attachment__ALLOWED_TYPES: ".avif,.cpuprofile,.csv,.dmp,.docx,.fodg,.fodp,.fods,.fodt,.gif,.gz,.jpeg,.jpg,.json,.jsonc,.log,.md,.mov,.mp4,.odf,.odg,.odp,.ods,.odt,.patch,.pdf,.png,.pptx,.svg,.tgz,.txt,.webm,.webp,.xls,.xlsx,.yaml,.yml,.zip"Gitea then builds its links from
ROOT_URLwhichever host a request came through, and accepts the concierge'suser-profile.yamlattachments.
-
-
Create the provisioned rooms' clone directory, so Docker does not create the ingester's bind-mount source owned by root:
The stack's
.gitignorealready ignores everything undersrc/but its own project; the provisioner makes the directory a git repository of its own. -
Rebuild and start.
(Add
tuito the build in stacks that ship it.) Thesoliplex-devandsoliplex-provisionerbuilds installsoliplex-template[provisioner]0.20 from PyPI.If the web client then stops at "probing providers", it is holding credentials stored by the old client: clear the browser's site data for the stack's address, and reload.
-
In stacks with Gitea, provision its rooms repository. Run the stack's Gitea setup again: it is idempotent, and it now also creates the private
soliplex-admin/rooms-provisionedrepository the provisioner pushes to, and the tracking repository's provision-status labels. It rotates the service account's token, so recreate the services that read.envafterwards: -
Admit the provisioner, in auth-mode stacks. The provisioner calls the backend with service tokens whose subject is
soliplex-provisioner; admit them as an admin once (see Room provisioning):docker compose run --rm --quiet-build soliplex-dev \ /app/.venv/bin/soliplex-cli admin-users add /environment \ --json-path '$[?$.sub == "soliplex-provisioner"]'Until this entry exists,
soliplex-provisionerreports unhealthy: its/okanswers503, naming the problem, and its log names theadmin_usersentry it needs. It rechecks its access every 15 seconds, so it turns healthy without a restart.To let users other than admins request rooms through the provisioner service, write a policy for the reserved room id
__provision__(see The provisioner service). -
Check it. Then provision a test room, and check that it is live:
Commit.