Runbook: DocStore

Runbook: DocStore

Last updated: 2026-03-30 Service owner: ODS Platform Team Pipeline status: STAGING_VERIFIED

1. Service Overview

DocStore is the document management microservice for the ODS Platform. It provides CRUD for documents, folders, tags, versioning, and a multi-tenant audit log. All document metadata is stored in PostgreSQL; events are published to Redpanda.

Property Value
Language Rust (Actix-web)
Container port 8080
DB schema docstore on ods database
DB tables documents, document_versions, document_tags, folders, tags, audit_log
Event bus topic events.docstore
Coolify app UUID fk0s044c8sw4ck80cosg4k0g
RLS enabled Yes

2. Health Check

Endpoint: GET /health Expected response: HTTP 200

curl -sf https://docstore.staging.orbusdigital.com/health

3. Staging URL

https://docstore.staging.orbusdigital.com

4. Environment Variables

Variable Required Description
DATABASE_URL Yes postgres://ods:***@ods-postgres:5432/ods (schema set via search_path or code)
RUST_LOG No Log level (default info)
SERVICE_PORT No Listen port (default 8080)
SERVICE_NAME No Service identifier (default docstore)
REDPANDA_BROKERS No Kafka broker address
REDPANDA_TOPIC No Event topic (default events.docstore)
OID_JWKS_URL Yes http://oid:8080/.well-known/jwks.json
OID_ISSUER Yes https://oid.staging.orbusdigital.com
OID_PUBLIC_KEY Alt RSA public key (PEM) if not using JWKS URL
CORS_ALLOWED_ORIGINS No Comma-separated allowed origins
MAX_BODY_SIZE_BYTES No Max request body (default 1MB)

5. How to Deploy

Via Coolify API

source ~/.env.adlc 2>/dev/null
curl -sf -X POST "https://app.coolify.io/api/v1/applications/fk0s044c8sw4ck80cosg4k0g/restart" \
  -H "Authorization: Bearer $COOLIFY_TOKEN"

Git-based deploy

Push to the staging branch of the docstore repository. Coolify auto-deploys.

6. How to Check Logs

# On srv-staging (35.195.54.220):
docker logs --tail 200 -f $(docker ps -qf "label=coolify.applicationId=fk0s044c8sw4ck80cosg4k0g")

7. Common Issues and Fixes

Issue: Cross-tenant data leakage (MT-009)

Context: Previously identified and fixed. Audit log entries were visible across tenants.

Verification:

curl -sf -H "Authorization: Bearer $TOKEN_TENANT_A" \
  https://docstore.staging.orbusdigital.com/api/audit | jq '.[] | .tenant_id' | sort -u
# Should show only tenant A's ID

Issue: OID JWKS unreachable

Symptom: All authenticated requests return 401/500.

Fix: Verify OID container is running and reachable from docstore:

docker exec <docstore_container> curl -sf http://oid:8080/.well-known/jwks.json

Issue: Migration failures on startup

Symptom: Container exits immediately, logs show SQL migration errors.

Fix: Check migration files in migrations/ directory. Connect to DB and verify schema state:

psql "postgres://ods:ods-dev-2026@127.0.0.1:5433/ods" -c "SET search_path TO docstore; \dt"

8. How to Restart

docker restart $(docker ps -qf "label=coolify.applicationId=fk0s044c8sw4ck80cosg4k0g")

9. Dependencies

Dependency Type Details
PostgreSQL 17 Database ods-postgres:5432, schema docstore, 6 tables, RLS enabled
Redpanda Event bus redpanda:9092, topic events.docstore
OID Auth JWKS endpoint for JWT verification

10. Monitoring / Alerting