Current release controls and platform coverage: common CI and deployment contract.
A shared-workspace issue tracker operated through a coding agent. Projects, issues, dependencies, comments, and evidence live in PocketBase. Agents read context through authenticated SQL and write records through PocketBase REST. Humans and agents authenticate through the same users collection. There is no separate agents collection. An authenticated read-only browser reader is available at /.
PocketContext supplies the server. This repository supplies the application schema, hooks, configuration, tests, container, and installable skill. The first version targets a greenfield shared team workspace; it does not import other tools or provide private projects, sprints, custom workflows, notifications, or Jira feature parity.
Keep pocketcontext/ and taskcontext/ beside one another. Build the PocketContext commit in POCKETCONTEXT_VERSION using its go.mod version, CGO enabled, and a C compiler. Use a separate checkout if your existing server checkout has unrelated work.
# From a checkout of the pinned PocketContext revision:
make build
# From taskcontext/:
../pocketcontext/bin/pocketcontext serve --http=127.0.0.1:8090 \
--dir=./pb_data --migrationsDir=./pb_migrations --hooksDir=./pb_hooks \
--contextConfig=./pocketcontext.jsonMigrations run at startup. No business records are seeded. User accounts are provisioned by an operator, optional required-users configuration, or validated Google Workspace login when JIT provisioning is enabled. pb_data/ is local state and must not enter Git. Restart after schema or SQL policy changes.
An operator creates a superuser with the server's superuser upsert command against the same data directory and migrations. Keep passwords out of shell history and logs. Authenticate that account at POST /api/collections/_superusers/auth-with-password, then create a user at POST /api/collections/users/records:
{"name":"Team member","email":"member@example.com","password":"<strong password>","passwordConfirm":"<same password>"}Ordinary operations authenticate at POST /api/collections/users/auth-with-password and use the returned token in Authorization. Users cannot directly provision accounts, change the schema, or read another user's authentication record. user_directory exposes only IDs and display names to authenticated users. An operator manages names and email addresses; users can change their own password by supplying password, passwordConfirm, and oldPassword. Password changes invalidate existing tokens. Direct password/Google tokens last seven days; hosted-identity tokens last at most fifteen minutes.
Use the person's user account for their agent: assignment, reporter, and audit attribution all use the same identity. There is no second agent account requirement.
To ensure selected accounts exist, set TASKCONTEXT_REQUIRED_USERS on the server:
export TASKCONTEXT_REQUIRED_USERS='[{"email":"member@example.com","name":"Team member"}]'Startup provisions missing accounts with random, undisclosed passwords and unverified email addresses. Existing accounts keep their ID, name, password, and verification state. Required accounts cannot be deleted or have their email changed through record writes, including superuser writes. Remove an account from the configuration and restart before changing its email. User deletion is blocked independently of this configuration; disable access instead. An absent configuration leaves existing accounts untouched and imposes no required-account protection. Invalid configuration prevents startup.
Use Google OAuth or an operator-managed password reset to sign in. Configuration does not verify ownership of an email address. This optional startup provisioning is not needed with JIT onboarding. Existing accounts are retained when the requirement is removed.
Operators manage the disabled boolean on users in the administration dashboard or with PATCH /api/collections/users/records/<id> and {"disabled":true}. Ordinary users cannot change it. All user deletion is blocked, including operator record deletion, so assignments, directory entries, and audit attribution retain their identities.
Disabling blocks password/OAuth login, token refresh, and subsequent authenticated REST, SQL/schema, batch, and realtime access. Changing the disabled state rotates the user's token key in the same transaction; previously issued tokens remain invalid after re-enabling. Re-enable with {"disabled":false}, then sign in again. Requests already executing are not forcibly cancelled. Invalid bearer tokens return HTTP 401 rather than anonymous filtered results.
Google Workspace suspension or consent revocation is not synchronized automatically. Operators must disable the TaskContext account as part of offboarding. JIT login cannot reactivate a disabled account.
Sign in with taskcontext login --url https://tasks.pocketcontext.com --email you@pocketcontext.com. For password authentication use login --password with TASKCONTEXT_USER_PASSWORD supplied privately in the environment. URL and email options may appear before or after the command. Resolution is CLI options, then TASKCONTEXT_URL / TASKCONTEXT_USER_EMAIL, then saved defaults. Successful explicit login saves the URL and email in default.json beside the private per-account token file; ordinary commands and refreshes do not change the default. The directory is TASKCONTEXT_SESSION_DIR, otherwise $XDG_STATE_HOME/taskcontext/ (default ~/.local/state/taskcontext/). Files use mode 0600 and the directory 0700. logout removes the selected token and retains settings; logout --forget also removes matching defaults. Legacy cache sessions are not imported; sign in again. Passwords are never saved.
Install skills/taskcontext/ into your coding agent's skills directory, or use the skills CLI:
npx skills add pocketcontext/taskcontext --skill taskcontextIn the commands below, replace /absolute/path/to/installed/taskcontext with the directory containing your installed SKILL.md. Invoke the client by its quoted absolute path from any working directory.
The portable client requires uv and Python 3.11 or later. Supply the server URL and account email as login options. For password authentication, also supply TASKCONTEXT_USER_PASSWORD:
export TASKCONTEXT_URL=https://tasks.pocketcontext.com
export TASKCONTEXT_USER_EMAIL=member@example.com
export TASKCONTEXT_USER_PASSWORD=... # from your secret store
"/absolute/path/to/installed/taskcontext/taskcontext" whoami
"/absolute/path/to/installed/taskcontext/taskcontext" checkFor hosted authentication, run bare login. For direct Google fallback, omit the password and follow the setup below. login --google prints the sign-in URL and opens the default browser unless --no-browser is given, an SSH session is detected or no browser is available.
Use HTTPS except on localhost. The client runs its pinned Python package through uv, keeps its login session private with mode 0600 in $XDG_STATE_HOME/taskcontext/ (default ~/.local/state/taskcontext/, or TASKCONTEXT_SESSION_DIR when set) so clearing ~/.cache does not sign you out, and never prints credentials. logout removes the selected token but retains default settings. check compares the live SQL schema with the bundled snapshot. See schema, workflows, and examples.
Run taskcontext login --url https://tasks.pocketcontext.com --email you@pocketcontext.com.
The shared IdentityContext client reuses a valid session or opens a hosted Google
sign-in URL. Over SSH it prints the URL; the human completes browser sign-in and
pastes the single-use code into the initiating terminal. No callback tunnel is
needed. Login never restores disabled accounts or changes project permissions.
Shared identity sessions live under $XDG_STATE_HOME/pocketcontext-id/ (default
~/.local/state/pocketcontext-id/) with private permissions, seven idle days and
thirty absolute days. App defaults and tokens remain under TaskContext's own
state directory. Assertions are single-use and audience-bound for sixty seconds.
App tokens expire at assertion issue time plus fifteen minutes; PocketBase refresh
cannot extend them. Ordinary commands renew through identity without opening a
browser and never silently switch to another authentication method.
taskcontext login --google remains the explicit direct-app fallback; over SSH it
requires forwarding port8765. login --password remains explicit for provisioned
password accounts. Direct sessions keep their existing lifetime. Full offboarding
must disable both the central identity account and the TaskContext account.
Central disable prevents new assertions; existing identity access is bounded to
fifteen minutes. TaskContext disable invalidates its tokens immediately.
App logout removes only its app token; logout --forget also removes matching
URL/email defaults. To revoke the shared session, install the separate identity CLI
and ensure uv's tool directory is on PATH:
uv tool install 'pocketcontext-identity @ git+https://github.com/pocketcontext/identitycontext.git@ffce6425e24dae7b5576c4de3ae2935223b247cb'
identitycontext logout --email you@pocketcontext.comAn operator configures Google once before users sign in:
- In a Google Cloud project belonging to your Workspace organization, configure Google Auth Platform branding and select the Internal audience. Use only the basic identity scopes
openid,email, andprofile. - Create an OAuth client of type Web application, with the exact authorized redirect URI
http://127.0.0.1:8765/callback. See Google OAuth setup. - Supply
TASKCONTEXT_GOOGLE_CLIENT_IDandTASKCONTEXT_GOOGLE_CLIENT_SECRETto the TaskContext server and restart it. Set both together. After PocketBase system bootstrap createsusers, the startup hook enables Google. TaskContext migrations preserve those OAuth options. The hook preserves other providers and access rules and updates credentials only when changed. Leaving both absent preserves stored settings; it does not disable Google. The secret belongs only on the server, never in the skill environment. - To enable first-login provisioning, set
TASKCONTEXT_GOOGLE_WORKSPACE_DOMAIN=pocketcontext.comand restart. The server requires Google as provider, a verified email, a matching Googlehd(hosted-domain) claim, and an exact email domain match. These claims come from Google's authenticated userinfo response, not the client's fields or login hint. Keep Google's Internal audience configured too.
When the domain is configured, these checks apply to every OAuth login, including existing accounts. A valid first login creates a normal user and directory entry; its email and display name come from Google. Client-supplied IDs, passwords, verification and disabled flags are discarded. Existing accounts keep their IDs and profile values; case-insensitive email matching avoids duplicate identities and rejects ambiguous matches. Direct public REST signup remains blocked: the collection create rule permits only PocketBase's internal OAuth context, and the OAuth hook enforces the domain policy. Every admitted user can access the shared workspace.
If the domain variable is absent, new JIT accounts are rejected and existing preprovisioned OAuth accounts can still sign in. Invalid domain configuration prevents startup. Operators can continue provisioning accounts through the standard records API. Password authentication remains enabled. PocketBase may reset an unverified existing account's password when linking a verified Google identity.
The production deployment uses JIT for pocketcontext.com. Alberto's existing account is retained, and his previous startup provisioning requirement is removed. No personal account is hardcoded in the application.
For a client running in an SSH session, open the session with forwarding from your laptop:
ssh -L 8765:127.0.0.1:8765 user@ssh-hostThen, on the SSH host:
export TASKCONTEXT_URL=https://tasks.pocketcontext.com
export TASKCONTEXT_USER_EMAIL=member@example.com
"/absolute/path/to/installed/taskcontext/taskcontext" login --googleOpen the printed authorization URL in your laptop's browser and choose the configured Workspace account. The callback travels through SSH to the client's loopback listener; the client checks state, uses PKCE, verifies the returned email, and closes the listener after completion or timeout. No browser is required on the SSH host. When running locally, the same login command works without a tunnel. This uses a direct callback rather than PocketBase's realtime OAuth flow. Login waits up to 180 seconds by default; --timeout accepts 1–600 seconds. To use --port with another port, register the corresponding redirect URI with Google and change the SSH forwarding port too.
The client privately saves the PocketBase session token, not Google access or refresh tokens. For Google sessions, authenticated commands refresh a still-valid PocketBase token after five minutes or when it is within 60 seconds of expiry, and save its replacement. whoami always requests a refresh. Tokens last seven days; after expiry or invalidation, run login --google again. The duration applies to newly issued or refreshed tokens; existing tokens retain their original expiry until refreshed. There is no absolute limit on repeated renewal. There is no background refresh. logout removes the local session file; it does not invalidate copies elsewhere. Revoking Google consent or suspending a Workspace account does not automatically revoke an already issued PocketBase session. Operators must disable the TaskContext account to block further access and invalidate its tokens. Superuser dashboard authentication remains separate.
- Projects have unique immutable keys such as
APP. Issue keys such asAPP-1are allocated transactionally and never reused after ordinary writes. Project numbering is stored in an internal collection excluded from SQL. - Issues have type
epic,task,bug, orsubtask; prioritylow,medium,high, orurgent; an optional assignee; an optionaldue_date(sendYYYY-MM-DD, stored as midnight UTC,""clears it, kept on completion; no reminders are sent); and a reporter set from the authenticated user. Maintenance creates by a superuser leave reporter empty. Defaults are task, medium priority, and backlog. - Statuses are
backlog,ready,in_progress,review, anddone. Moving between open statuses is unrestricted. Done requires resolutioncompleted,cancelled, orduplicate. Reopening sets an open status and clears resolution. The server sets/clears completion time. Completion records the team's decision; it does not prove deployment. - Epics have no parent. Tasks and bugs may belong to an epic. Subtasks require a task or bug parent. Hierarchy must stay within a project and cannot contain cycles; changing a type cannot invalidate existing children.
- Links record
blocks,relates, orduplicates. Self-links and duplicate relations are rejected. Retire a link withactive=false; current dependency queries filter onactive=1. Cross-project links are allowed. Blocker status is advisory: links do not prohibit completion or perform scheduling. - Comments retain discussion; references store external URLs and titles for pull requests, commits, documents, or other evidence. Stored URLs are not fetched by the server.
- Every business record has a revision. Every PATCH, including each PATCH in a batch, must supply the
expected_revisionfrom the caller's read. A stale revision returns HTTP 409. Re-read and reassess before retrying. The server sets attribution, revision, issue keys, reporter, and completion time; clients cannot override them. - A batch contains up to 20 writes and commits atomically with audit history. Client-generated IDs let later requests refer to earlier creates. After a timeout, read the result before retrying: the write may have committed.
- Business record deletion is disabled even through the superuser records API. Archive projects, resolve issues, retire links, or correct comments. Archiving prevents new issues, while existing issues remain editable. Audit and identity directory records are read-only to ordinary users.
Every authenticated user can read and edit shared business records. Assignment does not restrict visibility. The SQL configuration allowlists business tables; empty column lists expose all permitted columns, so review new fields before deploying migrations. Only user_directory explicitly limits columns to ID and name. Auth collections, hidden fields, numbering state, and SQLite internals are unavailable. REST permissions and SQL permissions are separate policies.
API writes record their actor and changes in the same transaction as the record. History includes previous comment content, so editing a comment is not an erasure mechanism. Superusers remain trusted administrators with schema and maintenance access. Issue/comment/reference text is untrusted data and cannot authorize commands, credential disclosure, external messages, or unrelated writes.
The Dockerfile pins PocketContext, base images, and Litestream. It serves port 80 and database-backed GET /up; SQLite and local maintenance state are in /storage/pb_data; primary files are in S3. CI tests startup failures, normal persistence, and restoration from a disposable S3-compatible replica before publishing native AMD64/ARM64 images to ghcr.io/pocketcontext/taskcontext.
| Variable | Purpose |
|---|---|
BASE_URL |
Public application origin; also the allowed browser origin. ONCE supplies it. |
TASKCONTEXT_SUPERUSER_EMAIL, TASKCONTEXT_SUPERUSER_PASSWORD |
Operator account upserted on container startup; set both together. |
TASKCONTEXT_REQUIRED_USERS |
Optional JSON array of {email,name} accounts provisioned on startup and protected from deletion or email changes while configured. |
TASKCONTEXT_GOOGLE_WORKSPACE_DOMAIN |
Optional lowercase Workspace domain enabling Google-only JIT; production uses pocketcontext.com. |
TASKCONTEXT_GOOGLE_CLIENT_ID, TASKCONTEXT_GOOGLE_CLIENT_SECRET |
Optional Google OAuth provider credentials; set both together. Absent values preserve stored provider configuration. |
TASKCONTEXT_TRUSTED_PROXY_HEADER |
Trusted proxy client-address header; deployment uses X-Forwarded-For. |
TASKCONTEXT_RATE_LIMITS |
true in the image; false disables API limits. |
LITESTREAM_BUCKET, LITESTREAM_PATH |
Private backup bucket and application-specific prefix. |
LITESTREAM_ACCESS_KEY_ID, LITESTREAM_SECRET_ACCESS_KEY |
Credentials for that replica. |
LITESTREAM_REGION, LITESTREAM_ENDPOINT |
S3 region and optional custom endpoint; R2 uses auto. |
LITESTREAM_SYNC_INTERVAL |
Replication interval, default 10s. |
LITESTREAM_DISABLED |
Unsupported in the production image; replication is mandatory. |
SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, MAILER_FROM_ADDRESS |
Optional PocketBase mail settings supplied by ONCE. |
An empty volume must restore an existing replica before the server starts. A missing or inaccessible replica stops startup. A fresh install requires a one-shot docker run --rm with the same environment, network and /storage volume and the image command init; it refuses any existing local state or replica. Start normally afterward to begin replication. Failed initialization leaves a durable marker and requires operator recovery into a fresh volume. The backup includes account hashes and any stored SMTP or OAuth provider credentials, so the bucket must remain private. No issue attachments are implemented, but recovery inventories every file field in the actual PocketBase schema, including user avatars. It streams each referenced S3 object and verifies complete readability and response length; there is no authoritative checksum for cryptographic comparison. Every start, including restarts on an existing volume, downloads these objects in parallel (TASKCONTEXT_VERIFY_CONCURRENCY, 1–64, default 16) so the server becomes ready within ONCE's fixed 120-second deployment wait; the first failure refuses startup. Recovery stages and checks SQLite and files before atomically installing the database. Frozen starts require matching persisted S3 settings and an existing valid auxiliary.db.
Production runs through the private pocketdeploy-v2 scaffold with separate
taskcontext-files and taskcontext-replica buckets; it moved there from
once-pocketcontext-v2 on 24 October 2026 by recovery from the replica. Keep
credentials in that scaffold's ignored private configuration. Public image pulls
are required by the commandless deployment trigger.
The pocketdeploy-v2 GitHub environment, named by the repository variable
COLORS_PROFILE, supplies the PocketDeploy SSH key and pinned host identity.
CONTEXT_DEPLOY_PAUSED=true pauses deployment while validation and publication
continue. The old-host installer and wrapper are removed. The host deploys with a
stop-first policy: one writer, a 300-second graceful stop and preserved volumes.
There is no automatic rollback. See the
common CI and deployment contract.
Use the pinned server and isolated temporary databases:
python3 tests/integration.py --binary ../pocketcontext/bin/pocketcontext
python3 tests/tracing.py --binary /absolute/path/to/pinned/pocketcontext
python3 tests/skill.py --binary ../pocketcontext/bin/pocketcontext
python3 tests/deploy.py --binary ../pocketcontext/bin/pocketcontext
python3 tests/required_users.py --binary ../pocketcontext/bin/pocketcontext
python3 tests/account_access.py --binary ../pocketcontext/bin/pocketcontext
python3 tests/realtime_access.py --binary ../pocketcontext/bin/pocketcontext
python3 tests/oauth.py
python3 tests/identity_client.py
python3 tests/identity_integration.py --binary ../pocketcontext/bin/pocketcontext
python3 tests/oauth_integration.py --binary ../pocketcontext/bin/pocketcontextIntegration covers concurrent revisions and issue allocation, rejected writes, hierarchy, shared identities, permissions, atomic batches, history, and rollback on audit/directory failures. Skill tests copy the installed skill outside the repository and verify its client, secure cache, and schema contract. Deployment tests check settings, proxy limits, health, and password changes. Required-user tests cover provisioning, preservation, removal protection, recreation after maintenance, and invalid configuration. OAuth tests cover the loopback callback, state and PKCE, private session cache, renewal, and rejected logins; OAuth integration uses a local provider fixture with the pinned server. JIT integration also checks hosted-domain validation, forged fields, existing identity preservation, and disabled-account rejection. Account-access and realtime tests verify revocation, re-enabling, blocked deletion and ordinary-user restrictions. A real Google Workspace login still requires configured credentials and a human browser.
With Docker available:
docker build -t taskcontext:ci .
python3 docker/smoke.py config --image taskcontext:ci
python3 docker/smoke.py smoke --image taskcontext:ci
python3 docker/smoke.py restore --image taskcontext:ciWhen changing the schema, regenerate and review the snapshot with python3 tests/skill.py --binary ../pocketcontext/bin/pocketcontext --write-schema, then update references. Never use local or production pb_data/ for tests.
The pinned server enables an authenticated, bounded in-memory trace buffer for taskcontext. Collection is client opt-in; ordinary commands produce no traces. See optional skill tracing for separate ObserveContext login, private upload, SQL-text consent, delivery retries and measurement limits. No ObserveContext credentials are installed on this server.
The authenticated reader at / provides a collection chooser, server-side text search,
paginated records, collection-specific filters, and outgoing/reverse relationship links.
Use /#/<collection>/<record-id> for a current-record permalink. Renames preserve this
identity; deletion or loss of access may make a link unavailable. Search/filter state is
stored in the hash query, and Copy record link omits that state. Copy search link
shares the current collection/filter view. Links do not grant access or preserve history.
The destination survives password or configured Google sign-in and reload.
Records are read through the existing authenticated SQL endpoint. The browser never queries auth collections, writes business records, or acknowledges anything on opening. Relationship labels use only authorized SQL; unavailable targets reveal no resolved label. User-directory records contain display names only.
The official PocketBase JavaScript SDK stores application tokens in an app-specific
LocalAuthStore in local storage. Sign-in survives reloads, new tabs and browser
restarts until expiry or sign-out. Authentication changes synchronize across tabs;
sign-out clears displayed data and stored credentials but does not revoke copied
tokens. Tokens are accessible to browser JavaScript. Old per-tab sessions are discarded
on upgrade, requiring one fresh sign-in. Active sessions renew on startup/focus at
most once per five minutes per tab; rejected credentials require sign-in. Refresh on focus or
the Refresh button reloads current data.
Markdown never executes HTML or loads remote images. Record metadata is collapsed below business fields. Currency amounts retain their original minor-unit values alongside formatted currency. No mixed-currency totals are calculated.
The reader's explicit navigation model lives in ui/src/config.ts. Keep its schema
snapshot aligned with the exported schema when changing columns; tests/reader.py
compares it with the real authenticated schema. The UI is built into the application
image; for local development build it before starting the ordinary server:
cd ui
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
pnpm exec playwright install chromium
pnpm e2e
cd ..
python3 tests/reader.py --binary /absolute/path/to/pinned/pocketcontext --browserUse Node.js 24 and pnpm 10.33.2. The browser smoke uses synthetic records and an isolated
temporary database. It tests actual production assets, authentication, direct links,
reload, search pagination, mobile navigation, and SQL/schema compatibility. Unit and
mocked browser tests additionally cover query escaping, malformed routes, relationship
labels, inert Markdown, and outside links opening in a new tab. Generated assets are
not committed.
For browser Google OAuth, register the application's own
https://<application-host>/api/oauth2-redirect URI in its existing OAuth client.
Install uv, then run uv venv and uv pip install -e .. Activate .venv before running the Python validation commands above. The full-name command is taskcontext; old script paths and short aliases are removed. The installed skill launcher requires uv and Python 3.11 or later and fetches its package at a full Git commit. Initial installation requires network access.
The implementation and bundled schema live in src/taskcontext_client/; keep its schema snapshot identical to skills/taskcontext/references/schema.json. Publish and test the package commit before updating the launcher to that commit. The ObserveContext dependency is pinned separately. Tracing is inactive unless explicitly enabled by observecontext capture -- taskcontext ...; capture failures must preserve the command result.
For a released launcher, run python3 tests/skill.py --binary /absolute/path/to/pinned/pocketcontext --client /absolute/path/to/copied/taskcontext. This uses a fresh uv cache and isolated synthetic records. Put the real uv binary on PATH when a version-manager shim depends on HOME; authentication tests deliberately use temporary home directories. Source/schema mutation checks use a private package copy.
Superusers inspect GET /api/context/maintenance and toggle with
PUT /api/context/maintenance using {"readOnly":true,"expectedGeneration":N}.
Use the returned generation; wait for confirmed read_only before taking a final
migration snapshot. Active writes drain, subsequent mutations return 503, and
authorized SQL reads and original downloads remain available. Existing sessions
can refresh; login flows requiring writes may fail. Thaw explicitly with
readOnly:false and the current generation. Stale generations return 409.
The private pb_data/maintenance.json marker must travel with a recovery snapshot.
Frozen startup preserves the existing database, settings, OAuth identities and
operator credentials; it skips restore and bootstrap provisioning and refuses
missing databases, unsafe markers or pending migrations. This is not cross-host
fencing: pause CD and stop/disable the source writer before activating a replacement.
Release gates use synthetic data:
python3 tests/entrypoint.py
python3 tests/maintenance.py --binary /absolute/path/to/pinned/pocketcontextMaintenance tests also verify that a frozen restart does not provision newly configured required users, existing operator/user tokens survive, pending migrations fail, and rejected issue creation does not consume the next issue number. The server maintenance suite covers in-flight write draining and managed SQLite guards.
Replicated startup waits for an initial Litestream IPC sync before serving. An
unreachable replica fails startup. Fresh Google-only databases require explicit init
before this handshake; frozen starts always require the existing database. This
ensures clean shutdown can sync even before the first periodic monitor tick.
To store PocketBase API uploads in a private S3-compatible bucket, provide all of
TASKCONTEXT_S3_BUCKET, TASKCONTEXT_S3_ENDPOINT,
TASKCONTEXT_S3_REGION, TASKCONTEXT_S3_ACCESS_KEY_ID, and
TASKCONTEXT_S3_SECRET_ACCESS_KEY. R2 uses region auto and its account S3
endpoint. Optional TASKCONTEXT_S3_FORCE_PATH_STYLE is exactly true or
false, default true. Partial configuration fails startup without logging
credentials. A writable restart with stored S3 enabled requires explicit complete
configuration, preventing accidental fallback to local disk. File credentials must
be scoped to the primary bucket; Litestream uses a different bucket and key.
The production container requires complete S3 settings. Direct local development
with the server binary can still use local file storage.
These credentials and the primary file bucket are separate from the
LITESTREAM_* SQLite replica configuration. This application currently has no
domain attachment feature; the setting also covers PocketBase file fields such
as the default user avatar. It does not add attachment APIs or change file access
rules. Buckets must remain private and downloads go through PocketBase.
Frozen startup requires complete S3 configuration matching stored settings, including credentials, and rejects changes before serving. Direct development-server frozen starts can use local files; the production container always requires S3. Container preflight rejects partial settings and sharing either the primary file bucket or access key with Litestream. Enabling S3 does not copy existing files: reconcile every referenced object and its checksum before switching a production database. Preserve the maintenance marker and stop the old writer before thawing the replacement. Litestream replicates SQLite, not primary bucket contents; plan file retention independently. This container startup refactor has not been deployed. It does not migrate existing files or production databases.
Validate the configuration and frozen-restart contract with:
python3 tests/object_storage.py --binary /absolute/path/to/pinned/pocketcontextThe container release gate also exercises a disposable MinIO service with separate bucket-scoped file and replica credentials. It creates a synthetic protected-file collection without changing the application schema, verifies owner/other-user/ anonymous downloads, freezes and restarts, and makes a late upload with a one-hour replication interval. Recovery compares every logical database row before deleting the source volume, then verifies original and late-upload bytes on the destination. A third phase thaws, uploads again and cleanly stops the second instance, deletes its volume, and checks normal entrypoint recovery into an empty third volume. This path automatically restores SQLite and initializes auxiliary state, without a manually copied marker or auxiliary database. Only one writer runs at a time.
For a planned frozen migration, copy maintenance.json and a consistent
auxiliary.db backup alongside the Litestream-restored data.db. Frozen startup
cannot initialize a missing auxiliary database. The test copies auxiliary state
from the stopped synthetic source with SQLite's backup API and verifies it; this
is not a claim that Litestream currently replicates auxiliary.db.
python3 docker/object_storage_smoke.py --image taskcontext:ciThis gate builds the pinned local MinIO fixture and removes its synthetic containers, volumes and network. It uses no live bucket or production credentials.
Local validation on 6 October 2026 passed image build, container configuration, smoke and populated restore, plus the three-stage primary S3 recovery gate and stale-snapshot/private-copy regression checks. These used the pinned server and isolated synthetic data; images remain local and production has not been changed.
The image checks for expired L0 files every five minutes
(l0-retention-check-interval: 5m) to reduce object-store listing requests.
This delays cleanup and can temporarily retain more local and remote files; it
does not change the default ten-second replication interval, compaction schedule,
minimum L0 retention or snapshot history. Successful L1 compaction can also run
cleanup. Container smoke checks verify the effective interval, and populated
restore checks remain release gates.