Skip to main content
The backend serves orchestration APIs, GitHub app endpoints, and internal APIs used by the UI. Use this page when you want to stop only orchestrator in Compose and run backend from source for faster changes. 
make -C self-hosting/docker-compose all-up
docker compose -f self-hosting/docker-compose/docker-compose.yml stop orchestrator
Run make -C ... from repo root, or run make all-up from self-hosting/docker-compose. If UI stays in Docker, point UI to host backend:
  • ORCHESTRATOR_BACKEND_URL=http://host.docker.internal:3000
If UI runs on host, use ORCHESTRATOR_BACKEND_URL=http://localhost:3000 in ui/.env.local.

​
Quick start

  1. Create backend/.env with the essentials (adjust DB URL/ports): 
    DATABASE_URL=postgres://postgres:postgres-password-CHANGE_ME@localhost:5432/orchestrator?sslmode=disable
DIGGER_INTERNAL_SECRET=orchestrator-secret          # must match UI ORCHESTRATOR_BACKEND_SECRET
DIGGER_ENABLE_INTERNAL_ENDPOINTS=true               # enables /_internal/*
DIGGER_ENABLE_API_ENDPOINTS=true                    # enables /api/*
PUBLIC_BASE_URL=http://localhost:3000               # public URL used for GitHub app callbacks
INTERNAL_BASE_URL=http://localhost:3000             # internal backend URL
    Optional but useful:
    • GITHUB_APP_ID, GITHUB_APP_PEM, GITHUB_APP_WEBHOOK_SECRET if you already have an app.
    • GITHUB_ORG if you want /github/setup to target an org.
  2. Start the service (from backend/): 
    set -a; source .env; set +a
go run main.go              # or: make start
    Default port: 3000.

​
Sync organization and user for UI flows

  • The UI calls /api/* and /github/* with Authorization: Bearer $DIGGER_INTERNAL_SECRET and DIGGER_ORG_ID/DIGGER_USER_ID headers.
  • You must upsert the WorkOS org + user the UI is authenticated as: 
    SECRET=$DIGGER_INTERNAL_SECRET
ORG_ID=org_xxx                           # WorkOS org id
ORG_NAME=my-org                          # slug shown in backend
ADMIN_EMAIL=you@example.com
USER_ID=user_xxx                         # WorkOS user id
USER_EMAIL=$ADMIN_EMAIL

# org
curl -s -X POST http://localhost:3000/_internal/api/upsert_org \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"org_name":"'"$ORG_NAME"'","external_source":"workos","external_id":"'"$ORG_ID"'","admin_email":"'"$ADMIN_EMAIL"'"}'

# user
curl -s -X POST http://localhost:3000/_internal/api/create_user \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"external_source":"workos","external_id":"'"$USER_ID"'","email":"'"$USER_EMAIL"'","external_org_id":"'"$ORG_ID"'"}'

​
GitHub app integration

  • For a quick install link, set ORCHESTRATOR_GITHUB_APP_URL in UI config to your app install URL (https://github.com/apps/<app>/installations/new).
  • To create a new app via the backend, open http://localhost:3000/github/setup (requires PUBLIC_BASE_URL and INTERNAL_BASE_URL configured).
  • When using ngrok, callbacks should target the UI tunnel domain, not direct backend localhost URLs.

​
Troubleshooting

  • 404 on /api/repos: ensure DIGGER_ENABLE_API_ENDPOINTS=true and the org/user above are created.
  • 401/403: verify Authorization header uses DIGGER_INTERNAL_SECRET.
  • GitHub connect 404: set ORCHESTRATOR_GITHUB_APP_URL as described.