Move to soliplex 0.85¶
Part of Upgrading an existing stack.
Walk this rung with the v0.18b1 skill release — its generator produces the rung's end state (Soliplex 0.85 built from PyPI; uv add-shaped). 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 section keeps the stack's PyPI-built backend/Dockerfile; only versions
and configuration shapes change. Skip the steps that do not apply.
-
Raise the soliplex pin, everywhere the stack has one:
-
backend/constraints.txt, andtui/constraints.txtif the stack has the TUI: -
the
soliplexentry in the rootpyproject.toml'sdependencies("soliplex >= 0.85, < 0.86"); - the
soliplexrequirement insrc/<package>/pyproject.toml. That is your own library, so check rather than overwrite: if the range it gives does not admit0.85, raise it to>= 0.85, < 0.86.
Then refresh both lock files and the host environment, so host-side work runs 0.85 from here on:
Expect large lock diffs: the new soliplex pulls in a newer dependency tree.
-
-
Add
bubblewrapto theapt-get installlist inbackend/Dockerfile, whether or not any room uses the sandbox skill yet: soliplex 0.84 and later refuse a room configuring that skill unlessbwrapcan run, and the current template always installs it. (A stack going on to section 2 replaces this Dockerfile there, so it may skip this step.) -
Bump the haiku.rag image to
ghcr.io/ggozad/haiku.rag-slim:0.96.1, in both places it appears: theFROMline ofhaiku.rag/Dockerfile, and thehaiku-ingesterservice'simage:indocker-compose.yml(in newer stacks that line also carries an&haiku_rag_imageanchor; keep it). soliplex 0.85 requireshaiku.rag-slim >= 0.96.1, < 0.97, and the ingester writes the stores the backend reads. Record the new version in the manifest:The template's two
haiku.rag.yamlfiles need no changes between haiku.rag 0.82 and 0.96.1. For a later bump, check haiku.rag's release notes for configuration changes. -
Bump docling-serve to
v1.32.0, indocling-serve/Dockerfileand thedocling-serveservice'simage:(and the commented GPU alternatives beside each). It goes with the haiku.rag bump:v1.32.0carries the docling stack haiku.rag 0.83 and later pin. It changes no stored data, but it does change how documents re-ingested from now on are chunked, and so their chunk ids; see Converter bumps. -
Rename the database settings (stacks from before soliplex 0.82, whose
installation.yamlstill hasthread_persistence_dburi:). Each section gets a new name, and its keys a_dburisuffix:thread_persistence_db: sync_dburi: "postgresql+psycopg://soliplex_agui:secret:AGUI_DB_PASSWORD@postgres/soliplex_agui" async_dburi: "postgresql+asyncpg://soliplex_agui:secret:AGUI_DB_PASSWORD@postgres/soliplex_agui" authorization_db: sync_dburi: "postgresql+psycopg://soliplex_authz:secret:AUTHZ_DB_PASSWORD@postgres/soliplex_authz" async_dburi: "postgresql+asyncpg://soliplex_authz:secret:AUTHZ_DB_PASSWORD@postgres/soliplex_authz"Rename the commented SQLite alternatives (
#sync:,#async:) the same way, so uncommenting one later does not bring the old spelling back. Keep your own role and database names if they differ. (Section 2 later switches theasync_dburidriver topsycopg.) -
Update sandbox rooms. List the rooms that configure the sandbox skill:
soliplex 0.84 flattened the skill's settings, and rejects the old keys, so in each room listed:
Before After default_environment: "bare"environment: "bare"allowed_environments: [...](gone: the room runs one environment, and the model does not choose it) sandbox_config:→execution_timeout_seconds: 30execution_timeout_seconds: 30.0(top level)sandbox_config:→max_output_chars: 100000max_output_chars: 10000(top level) -
Add the sandbox
security_optblock to thebackendservice indocker-compose.yml, after itsuser:line (where the template has it), andsecurity_opt: *sandbox_security_opttosoliplex-devif the stack has one. Add it live if a room from step 6 is to run code:security_opt: &sandbox_security_opt - seccomp=unconfined - apparmor=unconfined - systempaths=unconfinedand commented out otherwise, as a stack generated today without the sandbox carries it, so opting in later means uncommenting it:
#security_opt: &sandbox_security_opt # - seccomp=unconfined # - apparmor=unconfined # - systempaths=unconfinedadd_room.pychecks for the live block, and refuses to add a sandbox room to a stack without it. Record the choice in the manifest's[tool.soliplex-template.params]table, besideinclude_tui:Configuration explains what the block lifts and why.
-
Add the one-shot
haiku-ragservice ifdocker-compose.ymllacks it:migrate_rag_dbs.pyruns on it. It shares the ingester's settings through YAML anchors, so first name four of thehaiku-ingesterservice's own keys, the ones directly underhaiku-ingester:at its four-space indent (other services have keys of the same names; leave those alone):haiku-ingester: image: &haiku_rag_image ghcr.io/ggozad/haiku.rag-slim:0.96.1 # ... volumes: &haiku_rag_volumes # ... environment: &haiku_rag_environment # ... ulimits: &haiku_rag_ulimitsthen add the service after it:
haiku-rag: profiles: ["tools"] image: *haiku_rag_image build: context: haiku.rag dockerfile: Dockerfile entrypoint: - sh - -c - | export INGESTER_DB_PASSWORD="$$(cat /run/secrets/ingester_db_password)" exec haiku-rag --config /app/haiku.rag.yaml "$$@" - haiku-rag volumes: *haiku_rag_volumes environment: *haiku_rag_environment user: "${PUID:-1000}:${PGID:-1000}" secrets: - ingester_db_password ulimits: *haiku_rag_ulimitsCheck it by running the CLI on it. It is held out of
docker compose upby its profile, so plaindocker compose configdoes not list it, butrunenables the profile itself; against the new haiku.rag image this also reports any store migrations step 11 will apply: -
Tag the current backend image, then rebuild. The tag keeps the old image to return to if the upgrade goes wrong;
<project>is thename:at the top ofdocker-compose.yml:docker tag <project>-backend:latest <project>-backend:pre-soliplex-0.85 docker compose build --no-cache backend docker compose build haiku-ingester docling-serve(and tag and rebuild
tuithe same way, if the stack has it).--no-cachematters: the backend resolves soliplex from PyPI in a cached layer, and without it Docker can reuse a layer an earlier build resolved, silently installing an older0.85.xthan the newest. To roll back, switch back to your usual branch and tag the old image aslatestagain; a database already migrated (step 10) also needs its backup restored. -
Migrate the Soliplex databases, with only Postgres running (the script runs the rebuilt backend image in a throwaway container, and refuses while the backend service is up). Databases created by soliplex 0.81 or earlier carry no Alembic stamp, and the backend refuses to start on them until stamped:
docker compose up -d --wait postgres uv run scripts/migrate_soliplex_dbs.py --check uv run scripts/migrate_soliplex_dbs.pyStamping prints the bootstrap script's own advice to run
soliplex-cli database upgrade; the script then runs it itself, so there is nothing to do by hand. A second--checkshould report both databases at head.Do this before section 2. Releases of the script up to soliplex-template 0.17.x fetch soliplex's stamping step with
curlinside the backend image, which this PyPI-built image has and the release images do not. -
Migrate the RAG stores, with the ingester still stopped:
haiku.rag prints a warning that it is outdated, naming a newer release; ignore it, since soliplex 0.85 requires a release below
0.97.rag/db/is ignored by git, so this step leaves nothing to commit. -
Bring the stack up (
docker compose up -d), Check it, and commit.
Database migrations covers both migration scripts, and what their reports mean, in full.