docs(deployment): single-container install page - #8
Open
Luca-Timo wants to merge 1 commit into
Open
Conversation
Covers the all-in-one image (PicPeak/picpeak#1042): the one-line `docker run`, when to pick it over the compose stack and when not to, first-login with the setup token, the volume layout, the minimal env reference, the external-Postgres variant, TLS, NAS notes, updating, and the limits. Written against a container built from the PR branch and run end to end — first-run wizard through to a live dashboard, then destroyed and recreated against the same volumes to confirm the persistence claims. Two things the page says that are worth flagging for review: - The wizard's own token hint prints a `docker compose exec backend …` command, which cannot work in a single-container install. The page calls that out inline rather than repeating it. The hint itself is hardcoded in the app (frontend/src/pages/SetupPage.tsx) and should probably be fixed there too. - The SMB/CIFS warning for the storage volume comes from a real production failure: the boot-time chown over an SMB mount hangs startup and leaves the container permanently unhealthy.
Luca-Timo
added a commit
to Luca-Timo/picpeak
that referenced
this pull request
Aug 16, 2026
The README had no mention of the all-in-one image, so the only way to discover it was reading the workflow file. Adds a Quick Start subsection with the one-line `docker run` and the `docker exec … cat SETUP_TOKEN` step, plus a row in the documentation table. Deliberately does not sell it as the default: the note says the compose stack is still the right choice for anything busier, gives the reason (SQLite takes one writer at a time), and points at the `.picpeak` restore as the way out, so nobody picks it and then finds themselves stuck. Full details live at docs.picpeak.app/deployment/single-container (PicPeak/docs#8).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the all-in-one image from PicPeak/picpeak#1042. Adds
app/deployment/single-container/page.mdx, a nav entry inapp/deployment/_meta.js, and a bullet on the deployment index.Covers: the one-line
docker run, when to choose it over the compose stack (and when not to), first login with the setup token, the volume layout, a minimal env reference, the external-Postgres variant, TLS, NAS notes, updating, and the limits.npm run buildpasses; the page prerenders at/deployment/single-container(77/77 static pages).Please read before merging
The volume paths in this page depend on which image lands. There are currently two open PRs for #1042 — PicPeak/picpeak#1067 and PicPeak/picpeak#1068 — and they use different layouts. This page documents #1068's (
/app/data+/app/storage, two mounts). #1067 uses a single/datamount with/data/db,/data/storage,/data/logs, which is the nicer design and the one I'd expect to win. If #1067 merges, the volume table, all threedocker runblocks and theSETUP_TOKENpath need updating — happy to push that change here, just say the word rather than merging this as-is.Everything else on the page (the SQLite-vs-Postgres guidance, the upgrade path, TLS, NAS warnings, limits) is layout-independent.
Two things worth acting on separately
frontend/src/pages/SetupPage.tsx:96hardcodesdocker compose exec backend cat /app/data/SETUP_TOKEN, repeated inen.jsonandde.json. There's no compose project and nobackendservice in a single-container install, so the first screen a new user sees offers a command that fails. The page works around it with an inline callout, but the app should probably be deployment-aware here. This affects #1067 identically.chownover an SMB-mounted storage path hangs startup and leaves the container permanently unhealthy with no login.Verification
Written against a container built from the #1068 branch and actually run — first-run wizard through to a live dashboard with System Health "Healthy", then destroyed and recreated against the same volumes to confirm the persistence claims (admin preserved, no migrations re-run). The external-Postgres variant was booted against a real
postgres:16-alpine. linux/arm64 only.