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.
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.
-
Note your extras. The old
backend/Dockerfileinstalls packages withuv add. Anything on that line other thansoliplex,psycopg[binary],asyncpg,textual,textual-fspickerandtextual-serveis yours, and so is any pin inbackend/constraints.txtother thansoliplex's. Your own edits to the two files show in their history from generation to thepre-upgradetag, which leaves out section 1's changes:git diff $(git rev-list --max-parents=0 HEAD) pre-upgrade \ -- backend/Dockerfile backend/constraints.txtThat 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
textualpackages 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). -
Create
backend/requirements.txtwith your extras, one requirement per line: anhttpx2on theuv addline with anhttpx2 >= 2.16pin inconstraints.txtbecomes the single linehttpx2 >= 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). -
Replace
backend/Dockerfilewith the release-image one below. Carry over any local edits from step 1 (e.g. aCOPYofvendor/).# 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"] -
Delete
backend/constraints.txt. -
Switch the async driver in
backend/environment/installation.yaml: bothasync_dburivalues changepostgresql+asyncpg://topostgresql+psycopg://. The image ships psycopg, not asyncpg. Leavehaiku.rag/haiku.rag.yamlalone: the haiku.rag image has its own driver, as the comment above itsdburisays. -
Replace the backend's healthcheck test in
docker-compose.yml. The image has nocurl, so thetest:entry under the backend'shealthcheck:uses the venv's Python instead; keep itsinterval,timeoutandretries: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: 4It takes effect when step 13 recreates the container.
-
The TUI, if
tui/Dockerfileexists: replace it with the one below, builtFROM ghcr.io/soliplex/soliplex-tuiat the same tag as the backend, and deletetui/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"] -
Update the stack's host-side dependencies in the root
pyproject.toml. Thesoliplex,psycopg[binary]andasyncpgentries become one: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, mostlyasyncpgdropping out.src/<package>/pyproject.tomlalready admits 0.85 (section 1, step 1). -
Update the manifest's parameters in the
[tool.soliplex-template.params]table. The version parameters are renamed,soliplex_backend_constraintandsoliplex_tui_constraintgiving way to:and, if section 1 did not already set them,
haiku_rag_version = "0.96.1"andenable_sandbox(section 1, steps 3 and 7). Finally, so the manifest names the template the stack now matches, set itsskill_source_commitandskill_generatedto the upgraded skill's ownsource_commitandgenerated, from themetadata:at the top of itsSKILL.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 withscripts/build_skill.pygets one, stamped with the checkout'sHEAD, which does not cover changes not yet committed there. -
Watch your own package. A stack generated before the backend watched its package carries no
--reload-dirs, so an edit undersrc/<package>/needs a restart. Have it watched, as a newly generated stack's is:Its
PYTHONPATHentry is already there (unchanged);addadds the matching--reload-dirs=/app/src/<package>/srcto the serve command. Ignore its advice to bring the backend up: step 13 does that. -
Give
soliplex-deva build of its own (stacks whosedocker-compose.ymlhas asoliplex-devservice). It now builds on the backend's image plus everysrc/project'sdevdependency group, so a project's tests run there against the backend's versions, without the backend image carrying them. Make asoliplex-dev/directory, save the template's Dockerfile into it assoliplex-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 soliplexthen generate its requirements file from the projects' dev groups:
and point the service's
build:at it, in place of itscontext: backend,dockerfile: Dockerfileandargs::Commit both files. Step 13 builds it.
-
Build nginx on the published web client. Instead of building the Flutter client from a release tarball,
nginx/Dockerfilenow copies it from theghcr.io/soliplex/frontend-webimage, already cache-busted. Replace the Dockerfile with the template's, keeping your own-subj "…"certificate subject on itsopenssl reqline:# 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 innginx/nginx.confreplace the hashed-asset locations — in bothserverblocks, 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_versionto the image tag (0.110follows the 0.110 series) and dropfrontend_release_path, which nothing reads any more. -
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 -dTag and rebuild
tuithe same way if the stack has it, and addsoliplex-devto the build if the stack has that (it builds on the backend's image). Then Check it, and commit.