Luca
9431b9f094
* feat(setup): configure the public address and SMTP in the wizard, not .env
A fresh install could not configure its own public address. `general_site_url`
and the `email_configs` row already existed as admin settings, but nothing
could reach them:
- docker-compose.yml injected FRONTEND_URL=${FRONTEND_URL:-http://localhost:3000}
and Dockerfile.aio baked in ENV FRONTEND_URL=http://localhost:3000, so
getFrontendBaseUrl() returned on its first branch every time and the setting
was never read. .env.example shipped the same value as an uncommented
placeholder for FRONTEND_URL / ADMIN_URL / API_URL.
- the wizard never asked for the address at all, and skipped its whole config
step unless a CRM-ish feature was selected — so a gallery-only install was
also never offered SMTP, despite gallery links, guest invites and expiry
warnings all going out through email_configs.
- eleven call sites read process.env.FRONTEND_URL directly rather than the
resolver, three of them defaulting to placeholder hosts that reached real
recipients: https://app.example.com in payment-reminder emails, localhost:3005
in admin invitation emails, https://app.example.com in dev template previews.
Stop injecting a default anywhere, and resolve the origin instead:
FRONTEND_URL -> general_site_url -> the origin the request arrived on ->
whichever exists -> ''. A loopback candidate is treated as unconfigured so the
installs that already have http://localhost:3000 baked into their environment
self-heal; the same guard previously lived inline in routes/gallery.js for the
slideshow QR (#848) and is now shared. The empty return is preserved because
shareLinkService and the SSO redirects in routes/auth rely on it to emit
relative urls — callers needing an absolute url use getAbsoluteFrontendUrl(),
which still ends at http://localhost:3000.
The wizard now persists window.location.origin right after the admin account is
created, so an install that skips the rest still has a usable origin for
background jobs that have no request to derive one from, and offers it as an
editable "Public address" field. Settings -> General shows the field read-only
when FRONTEND_URL pins it, instead of silently ignoring edits.
Also drop the `|| 'mailhog'` fallback when seeding email_configs: that host only
exists in the dev compose profile (which does not even start by default), so a
fresh install came up with a live config pointing nowhere while the wizard
showed empty SMTP fields. With no row, blank fields are the truth and
emailProcessor logs "No email configuration found". Developers set
SMTP_HOST=mailhog explicitly.
backend/src/services/emailService.js is deleted: nothing in backend/ references
it, and it was the only consumer of the SMTP_* variables, which misrepresented
how mail is configured.
Refs #705
* fix(setup): keep FRONTEND_URL ahead of ADMIN_URL/APP_URL when resolving links
The previous commit routed two call sites through the resolver but put the
site-specific variable FIRST, silently reversing precedence:
userManagementService was: FRONTEND_URL || ADMIN_URL || localhost:3005
became: ADMIN_URL || resolver
adminEvents/crud was: FRONTEND_URL || APP_URL || ''
became: APP_URL || resolver
An install with both variables set would have flipped which one won. Call the
resolver first instead — it starts with FRONTEND_URL, so the original relative
order is preserved and only the final fallback changes: localhost:3005 (not
even the frontend's port) and '' (a relative link inside an email) both become
the resolved origin.
Refs #705
* fix(setup): unpin loopback FRONTEND_URL, keep ADMIN_URL/APP_URL reachable
Review feedback on #1104.
isEnvPinned() reported ANY FRONTEND_URL as authoritative, including the
loopback values getFrontendBaseUrl() deliberately demotes. An install
upgrading with the old compose default FRONTEND_URL=http://localhost:3000
therefore resolved its origin from general_site_url correctly, but got the
Site URL field rendered read-only in Settings and skipped by the wizard's
seeding - locking the exact operators this change exists to unblock out of
configuring a public address anywhere. The predicate now mirrors the
resolver, and the derived general_site_url_effective the General tab reads
comes from the same helper instead of re-normalising process.env inline.
APP_URL and ADMIN_URL had become dead code: getFrontendBaseUrl() only
returns falsy when NOTHING is configured, so `|| process.env.ADMIN_URL`
after it never ran once a site URL existed - which after this PR is the
normal case. A split-origin install pointing ADMIN_URL at a separate admin
host got invite links on the public gallery origin instead. They are now
passed as an explicit `override` that resolves directly below FRONTEND_URL,
preserving the historic FRONTEND_URL-before-ADMIN_URL order while beating
the database- and request-derived fallbacks.
general_site_url now feeds the CORS allowlist and the
Access-Control-Allow-Origin header, not just email links, so a schemeless
value is an allowlist entry no browser origin can match. Validate it
server-side in PUT /general (isURL with require_protocol, require_tld off
so LAN/NAS installs on http://nas:3000 still work) and client-side in both
surfaces that write it - type="url" never fires in either, since neither
input sits inside a form.
Two more wizard fixes: the General tab no longer reposts general_site_url
while it is env-pinned, because the field then holds the effective env
value rather than the stored one and the round-trip read as a change to a
protected key, 403ing a settings.edit-without-settings.domains admin on an
unrelated save. And SetupConfigStep validates the From address before
posting - /admin/email/config rejects a blank one, which used to surface as
a generic warning while the wizard advanced from its finally block anyway,
discarding every SMTP value the user had typed, password included. A failed
save now keeps them on the step.
* fix(setup): surface a rejected public address instead of swallowing it
Review round 2 follow-up on #1104, pushed onto the branch.
saveSiteUrl() caught and discarded every error. That was defensible before
round 2 added a server-side URL check, but PUT /general can now answer 400 —
and the two validators disagreed:
http://my_nas.local client: accepted server: rejected
http://foo_bar:3000 client: accepted server: rejected
validate() let those through, the 400 was swallowed, `failed` stayed false and
onDone() ran. The operator finished the wizard believing the public address was
stored when nothing had been. That is the silent misconfiguration this whole
change exists to remove, landing on the LAN and NAS installs it targets.
Three parts:
- saveSiteUrl() throws. finish() resolves it before anything else is posted and
puts the message on the address field rather than the generic "some settings
could not be saved" warning. Skip for now still always leaves, by contract,
but warns instead of dropping the value in silence.
- allow_underscores on the server check, for the same reason require_tld is
off: browsers resolve http://my_nas.local and the client accepts it, so
rejecting it server-side only produced the mismatch above. Both validators
now agree across the LAN/NAS, IDN, bare-IP and scheme-less cases.
- LOOPBACK_BASE_RE anchors its host token. Bare prefix matching also demoted
https://localhost-nas.example.com, and now that this predicate gates the
whole resolver rather than just the slideshow QR, being demoted means a
configured address is silently ignored. 127. stays a bare prefix on purpose:
all of 127.0.0.0/8 is loopback.
Resolver suite 31 passing, up from 26. Mutation-checked: restoring the
unanchored regex fails the three new host-boundary cases.
* fix(settings): don't lock the General tab on a site URL nobody typed
Review follow-up on #1104, pushed onto the branch.
general_site_url was free-text until this PR added a server-side check, so an
upgraded install can hold something schemeless that predates it. The tab
flagged that on load, and `disabled={!!siteUrlError}` then killed Save for
EVERY General setting.
An admin holding settings.edit but not settings.domains could not clear it
either: correcting the address is a change to a protected key and 403s. The
tab has no permission gating, so that role was simply locked out of the tab
with no self-service way back.
That is the same role adminSettings.js:85-95 documents the no-op round-trip
allowance for. The allowance only helps if the request is made, and this
blocked it in the browser first.
Validation now waits until the field is actually edited, and an unchanged
value is dropped from the payload rather than reposted — matching what the
env-pinned case already does one line above, and for the same reason.
stored value invalid, untouched Save works, key not sent
edited to something unusable Save blocked
edited to a usable absolute url saved
Four tests, first coverage for this feature. Mutation-checked: removing the
dirty gate fails the untouched-value case.
---------
Co-authored-by: Paul Nothaft <53005142+the-luap@users.noreply.github.com>
152 lines
6.0 KiB
Markdown
152 lines
6.0 KiB
Markdown
# PicPeak all-in-one (single container)
|
|
|
|
One `docker run`, one volume, working PicPeak. Built for NAS boxes (Synology,
|
|
UGREEN, QNAP) and small VPSes where standing up a four-service compose stack is
|
|
the thing that makes people give up and go back to a SaaS.
|
|
|
|
If you already run PostgreSQL, or you expect several photographers hitting the
|
|
admin UI at once, use the [compose stack](../README.md) instead. This image is
|
|
the small end of the range, not a replacement for it.
|
|
|
|
## Run it
|
|
|
|
```bash
|
|
docker run -d \
|
|
--name picpeak \
|
|
-p 3000:3000 \
|
|
-v picpeak:/data \
|
|
-e JWT_SECRET="$(openssl rand -base64 48)" \
|
|
ghcr.io/picpeak/picpeak/aio:stable
|
|
```
|
|
|
|
Open `http://<host>:3000`. The first visit lands on the setup wizard, which
|
|
asks for a one-time token:
|
|
|
|
```bash
|
|
docker exec picpeak cat /data/db/SETUP_TOKEN
|
|
```
|
|
|
|
The token is also printed to the container log on first start.
|
|
|
|
`JWT_SECRET` is the only variable you must set. Generate it once and keep it —
|
|
changing it invalidates every existing session and gallery link.
|
|
|
|
## What is inside
|
|
|
|
One Node process. No supervisor, no nginx, no PostgreSQL, no Redis.
|
|
|
|
The backend serves the built frontend directly and applies the same security
|
|
headers the nginx container applies in the compose stack — same CSP, same
|
|
`X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy` and
|
|
`Permissions-Policy`, plus the same cache tiers (hashed assets immutable,
|
|
`index.html` never cached).
|
|
|
|
**SQLite is the default**, deliberately. It is a library inside the process
|
|
writing one file on your volume: no second daemon, no credentials, no startup
|
|
ordering, and no `pg_upgrade` dance when you pull a newer image. The engine is
|
|
resolved and logged at boot, so `docker logs` always tells you which database
|
|
you are actually on:
|
|
|
|
```
|
|
Database engine: sqlite (/data/db/picpeak.db)
|
|
```
|
|
|
|
Redis is absent — nothing in the backend needs it at runtime.
|
|
|
|
## The volume
|
|
|
|
Everything that must survive a container replacement lives under `/data`:
|
|
|
|
| Path | Contents |
|
|
|---|---|
|
|
| `/data/db` | `picpeak.db` (+ `-wal`/`-shm`) and `SETUP_TOKEN` |
|
|
| `/data/storage` | originals, thumbnails, archives |
|
|
| `/data/logs` | application logs |
|
|
| `/data/backup` | built-in backup output (`/backup` is symlinked here) |
|
|
|
|
One mount point is the whole point. Back up `/data` and you have backed up the
|
|
install.
|
|
|
|
Upgrades are `docker pull` + recreate the container; migrations run at start.
|
|
The volume is what carries your data across, so never bind-mount a directory
|
|
you are about to delete.
|
|
|
|
## Environment
|
|
|
|
Only `JWT_SECRET` is required. Everything else has a working default.
|
|
|
|
| Variable | Default | Notes |
|
|
|---|---|---|
|
|
| `JWT_SECRET` | — | **Required.** Long random string. |
|
|
| `PORT` | `3000` | Listen port inside the container. |
|
|
| `FRONTEND_URL` | — | Optional override for the public URL. Normally you set this in the setup wizard instead (it proposes the address you opened), and it is editable later under Settings → General. Setting it here pins the value and makes that field read-only. |
|
|
| `SMTP_*` | — | Optional override for outbound email, which is normally configured in the setup wizard / Settings → Email. Without either, PicPeak runs fine but sends nothing. |
|
|
| `DATABASE_CLIENT` | `sqlite3` | Set to `pg` to use an external PostgreSQL. Required — the image declares `sqlite3`, and the boot resolver treats a declared client as an explicit instruction, so `DB_*` alone will **not** switch engines. |
|
|
| `DB_HOST`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` | — | Connection details, used when `DATABASE_CLIENT=pg`. |
|
|
|
|
### Using an external PostgreSQL
|
|
|
|
```bash
|
|
docker run -d --name picpeak -p 3000:3000 -v picpeak:/data \
|
|
-e JWT_SECRET="…" \
|
|
-e DATABASE_CLIENT=pg \
|
|
-e DB_HOST=10.0.0.5 -e DB_USER=picpeak -e DB_PASSWORD=… -e DB_NAME=picpeak \
|
|
ghcr.io/picpeak/picpeak/aio:stable
|
|
```
|
|
|
|
The image waits for the database to accept connections before running
|
|
migrations, exactly as the compose backend does.
|
|
|
|
## TLS
|
|
|
|
None is included. Terminate TLS in front of it — your NAS's reverse proxy,
|
|
Caddy, nginx, or a Cloudflare Tunnel. Put the public `https://…` address in
|
|
Settings → General (or re-run the setup wizard) so generated links match —
|
|
`FRONTEND_URL` does the same thing but pins it outside the admin UI.
|
|
|
|
## NAS notes
|
|
|
|
**Synology (Container Manager)** and **QNAP (Container Station)** can both run
|
|
this from the registry UI: pull `ghcr.io/picpeak/picpeak/aio:stable`, map a
|
|
host port to container port `3000`, and add one volume mapping to `/data`.
|
|
Set `JWT_SECRET` under Environment.
|
|
|
|
Point the volume at a folder on your data pool, not the system partition, and
|
|
prefer a folder you own — the container starts as root only long enough to
|
|
adopt the directory, then drops to UID 1001.
|
|
|
|
## Outgrowing it
|
|
|
|
A single-container install is never a dead end. When you need the full stack:
|
|
|
|
1. **Settings → Backup → Export `.picpeak`** (include photos).
|
|
2. Stand up the compose stack with PostgreSQL and run its setup wizard.
|
|
3. **Settings → Backup → Restore** the `.picpeak` file.
|
|
|
|
SQLite → PostgreSQL restore is supported (#1041); the reverse is not. Your
|
|
galleries, settings, customers and photos come across.
|
|
|
|
## Health
|
|
|
|
`/health` returns 200 when the database is reachable and 503 when it is not,
|
|
and the image's `HEALTHCHECK` uses it — so `docker ps` showing `healthy`
|
|
means the app can actually serve, not merely that a socket is open.
|
|
|
|
```bash
|
|
docker inspect --format='{{.State.Health.Status}}' picpeak
|
|
```
|
|
|
|
## Limits
|
|
|
|
- **SQLite means one writer.** Fine for one photographer plus guests
|
|
browsing; if several admins upload simultaneously all day, move to
|
|
PostgreSQL.
|
|
- **No built-in TLS or reverse proxy.**
|
|
- **No Redis**, so nothing here scales horizontally — run one container.
|
|
- **No face recognition.** "People in this gallery" needs a separate ML
|
|
container this image does not include, and running detection alongside
|
|
thumbnail and preview generation in one container would slow everything
|
|
down rather than fail cleanly. The toggle in Settings → Features is
|
|
disabled here and says so. Use the multi-container deployment if you want
|
|
it.
|