Skip to content

Build on the soliplex release images

Part of Upgrading an existing stack.

Walk this rung with the v0.18 skill release — its generator produces the rung's end state (the 0.85 release-image shape). 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.18

From here the backend no longer resolves soliplex from PyPI: it builds on the published ghcr.io/soliplex/soliplex-postgres image, which already holds soliplex and its PostgreSQL driver. See Backend image & dependencies for how the result works.

Stop the stack first (docker compose down). The backend reloads backend/environment/ as soon as a file there changes, so a running stack would pick up step 5's edit on the old image.

  1. Note your extras. The old backend/Dockerfile installs packages with uv add. Anything on that line other than soliplex, psycopg[binary], asyncpg, textual, textual-fspicker and textual-serve is yours, and so is any pin in backend/constraints.txt other than soliplex's. Your own edits to the two files show in their history from generation to the pre-upgrade tag, which leaves out section 1's changes:

    git diff $(git rev-list --max-parents=0 HEAD) pre-upgrade \
        -- backend/Dockerfile backend/constraints.txt
    

    That takes the stack's first commit as "as generated", which holds when the generator created the repository (its default). For a stack generated with --no-git, or whose history was rewritten, compare against a reference stack instead (see the tip at the top).

    The textual packages go: the backend image no longer carries the TUI's dependencies, so a TUI run inside the backend container needs the TUI service instead (include_tui).

  2. Create backend/requirements.txt with your extras, one requirement per line: an httpx2 on the uv add line with an httpx2 >= 2.16 pin in constraints.txt becomes the single line httpx2 >= 2.16. Drop pins on packages the soliplex release already holds: the build freezes the image's own versions as constraints, so a pin that disagrees fails the build rather than moving them. With no extras, the file holds only its header:

    # Extra PyPI dependencies for this stack's backend image, one requirement per
    # line (pip requirements syntax), e.g.:
    #
    #   cowsay
    #   httpx2-kerberos >= 2.1.1
    #
    # backend/Dockerfile installs them into the soliplex image's '/app/.venv',
    # with every package the image already holds frozen as a constraint: an extra
    # may add packages, but one that needs a different version of something the
    # soliplex release pinned fails the build rather than moving it.
    #
    # Rebuild after editing: 'docker compose build backend' (add 'soliplex-dev'
    # if you use dev mode, which builds its own copy of this image).
    #
    # Local projects under src/ are not installed from here; they are mounted
    # and put on PYTHONPATH (see docs/users/custom-package.md).
    
  3. Replace backend/Dockerfile with the release-image one below. Carry over any local edits from step 1 (e.g. a COPY of vendor/).

    # syntax=docker/dockerfile:1
    #
    # Built on the soliplex release image with PostgreSQL support: '/app/.venv'
    # holds soliplex and its 'postgres' extra (pure-Python 'psycopg' over the
    # image's system 'libpq5'). Its tag picks the release: a moving
    # '<major>.<minor>' tag follows patch releases on
    # 'docker compose build --pull backend'; an exact '<major>.<minor>.<patch>'
    # pins one. Only what is particular to this stack is layered on below.
    #
    # The release image carries neither 'uv' nor 'bwrap': 'uv' is mounted for the
    # build steps that need it (never copied into the image, as upstream does),
    # and 'bwrap' is installed for the 'bubble-sandbox' skill.
    FROM ghcr.io/astral-sh/uv:0.12.18 AS uv
    
    FROM ghcr.io/soliplex/soliplex-postgres:0.85
    
    WORKDIR /app
    
    # Enable bytecode compilation for faster startup
    ENV UV_COMPILE_BYTECODE=1 \
        UV_LINK_MODE=copy
    
    # 'bwrap' for the 'bubble-sandbox' skill. Running code also needs the
    # backend's 'security_opt' in docker-compose.yml (generator: enable_sandbox).
    RUN \
      apt-get update && \
      apt-get install -y --no-install-recommends \
        bubblewrap && \
        rm -rf /var/lib/apt/lists/*
    
    # Extra PyPI dependencies for this stack, one requirement per line (see
    # requirements.txt). The soliplex image's own versions are frozen as
    # constraints, so an extra can add packages but never silently move one the
    # release pinned; an extra that needs a different version fails the build
    # instead. Skipped while the file holds only comments and blank lines.
    COPY --link requirements.txt /tmp/requirements.txt
    
    RUN --mount=from=uv,source=/uv,target=/usr/local/bin/uv \
        --mount=type=cache,target=/root/.cache/uv \
        if grep -qv '^[[:space:]]*\(#\|$\)' /tmp/requirements.txt; then \
          uv pip freeze --python /app/.venv/bin/python \
            > /tmp/base-constraints.txt && \
          uv pip install --python /app/.venv/bin/python \
            --constraints /tmp/base-constraints.txt \
            --requirements /tmp/requirements.txt; \
        fi
    
    # Bootstrap sandbox environments
    COPY --link sandbox/environments /sandbox/environments
    
    RUN --mount=from=uv,source=/uv,target=/usr/local/bin/uv \
        --mount=type=cache,target=/root/.cache/uv \
        for env_dir in /sandbox/environments/*/; do \
          if [ -f "$env_dir/pyproject.toml" ]; then \
            uv --directory "$env_dir" sync --frozen; \
          fi; \
        done
    
    # UID/GID the service runs as. Passed from docker-compose.yml (build.args),
    # which sources PUID/PGID from .env; defaults match the historical 1000:1000.
    # Aligning the image user with the host operator lets host-owned bind mounts
    # and 0600 Docker secrets be read/written without a uid mismatch. (The
    # soliplex image deliberately creates no user of its own.)
    ARG PUID=1000
    ARG PGID=1000
    RUN groupadd -g ${PGID} soliplex && useradd -m -u ${PUID} -g ${PGID} soliplex
    
    USER soliplex
    
    ENV PATH="/app/.venv/bin:$PATH"
    
    CMD ["/app/.venv/bin/soliplex-cli", "serve", "--host=0.0.0.0", "--proxy-headers", "--forwarded-allow-ips=*", "/environment"]
    
  4. Delete backend/constraints.txt.

  5. Switch the async driver in backend/environment/installation.yaml: both async_dburi values change postgresql+asyncpg:// to postgresql+psycopg://. The image ships psycopg, not asyncpg. Leave haiku.rag/haiku.rag.yaml alone: the haiku.rag image has its own driver, as the comment above its dburi says.

  6. Replace the backend's healthcheck test in docker-compose.yml. The image has no curl, so the test: entry under the backend's healthcheck: uses the venv's Python instead; keep its interval, timeout and retries:

        healthcheck:
          # The soliplex image has no curl; use the venv's stdlib instead.
          test:
            - "CMD"
            - "python"
            - "-c"
            - "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/api/ok', timeout=5).status == 200 else 1)"
          interval: 30s
          timeout: 10s
          retries: 4
    

    It takes effect when step 13 recreates the container.

  7. The TUI, if tui/Dockerfile exists: replace it with the one below, built FROM ghcr.io/soliplex/soliplex-tui at the same tag as the backend, and delete tui/constraints.txt:

    # syntax=docker/dockerfile:1
    #
    # Built on the soliplex-tui release image: soliplex plus the TUI's
    # dependencies (textual, textual-serve, textual-fspicker) in '/app/.venv'. It
    # talks to the backend over HTTP, so it needs no PostgreSQL driver. It shares
    # its tag with the backend's soliplex-postgres image, so the two always run
    # the same soliplex release.
    FROM ghcr.io/soliplex/soliplex-tui:0.85
    
    WORKDIR /app
    
    # UID/GID the service runs as (build.args from docker-compose.yml, sourced from
    # PUID/PGID in .env; defaults to the historical 1000:1000). The soliplex-tui
    # image deliberately creates no user of its own.
    ARG PUID=1000
    ARG PGID=1000
    RUN groupadd -g ${PGID} soliplex && useradd -m -u ${PUID} -g ${PGID} soliplex
    
    USER soliplex
    
    ENV PATH="/app/.venv/bin:$PATH"
    
    EXPOSE 8002
    
    CMD ["/app/.venv/bin/soliplex-tui-serve"]
    
  8. Update the stack's host-side dependencies in the root pyproject.toml. The soliplex, psycopg[binary] and asyncpg entries become one:

    dependencies = [
        "soliplex[postgres-binary] >= 0.85, < 0.86",
    ]
    

    then refresh the lock and the environment (uv lock && uv sync). Section 1 already moved the lock to 0.85, so the diff is small, mostly asyncpg dropping out. src/<package>/pyproject.toml already admits 0.85 (section 1, step 1).

  9. Update the manifest's parameters in the [tool.soliplex-template.params] table. The version parameters are renamed, soliplex_backend_constraint and soliplex_tui_constraint giving way to:

    soliplex_image_tag = "0.85"
    soliplex_dev_constraint = ">= 0.85, < 0.86"
    

    and, if section 1 did not already set them, haiku_rag_version = "0.96.1" and enable_sandbox (section 1, steps 3 and 7). Finally, so the manifest names the template the stack now matches, set its skill_source_commit and skill_generated to the upgraded skill's own source_commit and generated, from the metadata: at the top of its SKILL.md. Only a built release carries that block: the skill as it sits in the template repository has none. A skill built from a checkout with scripts/build_skill.py gets one, stamped with the checkout's HEAD, which does not cover changes not yet committed there.

  10. Watch your own package. A stack generated before the backend watched its package carries no --reload-dirs, so an edit under src/<package>/ needs a restart. Have it watched, as a newly generated stack's is:

    uv run <skill>/scripts/src_projects.py add <package>
    

    Its PYTHONPATH entry is already there (unchanged); add adds the matching --reload-dirs=/app/src/<package>/src to the serve command. Ignore its advice to bring the backend up: step 13 does that.

  11. Give soliplex-dev a build of its own (stacks whose docker-compose.yml has a soliplex-dev service). It now builds on the backend's image plus every src/ project's dev dependency group, so a project's tests run there against the backend's versions, without the backend image carrying them. Make a soliplex-dev/ directory, save the template's Dockerfile into it as soliplex-dev/Dockerfile:

    # syntax=docker/dockerfile:1
    #
    # The dev-mode 'soliplex-dev' service: the backend's own image (compose passes
    # it as the 'backend' build context, 'service:backend'), plus the 'dev'
    # dependency group of every project under src/ -- pytest and the like -- so a
    # project's tests run against the very versions the backend imports it with.
    #
    # Those are listed in requirements-dev.txt, which src_projects.py generates
    # from the projects' pyproject.toml files. They are installed with the backend
    # image's own versions frozen as constraints, as backend/requirements.txt is: a
    # dev requirement that needs a different version fails this build. Skipped
    # while the file holds only comments and blank lines.
    #
    # The 'uv' tag is the one backend/Dockerfile mounts; keep the two in step.
    FROM ghcr.io/astral-sh/uv:0.12.18 AS uv
    
    FROM backend
    
    # The backend image runs as the 'soliplex' user; installing needs root.
    USER root
    
    COPY --link requirements-dev.txt /tmp/requirements-dev.txt
    
    RUN --mount=from=uv,source=/uv,target=/usr/local/bin/uv \
        --mount=type=cache,target=/root/.cache/uv \
        if grep -qv '^[[:space:]]*\(#\|$\)' /tmp/requirements-dev.txt; then \
          uv pip freeze --python /app/.venv/bin/python \
            > /tmp/base-constraints.txt && \
          uv pip install --python /app/.venv/bin/python \
            --constraints /tmp/base-constraints.txt \
            --requirements /tmp/requirements-dev.txt; \
        fi
    
    USER soliplex
    

    then generate its requirements file from the projects' dev groups:

    uv run <skill>/scripts/src_projects.py dev-requirements
    

    and point the service's build: at it, in place of its context: backend, dockerfile: Dockerfile and args::

        build:
          context: soliplex-dev
          additional_contexts:
            backend: "service:backend"
    

    Commit both files. Step 13 builds it.

  12. Build nginx on the published web client. Instead of building the Flutter client from a release tarball, nginx/Dockerfile now copies it from the ghcr.io/soliplex/frontend-web image, already cache-busted. Replace the Dockerfile with the template's, keeping your own -subj "…" certificate subject on its openssl req line:

    # The built Soliplex web client, published by soliplex/frontend as an image
    # holding only 'build/web', already cache-busted: everything but index.html,
    # the manifest, favicon and icons sits under a 'v<release-tag>/' directory,
    # with relative URLs, so the same tree serves under any '<base href>'. Its tag
    # picks the release: a moving '<major>.<minor>' tag follows patch releases on
    # 'docker compose build --pull nginx'; an exact '<major>.<minor>.<patch>' (or
    # '<major>.<minor>.<patch>-<build>') pins one.
    FROM ghcr.io/soliplex/frontend-web:0.110 AS frontend
    
    FROM debian:trixie
    
    # UID/GID the service runs as (build.args from docker-compose.yml, sourced from
    # PUID/PGID in .env; defaults to the historical 1000:1000). Used below to own
    # the build-time self-signed TLS material and create the runtime user.
    ARG PUID=1000
    ARG PGID=1000
    
    # Install:
    # - iputils-ping for network debugging
    # - openssl for certificate generation,
    # - ca-certificates
    # - curl for healthcheck
    # - headers-more module to suppress the Server header
    RUN apt-get update && \
        apt-get install --no-install-recommends -y \
            openssl ca-certificates curl \
            libnginx-mod-http-headers-more-filter \
            libnginx-mod-http-ndk \
            libnginx-mod-http-lua && \
        rm -rf /var/lib/apt/lists/*
    
    # Generate self-signed SSL certificate
    RUN mkdir -p /etc/nginx/ssl && \
        openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
        -keyout /etc/nginx/ssl/server.key \
        -out /etc/nginx/ssl/server.crt \
        -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost" && \
        chown -R ${PUID}:${PGID} /etc/nginx/ssl
    
    ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
    ENV SSL_CERT_DIR=/etc/ssl/certs
    ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
    
    # The built web client, served from here (see nginx.conf)
    COPY --from=frontend /build/web /app/build/web
    
    # nginx configuration (nginx.conf, mime.types, error-pages) is bind-mounted
    # from the host at runtime (see docker-compose.yml), so edits don't require
    # an image rebuild.
    
    EXPOSE 9000 9443
    RUN groupadd -g ${PGID} soliplex && useradd -m -u ${PUID} -g ${PGID} soliplex
    USER soliplex
    HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
        CMD curl -f http://localhost:9000/ || exit 1
    
    CMD ["nginx", "-g", "daemon off;"]
    

    delete nginx/post-build-cache-bust.sh, which it no longer runs, and in nginx/nginx.conf replace the hashed-asset locations — in both server blocks, the HTTP one and the HTTPS one — with the one below. The image names its asset directory for the release tag, build metadata included (v0.110.0+96/), which the old pattern does not match, so without this change the assets lose their long-lived caching:

            location ~ "^/v[0-9]+\.[0-9]+(\.[0-9]+)?(\+[0-9A-Za-z.-]+)?/(.*)" {
                expires 1y;
                add_header Cache-Control "public, max-age=31536000, immutable";
            }
    

    Then, in the manifest, set frontend_version to the image tag (0.110 follows the 0.110 series) and drop frontend_release_path, which nothing reads any more.

  13. Tag the current backend image, then rebuild with --pull, so Docker fetches the release image, and bring the stack up:

    docker tag <project>-backend:latest <project>-backend:pre-release-image
    docker compose build --pull backend nginx
    docker compose up -d
    

    Tag and rebuild tui the same way if the stack has it, and add soliplex-dev to the build if the stack has that (it builds on the backend's image). Then Check it, and commit.