Skip to content

Upgrading an existing stack

A generated stack belongs to you. Regenerating it would throw away your rooms, prompts and configuration, and nothing yet updates one in place, so bringing an older stack up to the current template is a by-hand job. This page lists the changes in order, grouped by the template release that introduced them: find the section your stack is at, and work forward from there.

Where do I start?

Your stack What its files show Skill release to walk with Start at
generated before soliplex-template v0.16 the package sits directly under src/ (src/<package>/tools.py), with tests/ at the stack root v0.16.2 0
soliplex 0.84 or earlier backend/constraints.txt pins below 0.85 v0.18b1 1
soliplex 0.85, built from PyPI backend/Dockerfile runs uv add … soliplex v0.18 2
on the 0.85 release images backend/Dockerfile builds FROM ghcr.io/soliplex/soliplex-postgres:0.85 v0.19b1 3
soliplex 0.86.1 backend/Dockerfile builds FROM ghcr.io/soliplex/soliplex-postgres:0.86.1 v0.19b2 4
soliplex 0.87 nginx/nginx.conf rewrites other cookies' SameSite via a catch-all proxy_cookie_flags; the ingester bearer rides an INGESTER_TOKEN compose environment entry v0.19 5
soliplex 0.87, serving through nginx nginx/nginx.conf routes /ingester/; docker-compose.yml has no soliplex-provisioner service v0.20 6
soliplex 0.89, provisioning rooms docker-compose.yml has a soliplex-provisioner service but no stack-init one; nginx/nginx.conf includes nothing from conf.d/ v0.21b1 7
soliplex 0.89, with stack-init docker-compose.yml's soliplex-provisioner runs soliplex_template.provision_service:create_app v0.21 8
soliplex 0.89, with the provisioner on concierge docker-compose.yml's soliplex-provisioner runs soliplex_template.provisioner.wiring:create_app v0.22 9
soliplex 0.89, through rung 9 backend/Dockerfile builds FROM ghcr.io/soliplex/soliplex-postgres:0.89 v0.24 10

Releases without rungs

The v0.23 template introduces no rung: nothing in the generated skeleton changed, so a stack through rung 9 is current — no migration to apply. What it adds to an existing stack:

  • the opt-in in-stack Authelia provider. Install it with skills/soliplex-template/scripts/install_authelia.py: the script splices its compose.authelia.yaml include: into docker-compose.yml and writes the nginx/conf.d/authelia.conf fragment itself. It relies on the conf.d fragment directory and a stack-init service, both in place after rung 7. Manage the users it creates with skills/soliplex-template/scripts/authelia_users.py.
  • refreshed doc pointers: the generated AGENTS.md and docker-compose.yml comments name the room-provisioning docs as a directory (docs/operations/room-provisioning/service.md), where older stacks still carry the single room-provisioning.md page. Cosmetic — refresh the stack's own agent-facing docs with the next upgrade (Afterwards), or by hand.

The [tool.soliplex-template] manifest at the end of the stack's pyproject.toml records the skill commit (skill_source_commit) and date (skill_generated) that generated it, and the parameters it was generated with. (skill_version may be empty.)

Compare against a fresh stack

Each step names what the current template has. To see it in place, generate a throwaway stack with the skill release the rung walks with (see Before you start #1) and your own parameters, and diff the two; see Checking the whole stack against a reference.

Which haiku.rag pairs with which soliplex?

The two pins are not a free pair: the ingester writes the LanceDB the backend reads, so its haiku.rag-slim release must stay inside the range the pinned soliplex release declares — including for --params overrides. Every rung below names its pair; the full generated table sits in the appendix at the end of this page.

How an upgrade runs

Every upgrade on this page should follow this phased process:

  1. Prepare — "Before you start": the new skill, a clean branch, the stack stopped, the state recorded and backed up.
  2. Run the rung — the numbered section Where do I start? named for your stack's state.
  3. Check it — the shared verification checklist: the audit's database lines and a room's ask.
  4. Afterwards — restore dev mode, refresh the stack's own agent-facing docs. Still on the rung's branch.
  5. Roll out — merge the branch to main and bring the live stack up on the merged state. main carries the files; the migration steps the rung rehearsed (the queue migration, the LanceDB store upgrades, the Alembic head) run live, against the deployment's own stores and databases, in the rollout's stop-apply-restart order.

Each phase completes before the next begins: a rung is not done until it has passed Check it and its commit exists, and no rung starts with the previous one unfinished.

Before you start

  1. Upgrade the soliplex-template skill in your harness, then pick the release that matches the rung being walked: the rung's steps run the skill's scripts (src_projects.py), and its generator renders the reference stack the rung compares against. The release this page describes is the right one for the newest rung (10); earlier rungs walk with the release that generated the shape the rung lands on — the stack's own manifest (skill_source_commit in [tool.soliplex-template]) names the release that generated it, the one the rung moving from it needs.

    Every rung names a software release (v…). A rung whose end state fell between two regular releases has a pre-release cut for it (e.g. v0.18b1).

    For instance, upgrade rung #1 above specifies the v0.18b1 skill release. If that is your rung, ask your agent, e.g.:

    Set the installed soliplex-template skill to the `v0.18b1` release.
    

    or run its helper yourself (list shows the published releases, diff what a move would change; upgrade installs whichever release it is given, older or newer than the installed one — no need to pass through the newest release first):

    uv run <skill>/scripts/skill_versions.py list
    uv run <skill>/scripts/skill_versions.py upgrade v0.18b1   # e.g. rung 1
    

    The rung's scripts come from the installed release, so walking a rung with a mismatched skill runs older scripts and generates an old-template reference: a comparison against it shows nothing to change. To check that the installed skill matches this page, ask its generator for its defaults: this page's release names the image tag, where an older one names the PyPI constraint instead:

    uv run <skill>/scripts/generate_soliplex_project.py --print-defaults \
        | grep -E 'soliplex_(image_tag|backend_constraint)'
    #   "soliplex_image_tag": "0.85",
    
  2. Start from a clean git tree, on a branch of its own, so each step below is a commit you can review, and switching back to your usual branch undoes the lot. Tag the starting point too; section 2 compares against it:

    git status --short                     # should list nothing
    git switch -c upgrade-soliplex-0.85
    git tag pre-upgrade-soliplex-0.85
    

    A checkout cloned under src/ (e.g. a dev-mode src/soliplex) is its own repository, which the stack's .gitignore hides from git status, so check it separately:

    git -C src/soliplex status --short     # for each checkout under src/
    
  3. Stop the stack with docker compose down, and check that nothing is left running (a one-off docker compose run container, say):

    docker compose down
    docker compose ps -a                   # should list nothing
    

    Never down -v here: that drops the Postgres volume holding the databases this upgrade migrates. (From step 5 on, docker compose ps -a also lists a stopped postgres container, which step 5 starts and stops again; that one is expected.)

  4. Record the state of each RAG store, to compare against after the upgrade. A stack whose docker-compose.yml has the one-shot haiku-rag service runs the CLI on it:

    docker compose run --rm haiku-rag info --db /data/haiku.rag.lancedb
    

    An older stack, without that service, runs it on the ingester instead. --no-deps keeps the ingester's dependencies (Postgres, docling-serve) stopped, and -e sets the queue password the config interpolates, which run would otherwise lose along with the ingester's own command; info never opens the queue, so any value will do:

    docker compose run --rm --no-deps -e INGESTER_DB_PASSWORD=unused \
        haiku-ingester haiku-rag info --db /data/haiku.rag.lancedb
    

    Run it once per store, rag/db/<stem>.lancedb appearing in the container as /data/<stem>.lancedb. Note the haiku.rag version (db) and the document and chunk counts.

  5. Back up the data the migrations touch, into a new directory under tmp/, which the stack's .gitignore already ignores. The directory is named to the second, so a second run makes a second backup: cp -a into a directory that already exists would nest the copy inside it instead. The Postgres dumps need Postgres running, and only Postgres:

    BACKUP=tmp/backup-$(date +%Y%m%dT%H%M%S)
    mkdir "$BACKUP"
    docker compose up -d --wait postgres
    for db in soliplex_agui soliplex_authz; do
        docker compose exec -T postgres sh -c \
            'PGPASSWORD=$(cat /run/secrets/postgres_password) \
             pg_dump -h localhost -U postgres -Fc "$0"' "$db" \
            > "$BACKUP/$db.dump"
    done
    docker compose stop postgres
    cp -a rag/db "$BACKUP/rag-db"
    

    Then check the dumps: a failed pg_dump still leaves its output file behind, empty. Each should be non-empty and start with PGDMP:

    for f in "$BACKUP"/*.dump; do printf '%s: ' "$f"; head -c 5 "$f"; echo; done
    

    Use your own database names if they differ (the manifest's agui_db and authz_db).

  6. Take a dev-mode checkout off the path. If the backend's PYTHONPATH in docker-compose.yml lists a checkout providing the soliplex package (e.g. /app/src/soliplex/src), take it off for the upgrade:

    uv run <skill>/scripts/src_projects.py remove soliplex
    

    Ignore its closing advice to docker compose up -d backend: the stack stays down until the end of the section. remove also takes the checkout off the backend's watch list (its --reload-dirs), and settles an older reload mode: --reload=both becomes --reload=config, while --reload=python stays, being what turns reload on without watching the config (--reload=config would work as well).

    The checkout's code would otherwise override the soliplex the rebuilt image installs, and the migrations would ask the wrong release. Putting it back is the last step, Restore dev mode.

  7. Fetch the migration scripts if the stack's scripts/ lacks migrate_soliplex_dbs.py and migrate_rag_dbs.py (stacks generated before soliplex-template 0.17):

    for s in migrate_soliplex_dbs migrate_rag_dbs; do
        curl -fsSL -o "scripts/$s.py" \
            "https://raw.githubusercontent.com/soliplex/soliplex-template/main/scripts/$s.py"
    done
    

    Each is a PEP 723 shim: uv run provisions the soliplex-template package from PyPI, which holds the migration code itself.

  8. Read the scripts' advice with the upgrade in mind. src_projects.py and both migration scripts end by telling you to start or restart a service. Mid-upgrade, ignore that: each section says when to bring the stack up.

<skill> is wherever the soliplex-template skill is installed, e.g. ~/.claude/skills/soliplex-template. The steps below edit the manifest in a few places, although its header says not to: they are the exception, so that it describes the stack the upgrade leaves.

Follow the upgrade steps for your rung

Follow the steps listed for your upgrade rung in order. After each step, check the status of your stack's files:

git status

If there are changes, commit them with a short checkpoint commit message:

git add .
git commit -m "Step #2: <short description>"

Restore Dev mode

A stack that ran a soliplex checkout in dev mode can put it back now; add puts it on the path and watches it, like any other project. Check out the release the image runs first: the checkout supplies only soliplex's code, and its dependencies still come from the image, so a checkout far from the image's release fails at import time.

docker compose run --rm --no-deps backend soliplex-cli --version
git -C src/soliplex checkout v<the version just reported>
uv run <skill>/scripts/src_projects.py add soliplex
docker compose up -d backend

Check it

docker compose ps                    # every service running, backend healthy
docker compose run --rm --no-deps backend soliplex-cli audit /environment
ls backend/environment/rooms         # room ids, for the 'ask' below
docker compose run --rm --no-deps backend \
    soliplex-cli ask /environment <room-id> "Say hello"

For the upgrade, what matters in the audit is its database lines: both databases OK at the same Alembic revision. It can still exit non-zero for reasons of its own, such as models missing on the Ollama server (soliplex-cli ollama pull fetches them). The ask should return a reply and persist its thread. Open the frontend (http://localhost:9000 by default) for a last look.

Checking the whole stack against a reference

For more than a smoke test, generate a throwaway stack from this stack's own generation manifest, with the skill release the rung walks with, and diff the two. The manifest under [tool.soliplex-template.params] records every parameter the stack was built with, so the reference is the stack as that release's generator would scaffold it:

cd <stack>

# Build a params file from the manifest. The generator recomputes derived
# values, so they are not accepted as input -- drop them. Manifests from
# before rung 7 also record 'auth_mode = "auth"', which the generator now
# refuses (providers are added after generation), so drop that too. (If it
# rejects others, its error message names them; add those to the list.)
python3 - <<'EOF' > /tmp/ref-params.json
import json, pathlib, tomllib

manifest = tomllib.loads(pathlib.Path("pyproject.toml").read_text())
params = manifest["tool"]["soliplex-template"]["params"]
for dropped in (
    "package_name",
    "frontend_release_path",
    "backend_auth_flag",
    "docling_serve_image",
    "auth_mode",
):
    params.pop(dropped, None)
print(json.dumps(params, indent=2))
EOF

uv run <skill>/scripts/generate_soliplex_project.py \
    --out /tmp/ref-stack --params /tmp/ref-params.json \
    --no-git --no-generate-secrets

Then diff the files the rung changed, e.g. for rung 0:

diff -u /tmp/ref-stack/pyproject.toml pyproject.toml
diff -ru /tmp/ref-stack/src src

Two differences are expected and harmless: skill_source_commit and skill_generated in the manifest record your stack's generation, and the reference's are blank or current. Anything else is a real divergence.

Afterwards

The stack's own agent guide (AGENTS.md, or CLAUDE.md in older stacks) and its docs/ were written for the stack as generated, and the upgrade leaves them describing the old setup: backend/constraints.txt, the old image tags. Refresh them from a reference stack generated with your parameters (see the tip at the top), or at least treat them as out of date.

Wrap the run into main: merge the rung's branch and bring the live stack up on the merged state. What merges is the files; what rolls out is the state: the migration steps the rung rehearsed run live, against the deployment's own databases and stores.

  • In the live stack's clone, the merge is direct, and the rollout follows it in the same working tree.
  • From a separate upgrade-only clone, the clone is the rehearsal: it proved the rung's steps against copied stores and databases; push the branch and open the PR for the files, and roll out live afterwards by re-running the rung's migration steps for real.

Upgrade rungs

One page per rung:

Appendix: the generated soliplex ↔ haiku.rag-slim pairing table

The stack couples two pins — the soliplex release and the ingester's haiku.rag-slim tag — and they are not a free pair: the ingester writes the LanceDB that the backend reads, so the haiku.rag-slim release must stay inside the range the pinned soliplex release declares. The generated table below (extracted from the soliplex repo's own release tags) lists that pin for every release; the rungs pick their pairings from it.

soliplex tag requires haiku.rag-slim
v0.93 >= 0.112.0, < 0.113
v0.92.2 >= 0.111.0, < 0.112
v0.92.1 >= 0.111.0, < 0.112
v0.92 >= 0.110.0, < 0.111
v0.91.1 >= 0.108.0, < 0.109
v0.91 >= 0.108.0, < 0.109
v0.90.1 >= 0.105.0, < 0.106
v0.90 >= 0.105.0, < 0.106
v0.89.2 >= 0.104.0, < 0.105
v0.89.1 >= 0.104.0, < 0.105
v0.89 >= 0.104.0, < 0.105
v0.88.4 >= 0.101.0, < 0.102
v0.88.3 >= 0.101.0, < 0.102
v0.88.2 >= 0.101.0, < 0.102
v0.88.1 >= 0.101.0, < 0.102
v0.88 >= 0.101.0, < 0.102
v0.87 >= 0.101.0, < 0.102
v0.86.1 >= 0.101.0, < 0.102
v0.86 >= 0.98.0, < 0.99
v0.85.5 >= 0.98.0, < 0.99
v0.85.4 >= 0.97.0, < 0.98
v0.85.3 >= 0.96.1, < 0.97
v0.85.2 >= 0.96.1, < 0.97
v0.85.1 >= 0.96.1, < 0.97
v0.85 >= 0.95.0, < 0.96
v0.84 >= 0.89.0, < 0.90
v0.83.4 >= 0.87.0, < 0.88
v0.83.3 >= 0.87.0, < 0.88
v0.83.2 >= 0.87.0, < 0.88
v0.83.1 >= 0.87.0, < 0.88
v0.83 >= 0.87.0, < 0.88
v0.82.4 >= 0.84.0, < 0.85
v0.82.3 >= 0.84.0, < 0.85
v0.82.2 >= 0.84.0, < 0.85
v0.82.1 >= 0.84.0, < 0.85
v0.82 >= 0.84.0, < 0.85
v0.81.1 >= 0.84.0, < 0.85
v0.81 >= 0.84.0, < 0.85
v0.80 >= 0.84.0, < 0.85
v0.79 >= 0.82.0, < 0.83
v0.78.2 >= 0.78.0, < 0.79
v0.78.1 >= 0.78.0, < 0.79
v0.78 >= 0.78.0, < 0.79
v0.77.2 >= 0.78.0, < 0.79
v0.77.1 >= 0.78.0, < 0.79
v0.77 >= 0.78.0, < 0.79
v0.76.1 >= 0.74.0, < 0.75
v0.76 >= 0.74.0, < 0.75
v0.75.4 >= 0.73.0, < 0.74
v0.75.3 >= 0.73.0, < 0.74
v0.75.2 >= 0.73.0, < 0.74
v0.75.1 >= 0.73.0, < 0.74
v0.75 >= 0.72.1, < 0.73
v0.74.4 >= 0.72.1, < 0.73
v0.74.3 >= 0.72.1, < 0.73
v0.74.2 >= 0.72, < 0.73
v0.74.1 >= 0.71, < 0.72
v0.74 >= 0.69, < 0.70
v0.73.3 >= 0.68, < 0.69
v0.73.2 >= 0.67.3, < 0.68
v0.73.1 >= 0.67.3, < 0.68
v0.73 >= 0.67, < 0.68
v0.72.6 >= 0.68, < 0.69
v0.72.5 >= 0.67.3, < 0.68
v0.72.4 >= 0.67.3, < 0.68
v0.72.3 >= 0.67, < 0.68
v0.72.2 >= 0.66, < 0.67
v0.72.1 >= 0.65, < 0.66
v0.72 >= 0.65, < 0.66
v0.71 >= 0.64, < 0.65
v0.70.2 >= 0.63.1, < 0.64
v0.70.1 >= 0.63.0, < 0.64
v0.70 >= 0.59.0, < 0.60
v0.69.6 >= 0.55.0, < 0.56
v0.69.5 >= 0.55.0, < 0.56
v0.69.4 >= 0.55.0, < 0.56
v0.69.3 >= 0.55.0, < 0.56
v0.69.2 >= 0.55.0, < 0.56
v0.69.1 >= 0.55.0, < 0.56
v0.69 >= 0.53.0, < 0.55
v0.68.2 >= 0.51.0, < 0.52
v0.68.1 >= 0.51.0, < 0.52
v0.68 >= 0.51.0, < 0.52
v0.67.8 >= 0.48.2, < 0.49
v0.67.7 >= 0.48.1, < 0.49
v0.67.6 >= 0.48.1, < 0.49
v0.67.5 >= 0.48.1, < 0.49
v0.67.4 >= 0.48.1, < 0.49
v0.67.3 >= 0.48.1, < 0.49
v0.67.2 >= 0.48.1, < 0.49
v0.67.1 >= 0.48.1, < 0.49
v0.67 >= 0.48.1, < 0.49
v0.66.2 >= 0.47.0, < 0.48
v0.66.1 >= 0.47.0, < 0.48
v0.66 >= 0.47.0, < 0.48
v0.65 >= 0.44.0, < 0.45
v0.64 >= 0.44.0, < 0.45
v0.63.1 >= 0.44.0, < 0.45
v0.63 >= 0.44.0, < 0.45
v0.62.4 >= 0.44.0, < 0.45
v0.62.3 >= 0.44.0, < 0.45
v0.62.2 >= 0.44.0, < 0.45
v0.62.1 >= 0.43.0, < 0.44
v0.62 >= 0.42.1, < 0.43
v0.61 >= 0.42.1, < 0.43
v0.60.9 >= 0.40.0, < 0.41
v0.60.8 >= 0.40.0, < 0.41
v0.60.7 >= 0.40.0, < 0.41
v0.60.6 >= 0.40.0, < 0.41
v0.60.5 >= 0.40.0, < 0.41
v0.60.4 >= 0.40.0, < 0.41
v0.60.3 >= 0.40.0, < 0.41
v0.60.2 >= 0.40.0, < 0.41
v0.60.1 >= 0.40.0, < 0.41
v0.60.0.1 >= 0.40.0, < 0.41
v0.60 >= 0.40.0, < 0.41
v0.59.8 >= 0.38.0, < 0.39
v0.59.7 >= 0.38.0, < 0.39
v0.59.6 >= 0.38.0, < 0.39
v0.59.5 >= 0.38.0, < 0.39
v0.59.4 >= 0.38.0, < 0.39
v0.59.3 >= 0.38.0, < 0.39
v0.59.2 >= 0.38.0, < 0.39
v0.59.1 >= 0.38.0, < 0.39
v0.59 >= 0.36.3, < 0.37
v0.58 >= 0.36.3, < 0.37
v0.57 >= 0.36.3, < 0.37
v0.56 >= 0.36.0, < 0.37
v0.55.1 >= 0.36.0, < 0.37
v0.55 >= 0.36.0, < 0.37
v0.54 >= 0.35.1, < 0.36
v0.53 >= 0.34.0, < 0.35
v0.52 >= 0.34.0, < 0.35
v0.51.3 >= 0.34.0, < 0.35
v0.51.2 >= 0.34.0, < 0.35
v0.51.1 >= 0.34.0, < 0.35
v0.51 >= 0.34.0, < 0.35
v0.50.3 >= 0.34.0, < 0.35
v0.50.2 >= 0.34.0, < 0.35
v0.50.1 >= 0.34.0, < 0.35
v0.50 >= 0.34.0, < 0.35
v0.49 >= 0.33.3, < 0.34
v0.48.3 >= 0.33.3, < 0.34
v0.48.2 >= 0.33.3, < 0.34
v0.48.1 >= 0.33.3, < 0.34
v0.48 >= 0.33.3, < 0.34
v0.47.0 >= 0.33, < 0.34
v0.46.2 >= 0.33, < 0.34
v0.46.1 >= 0.33, < 0.34
v0.46 >= 0.33, < 0.34
v0.45.1 >= 0.33, < 0.34
v0.45 >= 0.33, < 0.34
v0.44.2 >= 0.30.1, < 0.31
v0.44.1 >= 0.30.1, < 0.31
v0.44 >= 0.30.1, < 0.31
v0.43.3 >= 0.30.1, < 0.31
v0.43.2 >= 0.30.1, < 0.31
v0.43.1 >= 0.30.1, < 0.31
v0.43 >= 0.30.1
v0.42.5 >= 0.29.1, < 0.30.0
v0.42.4 >= 0.29.1, < 0.30.0
v0.42.3 >= 0.29.1, < 0.30.0
v0.42.2 >= 0.29.1, < 0.30.0
v0.42.1 >= 0.29.1, < 0.30.0
v0.42 >= 0.29.1, < 0.30.0
v0.41 >= 0.29.1
v0.40.1 >= 0.28.0
v0.40 >= 0.28.0
v0.39.2 >= 0.28.0
v0.39.1 >= 0.28.0
v0.39 >= 0.28.0
v0.38 >= 0.28.0
v0.37.2 >= 0.27.1
v0.37.1 >= 0.27.1
v0.37 >= 0.27.1
v0.36.1 >= 0.26.5
v0.36 >= 0.26.5
v0.35.2 >= 0.26.5
v0.35.1 >= 0.26.5
v0.35 >= 0.26.5
v0.34.4 == 0.25.0
v0.34.3 == 0.25.0
v0.34.2 == 0.25.0
v0.34.1 == 0.25.0
v0.34 == 0.25.0
v0.33 >= 0.23.0, < 0.26dev0
v0.32 >= 0.23.0, < 0.26dev0
v0.31 >= 0.23.0
v0.30 >= 0.23.0
v0.29 >= 0.23.0
v0.28 >= 0.20.2
v0.27 >= 0.20.2
v0.26 >= 0.20.2
v0.25 >= 0.20.2
v0.24 >= 0.20.2
v0.23 >= 0.19.6
v0.22 >= 0.19.6
v0.21 >= 0.19.6
v0.20 >= 0.19.6
v0.19 >= 0.19.5
v0.18.1 >= 0.19.0
v0.18 >= 0.19.0

A two-part tag name (e.g. v0.85) is the first release of its series: later patches tag their own commits and may raise the pin (0.85 pins >= 0.95.0, < 0.96, while 0.85.4 pins >= 0.97.0, < 0.98). For the moving image tag (ghcr.io/soliplex/soliplex-postgres:0.85), the effective pairing is the newest patch's row. An out-of-range pair still generates cleanly, and only breaks at run time — so pick every haiku_rag_version from this table, not by release number, and let the post-upgrade audit (the Check it phase, above) remain the net.