Skip to content

The open-source app everyone uses to manage agents at work

chore(docker): improve base image and organize docker files

Cody (Radius Red)420cd4fd8dd5
diff --git a/Dockerfile b/Dockerfile
index bf1501aad8..d613c380b4 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -2,10 +2,17 @@ FROM node:lts-trixie-slim AS base
ARG USER_UID=1000
ARG USER_GID=1000
RUN apt-get update \
- && apt-get install -y --no-install-recommends ca-certificates curl git gosu \
- && rm -rf /var/lib/apt/lists/*
-
-RUN corepack enable
+ && apt-get install -y --no-install-recommends ca-certificates gosu curl git wget ripgrep python3 \
+ && mkdir -p -m 755 /etc/apt/keyrings \
+ && wget -nv -O/etc/apt/keyrings/githubcli-archive-keyring.gpg https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+ && echo "20e0125d6f6e077a9ad46f03371bc26d90b04939fb95170f5a1905099cc6bcc0 /etc/apt/keyrings/githubcli-archive-keyring.gpg" | sha256sum -c - \
+ && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+ && mkdir -p -m 755 /etc/apt/sources.list.d \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends gh \
+ && rm -rf /var/lib/apt/lists/* \
+ && corepack enable
# Modify the existing node user/group to have the specified UID/GID to match host user
RUN usermod -u $USER_UID --non-unique node \
@@ -51,7 +58,7 @@ RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/cod
&& mkdir -p /paperclip \
&& chown node:node /paperclip
-COPY docker-entrypoint.sh /usr/local/bin/
+COPY scripts/docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
ENV NODE_ENV=production \
@@ -65,7 +72,8 @@ ENV NODE_ENV=production \
USER_GID=${USER_GID} \
PAPERCLIP_CONFIG=/paperclip/instances/default/config.json \
PAPERCLIP_DEPLOYMENT_MODE=authenticated \
- PAPERCLIP_DEPLOYMENT_EXPOSURE=private
+ PAPERCLIP_DEPLOYMENT_EXPOSURE=private \
+ OPENCODE_ALLOW_ALL_MODELS=true
VOLUME ["/paperclip"]
EXPOSE 3100
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index 1516c84aea..dd9efee637 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -97,7 +97,7 @@ docker run --name paperclip \
Or use Compose:
```sh
-docker compose -f docker-compose.quickstart.yml up --build
+docker compose -f docker/docker-compose.quickstart.yml up --build
```
See `doc/DOCKER.md` for API key wiring (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`) and persistence details.
diff --git a/doc/DOCKER.md b/doc/DOCKER.md
index a7055e203c..056a7bdf04 100644
--- a/doc/DOCKER.md
+++ b/doc/DOCKER.md
@@ -2,6 +2,28 @@
Run Paperclip in Docker without installing Node or pnpm locally.
+All commands below assume you are in the **project root** (the directory containing `package.json`), not inside `docker/`.
+
+## Building the image
+
+```sh
+docker build -t paperclip-local .
+```
+
+The Dockerfile installs common agent tools (`git`, `gh`, `curl`, `wget`, `ripgrep`, `python3`) and the Claude, Codex, and OpenCode CLIs.
+
+Build arguments:
+
+| Arg | Default | Purpose |
+|-----|---------|---------|
+| `USER_UID` | `1000` | UID for the container `node` user (match your host UID to avoid permission issues on bind mounts) |
+| `USER_GID` | `1000` | GID for the container `node` group |
+
+```sh
+docker build -t paperclip-local \
+ --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) .
+```
+
## One-liner (build + run)
```sh
@@ -10,6 +32,7 @@ docker run --name paperclip \
-p 3100:3100 \
-e HOST=0.0.0.0 \
-e PAPERCLIP_HOME=/paperclip \
+ -e BETTER_AUTH_SECRET=$(openssl rand -hex 32) \
-v "$(pwd)/data/docker-paperclip:/paperclip" \
paperclip-local
```
@@ -25,10 +48,15 @@ Data persistence:
All persisted under your bind mount (`./data/docker-paperclip` in the example above).
-## Compose Quickstart
+## Docker Compose
+
+### Quickstart (embedded SQLite)
+
+Single container, no external database. Data persists via a bind mount.
```sh
-docker compose -f docker-compose.quickstart.yml up --build
+BETTER_AUTH_SECRET=$(openssl rand -hex 32) \
+ docker compose -f docker/docker-compose.quickstart.yml up --build
```
Defaults:
@@ -39,11 +67,36 @@ Defaults:
Optional overrides:
```sh
-PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc docker compose -f docker-compose.quickstart.yml up --build
+PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=../data/pc \
+ docker compose -f docker/docker-compose.quickstart.yml up --build
```
+**Note:** `PAPERCLIP_DATA_DIR` is resolved relative to the compose file (`docker/`), so `../data/pc` maps to `data/pc` in the project root.
+
If you change host port or use a non-local domain, set `PAPERCLIP_PUBLIC_URL` to the external URL you will use in browser/auth flows.
+Pass `OPENAI_API_KEY` and/or `ANTHROPIC_API_KEY` to enable local adapter runs.
+
+### Full stack (with PostgreSQL)
+
+Paperclip server + PostgreSQL 17. The database is health-checked before the server starts.
+
+```sh
+BETTER_AUTH_SECRET=$(openssl rand -hex 32) \
+ docker compose -f docker/docker-compose.yml up --build
+```
+
+PostgreSQL data persists in a named Docker volume (`pgdata`). Paperclip data persists in `paperclip-data`.
+
+### Untrusted PR review
+
+Isolated container for reviewing untrusted pull requests with Codex or Claude, without exposing your host machine. See `doc/UNTRUSTED-PR-REVIEW.md` for the full workflow.
+
+```sh
+docker compose -f docker/docker-compose.untrusted-review.yml build
+docker compose -f docker/docker-compose.untrusted-review.yml run --rm --service-ports review
+```
+
## Authenticated Compose (Single Public URL)
For authenticated deployments, set one canonical public URL and let Paperclip derive auth/callback defaults:
@@ -93,11 +146,71 @@ Notes:
- Without API keys, the app still runs normally.
- Adapter environment checks in Paperclip will surface missing auth/CLI prerequisites.
-## Untrusted PR Review Container
+## Podman Quadlet (systemd)
+
+The `docker/quadlet/` directory contains unit files to run Paperclip + PostgreSQL as systemd services via Podman Quadlet.
+
+| File | Purpose |
+|------|---------|
+| `docker/quadlet/paperclip.pod` | Pod definition — groups containers into a shared network namespace |
+| `docker/quadlet/paperclip.container` | Paperclip server — joins the pod, connects to Postgres at `127.0.0.1` |
+| `docker/quadlet/paperclip-db.container` | PostgreSQL 17 — joins the pod, health-checked |
+
+### Setup
+
+1. Build the image (see above).
+
+2. Copy quadlet files to your systemd directory:
+
+ ```sh
+ # Rootless (recommended)
+ cp docker/quadlet/*.pod docker/quadlet/*.container \
+ ~/.config/containers/systemd/
+
+ # Or rootful
+ sudo cp docker/quadlet/*.pod docker/quadlet/*.container \
+ /etc/containers/systemd/
+ ```
-If you want a separate Docker environment for reviewing untrusted pull requests with `codex` or `claude`, use the dedicated review workflow in `doc/UNTRUSTED-PR-REVIEW.md`.
+3. Create a secrets env file (keep out of version control):
-That setup keeps CLI auth state in Docker volumes instead of your host home directory and uses a separate scratch workspace for PR checkouts and preview runs.
+ ```sh
+ cat > ~/.config/containers/systemd/paperclip.env <<EOL
+ BETTER_AUTH_SECRET=$(openssl rand -hex 32)
+ POSTGRES_USER=paperclip
+ POSTGRES_PASSWORD=paperclip
+ POSTGRES_DB=paperclip
+ DATABASE_URL=postgres://paperclip:[email protected]:5432/paperclip
+ # OPENAI_API_KEY=sk-...
+ # ANTHROPIC_API_KEY=sk-...
+ EOL
+ ```
+
+4. Create the data directory and start:
+
+ ```sh
+ mkdir -p ~/.local/share/paperclip
+ systemctl --user daemon-reload
+ systemctl --user start paperclip-pod
+ ```
+
+### Quadlet management
+
+```sh
+journalctl --user -u paperclip -f # App logs
+journalctl --user -u paperclip-db -f # DB logs
+systemctl --user status paperclip-pod # Pod status
+systemctl --user restart paperclip-pod # Restart all
+systemctl --user stop paperclip-pod # Stop all
+```
+
+### Quadlet notes
+
+- **First boot**: Unlike Docker Compose's `condition: service_healthy`, Quadlet's `After=` only waits for the DB unit to *start*, not for PostgreSQL to be ready. On a cold first boot you may see one or two restart attempts in `journalctl --user -u paperclip` while PostgreSQL initialises — this is expected and resolves automatically via `Restart=on-failure`.
+- Containers in a pod share `localhost`, so Paperclip reaches Postgres at `127.0.0.1:5432`.
+- PostgreSQL data persists in the `paperclip-pgdata` named volume.
+- Paperclip data persists at `~/.local/share/paperclip`.
+- For rootful quadlet deployment, remove `%h` prefixes and use absolute paths.
## Onboard Smoke Test (Ubuntu + npm only)
@@ -133,4 +246,9 @@ Notes:
- In authenticated mode, the smoke script defaults `SMOKE_AUTO_BOOTSTRAP=true` and drives the real bootstrap path automatically: it signs up a real user, runs `paperclipai auth bootstrap-ceo` inside the container to mint a real bootstrap invite, accepts that invite over HTTP, and verifies board session access.
- Run the script in the foreground to watch the onboarding flow; stop with `Ctrl+C` after validation.
- Set `SMOKE_DETACH=true` to leave the container running for automation and optionally write shell-ready metadata to `SMOKE_METADATA_FILE`.
-- The image definition is in `Dockerfile.onboard-smoke`.
+- The image definition is in `docker/Dockerfile.onboard-smoke`.
+
+## General Notes
+
+- The `docker-entrypoint.sh` adjusts the container `node` user UID/GID at startup to match the values passed via `USER_UID`/`USER_GID`, avoiding permission issues on bind-mounted volumes.
+- Paperclip data persists via Docker volumes/bind mounts (compose) or at `~/.local/share/paperclip` (quadlet).
diff --git a/doc/UNTRUSTED-PR-REVIEW.md b/doc/UNTRUSTED-PR-REVIEW.md
index 0061a58135..40505873cd 100644
--- a/doc/UNTRUSTED-PR-REVIEW.md
+++ b/doc/UNTRUSTED-PR-REVIEW.md
@@ -16,14 +16,14 @@ By default this workflow does **not** mount your host repo checkout, your host h
## Files
- `docker/untrusted-review/Dockerfile`
-- `docker-compose.untrusted-review.yml`
+- `docker/docker-compose.untrusted-review.yml`
- `review-checkout-pr` inside the container
## Build and start a shell
```sh
-docker compose -f docker-compose.untrusted-review.yml build
-docker compose -f docker-compose.untrusted-review.yml run --rm --service-ports review
+docker compose -f docker/docker-compose.untrusted-review.yml build
+docker compose -f docker/docker-compose.untrusted-review.yml run --rm --service-ports review
```
That opens an interactive shell in the review container with:
@@ -47,7 +47,7 @@ claude login
If you prefer API-key auth instead of CLI login, pass keys through Compose env:
```sh
-OPENAI_API_KEY=... ANTHROPIC_API_KEY=... docker compose -f docker-compose.untrusted-review.yml run --rm review
+OPENAI_API_KEY=... ANTHROPIC_API_KEY=... docker compose -f docker/docker-compose.untrusted-review.yml run --rm review
```
## Check out a PR safely
@@ -117,7 +117,7 @@ Notes:
Remove the review container volumes when you want a clean environment:
```sh
-docker compose -f docker-compose.untrusted-review.yml down -v
+docker compose -f docker/docker-compose.untrusted-review.yml down -v
```
That deletes:
diff --git a/Dockerfile.onboard-smoke b/docker/Dockerfile.onboard-smoke
similarity index 100%
rename from Dockerfile.onboard-smoke
rename to docker/Dockerfile.onboard-smoke
diff --git a/docker-compose.quickstart.yml b/docker/docker-compose.quickstart.yml
similarity index 86%
rename from docker-compose.quickstart.yml
rename to docker/docker-compose.quickstart.yml
index 82006606b1..65705059aa 100644
--- a/docker-compose.quickstart.yml
+++ b/docker/docker-compose.quickstart.yml
@@ -1,7 +1,7 @@
services:
paperclip:
build:
- context: .
+ context: ..
dockerfile: Dockerfile
ports:
- "${PAPERCLIP_PORT:-3100}:3100"
@@ -15,4 +15,4 @@ services:
PAPERCLIP_PUBLIC_URL: "${PAPERCLIP_PUBLIC_URL:-http://localhost:3100}"
BETTER_AUTH_SECRET: "${BETTER_AUTH_SECRET:?BETTER_AUTH_SECRET must be set}"
volumes:
- - "${PAPERCLIP_DATA_DIR:-./data/docker-paperclip}:/paperclip"
+ - "${PAPERCLIP_DATA_DIR:-../data/docker-paperclip}:/paperclip"
diff --git a/docker-compose.untrusted-review.yml b/docker/docker-compose.untrusted-review.yml
similarity index 97%
rename from docker-compose.untrusted-review.yml
rename to docker/docker-compose.untrusted-review.yml
index ff11148ac9..ca1ee09805 100644
--- a/docker-compose.untrusted-review.yml
+++ b/docker/docker-compose.untrusted-review.yml
@@ -1,7 +1,7 @@
services:
review:
build:
- context: .
+ context: ..
dockerfile: docker/untrusted-review/Dockerfile
init: true
tty: true
diff --git a/docker-compose.yml b/docker/docker-compose.yml
similarity index 94%
rename from docker-compose.yml
rename to docker/docker-compose.yml
index 94f4291f17..b26b396ab8 100644
--- a/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -16,7 +16,9 @@ services:
- pgdata:/var/lib/postgresql/data
server:
- build: .
+ build:
+ context: ..
+ dockerfile: Dockerfile
ports:
- "3100:3100"
environment:
diff --git a/docker/quadlet/paperclip-db.container b/docker/quadlet/paperclip-db.container
new file mode 100644
index 0000000000..5cb39cc207
--- /dev/null
+++ b/docker/quadlet/paperclip-db.container
@@ -0,0 +1,20 @@
+[Unit]
+Description=PostgreSQL for Paperclip
+
+[Container]
+Image=docker.io/library/postgres:17-alpine
+ContainerName=paperclip-db
+Pod=paperclip.pod
+Volume=paperclip-pgdata:/var/lib/postgresql/data
+EnvironmentFile=%h/.config/containers/systemd/paperclip.env
+HealthCmd=pg_isready -U $POSTGRES_USER -d $POSTGRES_DB -h localhost || exit 1
+HealthInterval=15s
+HealthTimeout=5s
+HealthRetries=5
+
+[Service]
+Restart=on-failure
+TimeoutStartSec=60
+
+[Install]
+WantedBy=default.target
diff --git a/docker/quadlet/paperclip.container b/docker/quadlet/paperclip.container
new file mode 100644
index 0000000000..2583916cd2
--- /dev/null
+++ b/docker/quadlet/paperclip.container
@@ -0,0 +1,23 @@
+[Unit]
+Description=Paperclip AI Agent Orchestrator
+Requires=paperclip-db.service
+After=paperclip-db.service
+
+[Container]
+Image=paperclip-local
+ContainerName=paperclip
+Pod=paperclip.pod
+Volume=%h/.local/share/paperclip:/paperclip:Z
+Environment=HOST=0.0.0.0
+Environment=PAPERCLIP_HOME=/paperclip
+Environment=PAPERCLIP_DEPLOYMENT_MODE=authenticated
+Environment=PAPERCLIP_DEPLOYMENT_EXPOSURE=private
+Environment=PAPERCLIP_PUBLIC_URL=http://localhost:3100
+EnvironmentFile=%h/.config/containers/systemd/paperclip.env
+
+[Service]
+Restart=on-failure
+TimeoutStartSec=120
+
+[Install]
+WantedBy=default.target
diff --git a/docker/quadlet/paperclip.pod b/docker/quadlet/paperclip.pod
new file mode 100644
index 0000000000..45297e9633
--- /dev/null
+++ b/docker/quadlet/paperclip.pod
@@ -0,0 +1,3 @@
+[Pod]
+PodName=paperclip
+PublishPort=3100:3100
diff --git a/docs/deploy/docker.md b/docs/deploy/docker.md
index 0effd4c7de..9fc2dbfe88 100644
--- a/docs/deploy/docker.md
+++ b/docs/deploy/docker.md
@@ -8,7 +8,7 @@ Run Paperclip in Docker without installing Node or pnpm locally.
## Compose Quickstart (Recommended)
```sh
-docker compose -f docker-compose.quickstart.yml up --build
+docker compose -f docker/docker-compose.quickstart.yml up --build
```
Open [http://localhost:3100](http://localhost:3100).
@@ -21,10 +21,12 @@ Defaults:
Override with environment variables:
```sh
-PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc \
- docker compose -f docker-compose.quickstart.yml up --build
+PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=../data/pc \
+ docker compose -f docker/docker-compose.quickstart.yml up --build
```
+**Note:** `PAPERCLIP_DATA_DIR` is resolved relative to the compose file (`docker/`), so `../data/pc` maps to `data/pc` in the project root.
+
## Manual Docker Build
```sh
diff --git a/scripts/docker-build-test.sh b/scripts/docker-build-test.sh
new file mode 100755
index 0000000000..1cdb8d4fa7
--- /dev/null
+++ b/scripts/docker-build-test.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Verify the Docker image builds successfully.
+# Skips gracefully when docker/podman is not available.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Detect container runtime
+if command -v docker >/dev/null 2>&1; then
+ RUNTIME=docker
+elif command -v podman >/dev/null 2>&1; then
+ RUNTIME=podman
+else
+ echo "SKIP: neither docker nor podman found — skipping build test"
+ exit 0
+fi
+
+# Verify the daemon is reachable (docker may be installed but not running)
+if ! "$RUNTIME" info >/dev/null 2>&1; then
+ echo "SKIP: $RUNTIME is installed but not running — skipping build test"
+ exit 0
+fi
+
+IMAGE_TAG="paperclip-build-test:$$"
+trap '"$RUNTIME" rmi "$IMAGE_TAG" >/dev/null 2>&1 || true' EXIT
+
+echo "==> Testing Docker build with $RUNTIME"
+"$RUNTIME" build \
+ -f "$REPO_ROOT/Dockerfile" \
+ -t "$IMAGE_TAG" \
+ --target production \
+ "$REPO_ROOT"
+
+echo "==> Verifying key binaries in image"
+"$RUNTIME" run --rm "$IMAGE_TAG" sh -c '
+ set -e
+ node --version
+ git --version
+ gh --version
+ rg --version
+ python3 --version
+ curl --version | head -1
+ claude --version 2>/dev/null || echo "claude CLI not found (OK in minimal builds)"
+'
+
+echo "PASS: Docker build test succeeded"
diff --git a/docker-entrypoint.sh b/scripts/docker-entrypoint.sh
similarity index 100%
rename from docker-entrypoint.sh
rename to scripts/docker-entrypoint.sh
diff --git a/scripts/docker-onboard-smoke.sh b/scripts/docker-onboard-smoke.sh
index 97f6743f22..c2830ff0f5 100755
--- a/scripts/docker-onboard-smoke.sh
+++ b/scripts/docker-onboard-smoke.sh
@@ -242,7 +242,7 @@ echo "==> Building onboard smoke image"
docker build \
--build-arg PAPERCLIPAI_VERSION="$PAPERCLIPAI_VERSION" \
--build-arg HOST_UID="$HOST_UID" \
- -f "$REPO_ROOT/Dockerfile.onboard-smoke" \
+ -f "$REPO_ROOT/docker/Dockerfile.onboard-smoke" \
-t "$IMAGE_NAME" \
"$REPO_ROOT"