feat: all-in-one embedded single-container mode (#377)

Embedded Postgres 17 + Redis via s6-overlay when DATABASE_URL/REDIS_URL are unset; restores the one-command docker run for 2.0. EMBEDDED=0 disables; Compose stays the production path. Verified arm64 (14/14 lifecycle + Compose regression) and amd64 (build + embedded smoke).

docker/Dockerfile

@@ -242,6 +242,7 @@ RUN for i in 1 2 3; do apt-get -o Acquire::Retries=3 update && break || sleep $(
     libopenjp2-tools \
     curl \
     gosu \
+    xz-utils \
     libde265-0 \
     libimage-exiftool-perl \
     python3 python3-pip python3-venv python3-dev \
@@ -273,6 +274,42 @@ RUN for i in 1 2 3; do apt-get -o Acquire::Retries=3 update && break || sleep $(
        fi \
     && rm -rf /var/lib/apt/lists/*
 
+# Embedded-mode databases: PostgreSQL 17 (PGDG, to match the Compose postgres:17
+# major for a clean data handoff) + Redis. Shipped in every image (single tag);
+# unused in external/Compose mode, ~tens of MB against the multi-GB base. They
+# enter the Trivy CVE surface and ride the existing apt-get upgrade patching.
+RUN install -d /usr/share/postgresql-common/pgdg \
+    && curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc \
+         -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \
+    && . /etc/os-release \
+    && echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt ${VERSION_CODENAME}-pgdg main" \
+         > /etc/apt/sources.list.d/pgdg.list \
+    && for i in 1 2 3; do apt-get -o Acquire::Retries=3 update && break || sleep $((i * 15)); done \
+    && apt-get install -y --no-install-recommends postgresql-17 postgresql-client-17 redis-server \
+    && rm -rf /var/lib/apt/lists/*
+
+# s6-overlay supervises the embedded service tree (postgres + redis + app).
+# Pinned and checksum-verified against the upstream-published .sha256, consistent
+# with the repo's digest-pinning posture. For stricter supply-chain pinning,
+# replace the .sha256 fetch with a literal hash checked via
+# `echo "<hash>  <file>" | sha256sum -c -`.
+ARG S6_OVERLAY_VERSION=3.2.0.2
+RUN set -e; \
+    case "$TARGETARCH" in \
+      amd64) S6_ARCH=x86_64 ;; \
+      arm64) S6_ARCH=aarch64 ;; \
+      *) echo "unsupported TARGETARCH=$TARGETARCH" >&2; exit 1 ;; \
+    esac; \
+    cd /tmp; \
+    base="https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}"; \
+    for f in "s6-overlay-noarch.tar.xz" "s6-overlay-${S6_ARCH}.tar.xz"; do \
+      curl -fsSL -O "${base}/${f}"; \
+      curl -fsSL -O "${base}/${f}.sha256"; \
+      sha256sum -c "${f}.sha256"; \
+      tar -C / -Jxpf "${f}"; \
+    done; \
+    rm -f /tmp/s6-overlay-*
+
 # Allow ImageMagick to use Ghostscript delegate for EPS (read for decode,
 # write for the convert tool's EPS output). PS/PDF/XPS stay read-only.
 RUN POLICY_FILE=$(find /etc/ImageMagick* -name policy.xml 2>/dev/null | head -1) && \
@@ -440,6 +477,13 @@ ENV SENTRY_RELEASE=${SENTRY_RELEASE}
 ENV NVIDIA_VISIBLE_DEVICES=all \
     NVIDIA_DRIVER_CAPABILITIES=compute,utility
 
+# s6-overlay (embedded mode): propagate the runtime-exported environment (the
+# 127.0.0.1 URLs, resolved _FILE secrets, auth defaults) into supervised
+# services, and never time out waiting for first-boot readiness (initdb can take
+# minutes). Inert in external mode, which never invokes s6.
+ENV S6_KEEP_ENV=1 \
+    S6_CMD_WAIT_FOR_SERVICES_MAXTIME=0
+
 # Suppress noisy ML library output in docker logs
 ENV PYTHONWARNINGS=default \
     TF_CPP_MIN_LOG_LEVEL=3 \
@@ -463,14 +507,25 @@ RUN chown -R snapotter:snapotter /app /opt/venv && \
 # entrypoint-lib.sh holds the writability helpers it sources at startup.
 COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
 COPY docker/entrypoint-lib.sh /usr/local/bin/entrypoint-lib.sh
+COPY docker/embedded-lib.sh /usr/local/bin/embedded-lib.sh
+COPY docker/embedded/postgres-bootstrap.sh /usr/local/bin/embedded-postgres-bootstrap.sh
 COPY docker/wait-for-postgres.mjs /app/docker/wait-for-postgres.mjs
-RUN chmod +x /usr/local/bin/entrypoint.sh
+# s6-overlay reads its service tree from /etc/s6-overlay/s6-rc.d (embedded mode)
+COPY docker/s6/s6-rc.d /etc/s6-overlay/s6-rc.d
+RUN chmod +x /usr/local/bin/entrypoint.sh /usr/local/bin/embedded-postgres-bootstrap.sh \
+    && chmod +x /etc/s6-overlay/s6-rc.d/postgres/run /etc/s6-overlay/s6-rc.d/redis/run \
+                /etc/s6-overlay/s6-rc.d/snapotter/run \
+                /etc/s6-overlay/s6-rc.d/postgres-init/up /etc/s6-overlay/s6-rc.d/postgres-ready/up \
+                /etc/s6-overlay/s6-rc.d/redis-ready/up
 
 EXPOSE 1349
 
-HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+HEALTHCHECK --interval=30s --timeout=5s --start-period=180s --retries=3 \
     CMD curl -sf --max-time 5 http://localhost:1349/api/v1/health || exit 1
 
-# tini as PID 1 for zombie reaping + signal forwarding
-ENTRYPOINT ["tini", "--", "entrypoint.sh"]
+# entrypoint.sh runs as PID 1 and re-execs the right init: `tini` for external
+# mode (zombie reaping + signal forwarding for the gosu-dropped app, same end
+# state as before), or s6-overlay's /init as PID 1 for embedded mode (which
+# s6-overlay-suexec requires).
+ENTRYPOINT ["entrypoint.sh"]
 CMD ["pnpm", "--filter", "@snapotter/api", "run", "start"]

docker/embedded-lib.sh

@@ -0,0 +1,87 @@
+#!/bin/sh
+# Shared helpers for SnapOtter embedded mode (in-container Postgres + Redis).
+# Sourced by docker/entrypoint.sh and the s6 service scripts. Kept in its own
+# file so the decision logic can be unit-tested directly
+# (tests/unit/security/embedded-mode.test.ts) rather than mirrored. Sourcing has
+# no side effects, only function definitions. POSIX sh only (no bashisms).
+#
+# Functions use _-prefixed locals (sh has no portable `local`).
+
+# decide_run_mode
+# Echoes "embedded" or "external" and returns 0, OR prints a fatal partial-config
+# error to stderr and returns 2. Embedded requires BOTH DATABASE_URL and
+# REDIS_URL unset and EMBEDDED != 0. Exactly one URL set is an ambiguous
+# misconfiguration and is rejected.
+decide_run_mode() {
+  if [ "${EMBEDDED:-auto}" = "0" ]; then
+    echo "external"
+    return 0
+  fi
+  if [ -z "${DATABASE_URL:-}" ] && [ -z "${REDIS_URL:-}" ]; then
+    echo "embedded"
+    return 0
+  fi
+  if [ -n "${DATABASE_URL:-}" ] && [ -n "${REDIS_URL:-}" ]; then
+    echo "external"
+    return 0
+  fi
+  echo "FATAL: set BOTH DATABASE_URL and REDIS_URL (external mode), or NEITHER (embedded mode)." >&2
+  echo "Exactly one is set, which is ambiguous. Refusing to guess." >&2
+  return 2
+}
+
+# embedded_requires_root <uid>
+# Embedded mode needs root to initdb, chown PGDATA, run Postgres as the postgres
+# user, and s6-setuidgid per service. Arbitrary-UID runtimes (OpenShift,
+# Kubernetes runAsNonRoot, `docker run --user`) cannot do this. Returns 0 when
+# uid is 0, otherwise prints guidance and returns 1.
+embedded_requires_root() {
+  _err_uid="$1"
+  if [ "$_err_uid" = "0" ]; then
+    return 0
+  fi
+  echo "FATAL: embedded mode needs root to run the in-container database (uid=$_err_uid)." >&2
+  echo "Run the container as root (the default), or use the Compose 3-container stack," >&2
+  echo "or set DATABASE_URL + REDIS_URL to point at external services." >&2
+  return 1
+}
+
+# sqlite_autodetect_path <data_dir>
+# Echoes the SQLite path the app should import on first boot, or empty. An
+# explicit SQLITE_MIGRATE_PATH always wins. Otherwise, if <data_dir>/snapotter.db
+# exists (a 1.x single-container database), echo it so embedded mode upgrades in
+# place. The importer itself no-ops when the target Postgres is non-empty, so a
+# second boot does not re-import.
+sqlite_autodetect_path() {
+  _sap_dir="$1"
+  if [ -n "${SQLITE_MIGRATE_PATH:-}" ]; then
+    echo "$SQLITE_MIGRATE_PATH"
+    return 0
+  fi
+  if [ -f "$_sap_dir/snapotter.db" ]; then
+    echo "$_sap_dir/snapotter.db"
+    return 0
+  fi
+  echo ""
+}
+
+# check_pg_version <pgdata> <installed_major>
+# Guards against a silent major-version mismatch. If <pgdata>/PG_VERSION exists
+# and its major differs from <installed_major>, print actionable guidance and
+# return 1 (never auto-pg_upgrade, never overwrite). Returns 0 when it matches or
+# when the data dir is fresh (no PG_VERSION yet).
+check_pg_version() {
+  _cpv_data="$1"
+  _cpv_installed="$2"
+  if [ ! -f "$_cpv_data/PG_VERSION" ]; then
+    return 0
+  fi
+  _cpv_found="$(tr -d '[:space:]' < "$_cpv_data/PG_VERSION" 2>/dev/null)"
+  if [ "$_cpv_found" = "$_cpv_installed" ]; then
+    return 0
+  fi
+  echo "FATAL: $_cpv_data was created by PostgreSQL $_cpv_found, but this image ships PostgreSQL $_cpv_installed." >&2
+  echo "Major-version upgrades are a manual procedure (pg_dump from the old major, restore into the new)." >&2
+  echo "See the embedded-mode upgrade docs. Refusing to start to avoid data corruption." >&2
+  return 1
+}

docker/embedded/postgres-bootstrap.sh

@@ -0,0 +1,52 @@
+#!/bin/sh
+# First-boot initializer for the embedded Postgres. Runs as ROOT inside the s6
+# `postgres-init` oneshot, before the `postgres` longrun starts. Idempotent: on a
+# data dir that already exists it only guards the version and fixes ownership.
+set -e
+. /usr/local/bin/embedded-lib.sh
+
+PGDATA=/data/postgres
+PGBIN=/usr/lib/postgresql/17/bin
+INSTALLED_MAJOR=17
+TMP=/data/postgres.bootstrapping   # same filesystem as PGDATA so the mv is atomic
+
+# Clean any interrupted previous bootstrap.
+rm -rf "$TMP"
+
+# Existing data dir: guard the major version, fix ownership, done.
+if [ -f "$PGDATA/PG_VERSION" ]; then
+  check_pg_version "$PGDATA" "$INSTALLED_MAJOR" || exit 1
+  chown -R postgres:postgres "$PGDATA"
+  echo "Embedded Postgres: existing data dir OK (major $INSTALLED_MAJOR)."
+  exit 0
+fi
+
+echo "Embedded Postgres: first-boot initdb..."
+install -d -o postgres -g postgres -m 700 "$TMP"
+
+# initdb: C locale (byte-ordered, libc-independent collation, so the data dir is
+# safe across the glibc/musl handoff to a Compose postgres:17-alpine), trust auth
+# on loopback (the only reachable interface), bootstrap superuser `snapotter` so
+# the role in DATABASE_URL already exists.
+s6-setuidgid postgres "$PGBIN/initdb" -D "$TMP" \
+  --username=snapotter --encoding=UTF8 --locale=C \
+  --auth-local=trust --auth-host=trust
+
+# Loopback only, and avoid the 64MB /dev/shm for parallel workers.
+{
+  echo "listen_addresses = '127.0.0.1'"
+  echo "dynamic_shared_memory_type = mmap"
+} >> "$TMP/postgresql.conf"
+
+# Create the application database and set the role password via single-user mode:
+# no socket, no listener, no /var/run/postgresql, auth bypassed. The snapotter
+# superuser already exists from initdb --username. The password is harmless under
+# trust auth but lets a future scram flip work without a reinit.
+echo "CREATE DATABASE snapotter OWNER snapotter;" | \
+  s6-setuidgid postgres "$PGBIN/postgres" --single -D "$TMP" postgres
+echo "ALTER ROLE snapotter WITH PASSWORD 'snapotter';" | \
+  s6-setuidgid postgres "$PGBIN/postgres" --single -D "$TMP" postgres
+
+# Atomic publish: a crash before this leaves only the throwaway temp dir.
+mv "$TMP" "$PGDATA"
+echo "Embedded Postgres: initialized."

docker/entrypoint.sh

@@ -4,6 +4,9 @@ set -e
 # Shared permission helpers (dir_writable, ensure_writable). Lives beside this
 # script in the image; sourcing only defines functions (no side effects).
 . /usr/local/bin/entrypoint-lib.sh
+# Embedded-mode helpers (decide_run_mode, embedded_requires_root,
+# sqlite_autodetect_path, check_pg_version). Same no-side-effects contract.
+. /usr/local/bin/embedded-lib.sh
 
 # --- Docker secret file convention (_FILE suffix) ---
 # For each supported var, if VAR_FILE is set, read the secret from that file
@@ -49,6 +52,25 @@ export AUTH_ENABLED="${AUTH_ENABLED:-true}"
 export DEFAULT_USERNAME="${DEFAULT_USERNAME:-admin}"
 export DEFAULT_PASSWORD="${DEFAULT_PASSWORD:-admin}"
 
+# Embedded mode detection (in-container Postgres + Redis). Decide the run mode
+# before any DB-dependent step. EMBEDDED_MODE is exported so later branches (the
+# wait loop, security warnings, chown, final exec) can key off it.
+RUN_MODE="$(decide_run_mode)" || exit $?   # exits 2 on ambiguous partial config
+if [ "$RUN_MODE" = "embedded" ]; then
+  embedded_requires_root "$(id -u)" || exit 1
+  EMBEDDED_MODE=1
+  export EMBEDDED_MODE
+  export DATABASE_URL="postgres://snapotter:snapotter@127.0.0.1:5432/snapotter"
+  export REDIS_URL="redis://127.0.0.1:6379"
+  # 1.x single-container upgrade: auto-import /data/snapotter.db on first boot
+  # unless the operator set an explicit path. Importer no-ops on a non-empty DB.
+  SQLITE_MIGRATE_PATH="$(sqlite_autodetect_path "${DATA_DIR:-/data}")"
+  export SQLITE_MIGRATE_PATH
+  printf '\n  \033[1;33m🦦 SnapOtter embedded mode\033[0m\n' >&2
+  printf '  \033[2mRunning an in-container Postgres + Redis for quick start.\033[0m\n' >&2
+  printf '  \033[2mFor production, use the Compose 3-container stack. See docs.\033[0m\n\n' >&2
+fi
+
 # Writable directories the runtime needs: WS = processing scratch, DD = data
 # root (holds files, logs, and the AI venv/models). Honor env overrides.
 WS="${WORKSPACE_PATH:-/tmp/workspace}"
@@ -110,8 +132,9 @@ if [ -d "/opt/venv" ]; then
   fi
 fi
 
-# Wait for Postgres to be reachable before starting the app
-if [ -n "${DATABASE_URL:-}" ]; then
+# Wait for Postgres to be reachable before starting the app (external mode only;
+# in embedded mode s6 starts Postgres and gates the app on a pg_isready oneshot).
+if [ -z "${EMBEDDED_MODE:-}" ] && [ -n "${DATABASE_URL:-}" ]; then
   echo "Waiting for Postgres..."
   i=0
   until node /app/docker/wait-for-postgres.mjs; do
@@ -126,11 +149,15 @@ print_security_warnings() {
   if [ "${DEFAULT_PASSWORD}" = "admin" ]; then
     printf '  \033[33mWARNING:%b Default admin password is still "admin". Change it for any non-local deployment.\n' '\033[0m' >&2
   fi
-  if echo "${DATABASE_URL:-}" | grep -q "snapotter:snapotter@"; then
-    printf '  \033[33mWARNING:%b Default Postgres credentials in use. Set POSTGRES_PASSWORD for production.\n' '\033[0m' >&2
-  fi
-  if echo "${REDIS_URL:-}" | grep -q ":snapotter@"; then
-    printf '  \033[33mWARNING:%b Default Redis password in use. Set REDIS_PASSWORD for production.\n' '\033[0m' >&2
+  # Embedded Postgres/Redis are loopback-only and never network-exposed, so the
+  # default-credential warnings below only apply to external (Compose) mode.
+  if [ -z "${EMBEDDED_MODE:-}" ]; then
+    if echo "${DATABASE_URL:-}" | grep -q "snapotter:snapotter@"; then
+      printf '  \033[33mWARNING:%b Default Postgres credentials in use. Set POSTGRES_PASSWORD for production.\n' '\033[0m' >&2
+    fi
+    if echo "${REDIS_URL:-}" | grep -q ":snapotter@"; then
+      printf '  \033[33mWARNING:%b Default Redis password in use. Set REDIS_PASSWORD for production.\n' '\033[0m' >&2
+    fi
   fi
 }
 
@@ -187,11 +214,23 @@ if [ "$(id -u)" = "0" ]; then
 
   # Ensure all writable subdirectories exist before chown
   mkdir -p /data/files /data/logs /data/ai/models /data/ai/pip-cache /data/ai/venv /tmp/workspace
+  [ -n "${EMBEDDED_MODE:-}" ] && mkdir -p /data/redis
 
-  # Chown writable directories (/data is the persistent volume, /tmp/workspace is ephemeral).
-  # /app and /opt/venv are read-only at runtime -- no chown needed.
-  chown -R snapotter:snapotter /data /tmp/workspace 2>&1 || \
-    echo "WARNING: Could not fix volume permissions. Use named volumes (not Windows bind mounts) to avoid this. See docs for details." >&2
+  # Chown writable directories (/data is the persistent volume, /tmp/workspace is
+  # ephemeral). /app and /opt/venv are read-only at runtime, so no chown needed.
+  # Embedded carve-out: /data/postgres must stay owned by the postgres user
+  # (Postgres refuses a foreign-owned PGDATA), so exclude it from the snapotter
+  # sweep and chown it separately when it already exists.
+  if [ -n "${EMBEDDED_MODE:-}" ]; then
+    find /data -mindepth 1 -maxdepth 1 ! -name postgres -exec chown -R snapotter:snapotter {} + 2>&1 || \
+      echo "WARNING: Could not fix /data permissions. Use named volumes to avoid this. See docs." >&2
+    chown snapotter:snapotter /data 2>/dev/null || true
+    chown -R snapotter:snapotter /tmp/workspace 2>&1 || true
+    [ -d /data/postgres ] && chown -R postgres:postgres /data/postgres 2>/dev/null || true
+  else
+    chown -R snapotter:snapotter /data /tmp/workspace 2>&1 || \
+      echo "WARNING: Could not fix volume permissions. Use named volumes (not Windows bind mounts) to avoid this. See docs for details." >&2
+  fi
 
   # Root can write anywhere, so verify as the unprivileged snapotter user that
   # actually runs the app. This catches root-squashed or foreign-owned mounts
@@ -201,9 +240,17 @@ if [ "$(id -u)" = "0" ]; then
   fi
 
   print_banner
-  exec gosu snapotter "$@"
+  if [ -n "${EMBEDDED_MODE:-}" ]; then
+    # Hand off to s6-overlay as PID 1 (s6-overlay-suexec requires PID 1); it
+    # supervises postgres + redis + the app and drops privileges per service.
+    exec /init
+  fi
+  # External mode: tini becomes PID 1 (reaps zombies, forwards signals) and runs
+  # the app as snapotter, the same end state as the prior tini ENTRYPOINT.
+  exec tini -- gosu snapotter "$@"
 fi
 
-# Already running as snapotter (e.g. Kubernetes runAsUser)
+# Already running as snapotter (e.g. Kubernetes runAsUser). External mode only:
+# embedded mode requires root and exited earlier. tini becomes PID 1.
 print_banner
-exec "$@"
+exec tini -- "$@"

docker/s6/s6-rc.d/postgres-init/type

@@ -0,0 +1 @@
+oneshot

docker/s6/s6-rc.d/postgres-init/up

@@ -0,0 +1,2 @@
+#!/command/with-contenv sh
+/usr/local/bin/embedded-postgres-bootstrap.sh

docker/s6/s6-rc.d/postgres-ready/type

@@ -0,0 +1 @@
+oneshot

docker/s6/s6-rc.d/postgres-ready/up

@@ -0,0 +1 @@
+/command/with-contenv sh -c "until pg_isready -h 127.0.0.1 -p 5432 -q; do sleep 1; done"

docker/s6/s6-rc.d/postgres/down-signal

@@ -0,0 +1 @@
+SIGINT

docker/s6/s6-rc.d/postgres/run

@@ -0,0 +1,2 @@
+#!/command/with-contenv sh
+exec s6-setuidgid postgres /usr/lib/postgresql/17/bin/postgres -D /data/postgres

docker/s6/s6-rc.d/postgres/type

@@ -0,0 +1 @@
+longrun

docker/s6/s6-rc.d/redis-ready/type

@@ -0,0 +1 @@
+oneshot

docker/s6/s6-rc.d/redis-ready/up

@@ -0,0 +1 @@
+/command/with-contenv sh -c "until redis-cli -h 127.0.0.1 -p 6379 ping 2>/dev/null | grep -q PONG; do sleep 1; done"

docker/s6/s6-rc.d/redis/run

@@ -0,0 +1,8 @@
+#!/command/with-contenv sh
+exec s6-setuidgid snapotter redis-server \
+  --dir /data/redis \
+  --bind 127.0.0.1 \
+  --port 6379 \
+  --maxmemory-policy noeviction \
+  --appendonly yes \
+  --maxmemory "${REDIS_MAXMEMORY:-512mb}"

docker/s6/s6-rc.d/redis/type

@@ -0,0 +1 @@
+longrun

docker/s6/s6-rc.d/snapotter/run

@@ -0,0 +1,3 @@
+#!/command/with-contenv sh
+cd /app
+exec s6-setuidgid snapotter pnpm --filter @snapotter/api run start

docker/s6/s6-rc.d/snapotter/type

@@ -0,0 +1 @@
+longrun