+ This page is the exhaustive reference. For the short path — the required secrets plus a
+ conservative first-boot config — start with .env.selfhost.example in{" "}
+ Quickstart instead.
+
- The sample env contains placeholders only. Keep your real .env out of git and
- prefer mounted secret files for multiline values like the GitHub App private key.
+ .env.selfhost.example is the short path: required secrets plus a conservative
+ first-boot config, with nothing about the Cloudflare Worker deploy. Copy it and fill in the
+ placeholders — keep your real .env out of git and prefer mounted secret files
+ for multiline values like the GitHub App private key.
.env.selfhost.example already ships a conservative starting config —{" "}
+ dry-run mode, a small repo allowlist, unified comments, safety, and grounding,
+ with AI, RAG, and REES left off. Switch to live only after webhook delivery, logs, and
+ review output match expectations. For every optional env var (observability, backup,
+ additional AI providers) see .env.example's self-host section or the{" "}
+ generated reference table.
+
- Begin with a small allowlist, unified comments, safety, and grounding. Leave AI, RAG, and
- REES off until webhook delivery and deterministic review are working.
+ Skip this step for a fully deterministic review (no AI). Otherwise uncomment ONE block in{" "}
+ .env.selfhost.example — Claude Code, Codex, or both. The self-host image
+ bundles both CLIs by default; credentials and provider choice are runtime-only.
dry-run computes reviews but suppresses writes. Switch to live only after
- webhook delivery, logs, and review output match expectations.
+ auth.json on the same filesystem that
+ prompt-influenced reviews can read, so it requires explicit opt-in (
+ GITTENSORY_ENABLE_UNSAFE_CODEX_REVIEWER=1) and a mounted{" "}
+ /data/codex auth volume. Claude Code has no equivalent restriction. See{" "}
+ AI providers for the full reference.
+ Recommended: pull the published image. No local build, no Node toolchain — + the script pulls, restarts, and waits for the health check to pass. +
+ Pin a specific release instead of :latest, or point at your own registry:
+
docker compose up -d --build builds the gittensory service from
+ the checkout instead of pulling a published image. Everything else on this page (env, health
+ checks, GitHub App) is identical either way.
+
+ Nothing below needs a flag to start; everything past the first row needs an explicit{" "}
+ --profile (combine freely) or an explicit AI_PROVIDER.
+
ORB_AIR_GAP=true for an air-gapped instance that sends nothing.
+
Point your App webhook to https://your-host.example/v1/github/webhook, set the
@@ -105,6 +172,13 @@ selfhost_ai_provider # only when AI_PROVIDER is set
selfhost_job_dead # investigate immediately if present
review_context_fetch_failed # REES/RAG/grounding context failure`}
/>
+
+ A cold first boot on SQLite commonly logs a one-time{" "}
+ selfhost_migrations_applied burst and a brief Redis connection retry while the
+ sidecar finishes starting — both are expected and stop once the stack is warm. Anything else
+ that looks wrong, or a /ready that stays unhealthy past a couple minutes, is
+ covered in Troubleshooting.
+
After the deterministic path is stable, continue with{" "}
Configuration and then layer in AI, REES,
diff --git a/docker-compose.yml b/docker-compose.yml
index b69db76494..8b7a971862 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,7 +1,12 @@
-# One-command self-host for gittensory (#980): docker compose up --build
+# Self-host for gittensory (#980). Two ways to boot the `gittensory` service — everything else on
+# this page (profiles, env, health checks) is identical either way:
#
-# SECRETS: copy .env.example → .env, fill in your GitHub App credentials and any optional secrets.
-# The file is gitignored. Every value below is a sample placeholder — never commit real secrets.
+# RECOMMENDED: ./scripts/deploy-selfhost-image.sh # pulls the published image, no local build
+# Building from source: docker compose up --build # for contributors / custom Dockerfile changes
+#
+# SECRETS: copy .env.selfhost.example → .env (the focused self-host starter) or .env.example → .env
+# (the exhaustive reference) and fill in your GitHub App credentials and any optional secrets. The
+# file is gitignored. Every value in either sample is a placeholder — never commit real secrets.
#
# PROFILES — activate optional services by passing --profile
- Skip this step for a fully deterministic review (no AI). Otherwise uncomment ONE block in{" "}
-
- Nothing below needs a flag to start; everything past the first row needs an explicit{" "}
-
Point your App webhook to
+ Nothing below needs a flag to start; everything past the first row needs an explicit{" "}
+ 2. Choose your AI provider (optional)
.env.selfhost.example — Claude Code, Codex, or both. The self-host image
- bundles both CLIs by default; credentials and provider choice are runtime-only.
+ Skip this step for a fully deterministic review (no AI). Otherwise uncomment ONE of the
+ three blocks below in .env.selfhost.example — they're mutually exclusive, each
+ sets its own AI_PROVIDER. The self-host image bundles both CLIs by default;
+ credentials and provider choice are runtime-only.
auth.json on the same filesystem that
@@ -103,8 +107,8 @@ GITTENSORY_IMAGE=ghcr.io/jsonbored/gittensory-selfhost@sha256:... ./scripts/depl
docker compose up -d --build builds the gittensory service from
- the checkout instead of pulling a published image. Everything else on this page (env, health
- checks, GitHub App) is identical either way.
+ the checkout instead of pulling a published image. Everything else in this quickstart (env,
+ health checks, GitHub App) is identical either way.
Defaults at a glance
- --profile (combine freely) or an explicit AI_PROVIDER.
- ORB_AIR_GAP=true for an air-gapped instance that sends nothing.
- 4. Install or connect the GitHub App
https://your-host.example/v1/github/webhook, set the
@@ -184,6 +157,38 @@ review_context_fetch_failed # REES/RAG/grounding context failure`}
Configuration and then layer in AI, REES,
or RAG deliberately.
Defaults at a glance
+ --profile (combine freely) or an explicit AI_PROVIDER.
+ ORB_AIR_GAP=true for an instance that sends nothing.
+