Skip to content

Move to soliplex 0.93

Part of Upgrading an existing stack.

Walk this rung with the v0.24 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.

uv run <skill>/scripts/skill_versions.py upgrade v0.24

This rung moves the stack to soliplex 0.93, haiku.rag-slim 0.112.0 and the 0.117 web client. What changes:

  • the releases: soliplex from the moving 0.89 image tag to 0.93, and the ingester from haiku.rag-slim 0.104.0 to 0.112.0; soliplex brings two Alembic migrations (thread labels in 0.92, full-text thread search in 0.93), which the backend applies itself on startup, and haiku.rag brings no RAG store migration
  • docling-serve: v1.38.0 to v1.38.2, the release haiku.rag 0.107 and later pair docling with
  • the web client: frontend 0.114 to 0.117, whose thread labels and thread search need soliplex 0.92 or later, so bump the two together
  • the image builds bind-mount the requirements files instead of copying them into /tmp: a COPY --link into /tmp leaves it mode 0755 under Docker's containerd image store, the default for new Docker 29 installs, which breaks apt in the soliplex-dev build and temporary files at run time
  • the soliplex-template floor in soliplex-dev/Dockerfile is >=0.22, as rung 9 set it; stacks generated by v0.22 or v0.23 still say >=0.21
  • the session key (SESSION_MIDDLEWARE_TOKEN) is a generated Docker secret, so sessions survive a backend restart; before, it fell back to a random value on every start
  • the sample bare-bones filesystem skill gains a body line, so soliplex-cli audit no longer flags it as having no instructions

Skip the steps that do not apply. Each names what the current template has; compare against a stack the rung's release generates.

  1. Stop the stack with docker compose down, and back up the Postgres databases and rag/db/ (see Before you start): this rung migrates both Soliplex databases.

  2. Bump the releases.

    • the FROM line in backend/Dockerfile: soliplex-postgres:0.89 becomes soliplex-postgres:0.93 (and in tui/Dockerfile, if the stack ships the TUI, soliplex-tui:0.89 becomes soliplex-tui:0.93)
    • the ingester image in docker-compose.yml (the &haiku_rag_image anchor): haiku.rag-slim:0.104.0 becomes haiku.rag-slim:0.112.0
    • the docling-serve image in docker-compose.yml: the v1.38.0 tag becomes v1.38.2 (for example docling-serve-cpu:v1.38.2)
    • the FROM line in nginx/Dockerfile: frontend-web:0.114 becomes frontend-web:0.117
    • the manifest in pyproject.toml: soliplex_image_tag = "0.93", soliplex_dev_constraint = ">= 0.93, < 0.94", haiku_rag_version = "0.112.0", docling_serve_version = "v1.38.2", the v1.38.2 tag in docling_serve_image, and frontend_version = "0.117"
    • the soliplex requirement in the root and package pyproject.toml files: >= 0.93, < 0.94; then run uv lock in each project that has a uv.lock (usually the root only)

    The two /v0.114.0+101/ examples in nginx/nginx.conf's comments become /v0.117.0+106/; nothing else in that file changes.

  3. Bind-mount the requirements files. In backend/Dockerfile, remove the line

    COPY --link requirements.txt /tmp/requirements.txt
    

    and add a bind mount to the RUN step that reads the file, after its two existing --mount lines:

    RUN --mount=from=uv,source=/uv,target=/usr/local/bin/uv \
        --mount=type=cache,target=/root/.cache/uv \
        --mount=type=bind,source=requirements.txt,target=/tmp/requirements.txt \
        if grep -qv '^[[:space:]]*\(#\|$\)' /tmp/requirements.txt; then \
    

    Do the same in soliplex-dev/Dockerfile for requirements-dev.txt: remove its COPY --link requirements-dev.txt /tmp/requirements-dev.txt line, and add --mount=type=bind,source=requirements-dev.txt,target=/tmp/requirements-dev.txt to the RUN step that follows it. The rest of each step is unchanged; the reference stack also carries a short comment above each step saying why the file is mounted.

    In the same file, check the soliplex-template floor. Rung 9 raised it, but the v0.22 and v0.23 generators did not, so a stack they generated may still have >=0.21:

    ARG SOLIPLEX_TEMPLATE="soliplex-template[provisioner]>=0.22"
    
  4. Make the session key a generated secret. In docker-compose.yml, declare it beside the other .gen secrets at the end of the file:

        session_middleware_token:
          file: ./.secrets/session_middleware_token.gen
    

    and add - session_middleware_token to two secrets: lists: the backend service's, and the one anchored &soliplex_dev_secrets on soliplex-dev, which soliplex-provisioner and stack-init share. In backend/environment/installation.yaml, put a file_path source first in SESSION_MIDDLEWARE_TOKEN's list:

      - secret_name: "SESSION_MIDDLEWARE_TOKEN"
        sources:
          - kind: "file_path"
            file_path: /run/secrets/session_middleware_token
          - kind: "env_var"
            env_var_name: "SOLIPLEX_SESSION_MIDDLEWARE_TOKEN"
          - kind: "random_chars"
    

    Then generate the new secret; the script writes only missing files:

    uv run scripts/generate_secrets.py
    

    Sessions signed with the old random key end once more when the backend first starts with this one.

  5. Give the sample skill a body. If the stack still has the generated backend/environment/skills/bare-bones/SKILL.md, add a line after its closing ---:

    Do nothing 'til you hear from me.
    
  6. Check the configuration you changed by hand. The generated files need nothing more, but soliplex 0.91 to 0.93 refuse some older spellings:

    • installation.yaml: the top-level thread_persistence_dburi: and authorization_dburi: stanzas are gone (since 0.91); use thread_persistence_db: and authorization_db:, each with sync_dburi and async_dburi
    • room and agent configs: a system_prompt or logo_image file must resolve inside the config's own directory (since 0.92)
    • OIDC providers: accepted_azp_list still loads, but is deprecated in favor of accepted_client_ids and goes away after 0.94
    • haiku.rag hooks and metadata providers: from 0.112, only edit_document writes a document's metadata["user"]; a user key set anywhere else is dropped
  7. Rebuild the images, the profiled soliplex-dev and stack-init included:

    docker compose --profile '*' build --pull
    

    docker compose up pulls the new ingester and docling-serve images itself.

  8. Check the databases. The Soliplex databases are behind by the two migrations above; with the default configuration the backend applies them when it starts. To see what is owed first:

    uv run scripts/migrate_soliplex_dbs.py --check
    

    A stack that configured a migration policy drives its own migrations; see the migrations reference. The RAG stores need nothing: no haiku.rag release since 0.91 changed their layout, so this should report nothing to migrate:

    uv run scripts/migrate_rag_dbs.py --check
    

    One exception: haiku.rag 0.112 no longer upgrades a store recorded before 0.64. A stack that has run its migrations at every rung has none; if --check reports one, migrate it with haiku.rag 0.111.1 first, as the error message says.

  9. Start the stack with docker compose up -d, then Check it, and commit. The audit's secrets section should list SESSION_MIDDLEWARE_TOKEN OK (file_path); with random_chars instead, it also warns that the value changes on every restart, which means step 4 is incomplete.