Skip to content

About

Shared-workspace issue tracking through coding agents, powered by PocketContext

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

TaskContext

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.

Run locally

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.json

Migrations 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.

Provision users

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.

Disable accounts without losing history

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.

Install the skill

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 taskcontext

In 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" check

For 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.

Hosted identity login

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.com

Direct Google fallback setup

An operator configures Google once before users sign in:

  1. 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, and profile.
  2. 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.
  3. Supply TASKCONTEXT_GOOGLE_CLIENT_ID and TASKCONTEXT_GOOGLE_CLIENT_SECRET to the TaskContext server and restart it. Set both together. After PocketBase system bootstrap creates users, 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.
  4. To enable first-login provisioning, set TASKCONTEXT_GOOGLE_WORKSPACE_DOMAIN=pocketcontext.com and restart. The server requires Google as provider, a verified email, a matching Google hd (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-host

Then, 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 --google

Open 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.

Data and write rules

  • Projects have unique immutable keys such as APP. Issue keys such as APP-1 are 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, or subtask; priority low, medium, high, or urgent; an optional assignee; an optional due_date (send YYYY-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, and done. Moving between open statuses is unrestricted. Done requires resolution completed, cancelled, or duplicate. 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, or duplicates. Self-links and duplicate relations are rejected. Retire a link with active=false; current dependency queries filter on active=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_revision from 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.

Container and deployment

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.

Continuous deployment

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.

Validate

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/pocketcontext

Integration 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:ci

When 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.

Request observability

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.

Browser reader and permanent links

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 --browser

Use 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.

Packaged CLI development

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.

Runtime maintenance freeze

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/pocketcontext

Maintenance 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.

Primary file object storage preparation

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/pocketcontext

The 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:ci

This 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.

Litestream cleanup frequency

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.

About

Shared-workspace issue tracking through coding agents, powered by PocketContext

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages