Operator guide for the self-hosted OGRL application: one Python ogrl server process (HTTP API, job worker, scheduler, agents) that is the sole writer to a PostgreSQL organization database, a Next.js web UI that talks to it only over HTTP, and S3-compatible object storage for evidence, document bodies, and rendered files. It covers the local Docker Compose stack, every environment variable the server reads, AI model settings, integrations, the library source, the AWS CloudFormation deployment with its cost figures, observability, and git snapshot export and restore.
#What runs
The application is specified in RFC 0003. The HTTP contract is RFC 0004.
| Component | Role |
|---|---|
ogrl server | FastAPI HTTP server, background job runner, scheduler, and agents. The only process that writes to Postgres. Console entry point ogrl (ogrl.main:run). |
| Web UI | Next.js. Reads and writes only through the HTTP API. Proxies /v1 and /health to OGRL_API_ORIGIN (default http://127.0.0.1:8080). |
| PostgreSQL | Organization database and auth tables. Schema changes ship as Alembic migrations; the server never migrates on startup. |
| Object storage | S3 on AWS, SeaweedFS S3 locally. Evidence blobs, policy and procedure bodies, rendered packages, and installed integration archives. Postgres stores only resource.uri and resource.digest. |
The image is built from the repository Dockerfile: Python 3.13, the prebuilt ogrl-rs wheel (no Rust compiler needed), runs as user ogrl, exposes 8080, defaults OGRL_BIND=0.0.0.0:8080, and health-checks GET /health. The web image builds from web/Dockerfile.
#Local quick start
The compose.yaml stack needs no AWS account.
docker compose up --build
open http://localhost:3000
Services, in start order:
| Service | What it does |
|---|---|
postgres | Postgres 18, user/password/db ogrl, port 5432. |
s3 | SeaweedFS S3 on port 8333, keys from deploy/local/s3.json. |
s3-bucket | Creates the private ogrl bucket, as the CloudFormation stack does in production. |
migrate | Runs alembic upgrade head against Postgres, then exits. |
api | The ogrl server on http://localhost:8080. Connection secrets persist in the secrets volume. |
seed | deploy/local/seed.py: pulls ogrl-library v0.2.0 and a starter organization, "Acme Platform", with NIST 800-171 r3 and SOC 2 programs. Installs the first-party Okta, AWS, and GitHub integration releases. Idempotent. |
web | Next.js UI on http://localhost:3000. |
Boot an empty workspace instead of the seeded one:
OGRL_SKIP_SEED=true docker compose up --build
The compose stack authenticates with a static administrator token, ogrl_pat_local_dev_admin (actor party--local-admin), set through OGRL_API_TOKENS. Do not reuse it outside local development.
AWS integration connections assume their read-only role with the AWS_* credentials present when compose starts. With an aws login session:
eval "$(aws configure export-credentials --format env)" && docker compose up -d api
To enable the AI assistant locally, export ANTHROPIC_API_KEY, OPENAI_API_KEY, or the OGRL_AI_* variables before docker compose up; compose passes them through to api.
#Running without containers
RFC 0003 §9 notes that local development needs no AWS: ogrl runs as a single process against local Postgres. The package is managed with uv, and the commands match the ones compose runs:
uv sync
export OGRL_DATABASE_URL=postgresql://ogrl:ogrl@localhost:5432/ogrl
uv run alembic upgrade head
uv run ogrl
With OGRL_DATABASE_URL unset, the server logs a warning and keeps the organization database in memory. The web app runs from web/ with OGRL_API_ORIGIN=http://127.0.0.1:8080 OGRL_API_TOKEN=... pnpm dev.
#mise tasks
mise.toml defines verification tasks only, not run tasks. mise run verify is the repository's definition of done.
| Task | Runs |
|---|---|
verify:py | uv run ruff check ., uv run ruff format --check ., uv run pytest -q |
verify:web | In web/: pnpm lint, pnpm typecheck, pnpm e2e (Playwright against a mock-mode build) |
verify | Both. Screenshots land in web/e2e/.screenshots/. |
mise run verify
#Configuration
The server reads its configuration from the environment. The module docstring of ogrl/main.py is the source of truth.
| Variable | Meaning |
|---|---|
OGRL_PROCESS | api (default) or jobs. See Processes. |
OGRL_BIND | host:port to bind. Default 0.0.0.0:8080; falls back to PORT. |
OGRL_API_TOKENS | JSON map of static tokens: {"<token>": {"actor_id": "party--...", "roles": ["administrator"], "kind": "person"}}. Tokens start with ogrl_pat_. Only their SHA-256 is kept in memory. |
OGRL_OIDC_PROVIDERS | JSON map of OIDC providers: {"okta": {"issuer": "...", "client_id": "...", "client_secret": "...", "redirect_uri": "..."}}. |
OGRL_BOOTSTRAP_ADMIN_EMAILS | Comma-separated emails granted administrator on first OIDC login. |
OGRL_ALLOWED_ORIGINS | Comma-separated extra origins accepted by the cookie CSRF check. |
OGRL_LIBRARY_REPO | Git repository for the OGRL standard library. See Library source. |
OGRL_DATABASE_URL | Postgres URL (postgresql://...). If unset, assembled from OGRL_DATABASE_HOST, _PORT (default 5432), _NAME (default ogrl), _USER (default ogrl), _PASSWORD, _SSLMODE, which is how CloudFormation configures it. If neither is set, an ephemeral in-memory store is used. |
OGRL_S3_BUCKET | Bucket for evidence bytes, document bodies, and render files. |
OGRL_S3_ENDPOINT | Only for an S3-compatible server, such as the compose stack. |
OGRL_S3_ACCESS_KEY_ID / OGRL_S3_SECRET_ACCESS_KEY | That server's keys. Separate from AWS_*, which stay free for the credentials that assume integration roles. |
OGRL_S3_PREFIX | Key prefix inside the bucket. Optional. |
OGRL_BLOB_DIR | A local directory instead of S3. With neither a bucket nor a directory, blobs are kept in memory. |
OGRL_EXPORT_REMOTE | Git remote for the snapshot. Unset: export is disabled. |
OGRL_RUN_SCHEDULER | true runs the export and integration schedules in this process. |
OGRL_EXPORT_INTERVAL | Seconds between scheduled exports. Default 86400. |
OGRL_INTEGRATION_TICK | Seconds between scheduled integration test runs. Default 300. Runs where OGRL_RUN_SCHEDULER=true. |
OGRL_PUBLIC_URL | The deployment's stable origin, such as https://grc.acme.com. OAuth connections need it for /v1/oauth/callback. |
OGRL_SNAPSHOT_REUSE | Seconds a snapshot may be reused before a run collects again. Default 3600. |
OGRL_QUEUE_URL | Optional SQS queue URL for job worker wakeups. |
OGRL_SSM_PREFIX | SSM Parameter Store prefix (for example /ogrl/ogrl) for secrets. |
OGRL_HARNESS_USER | Operating-system user the shell runner switches to. |
OGRL_HARNESS_<NAME> | The value of run.env name <NAME> for the harness. |
OGRL_INTEGRATIONS_DIR | Directory of unpacked integration packages. Loaded only with OGRL_ALLOW_LOCAL_INTEGRATIONS=true. |
OGRL_ALLOW_LOCAL_INTEGRATIONS | true permits the local trust tier (directory packages and unsigned archives). Default false. |
OGRL_SECRETS_FILE | JSON file for connection secrets when OGRL_SSM_PREFIX is unset. With neither, connection secrets are kept in memory. |
OTEL_EXPORTER_OTLP_ENDPOINT / LOGFIRE_TOKEN | Optional telemetry destinations. See Observability. |
AWS_REGION or AWS_DEFAULT_REGION sets the region for S3, SQS, SSM, and STS clients.
The web container reads OGRL_API_ORIGIN (default http://127.0.0.1:8080) and, locally, OGRL_API_TOKEN.
#Processes
Detail: RFC 0003 §2.
OGRL_PROCESS=apiserves HTTP.OGRL_PROCESS=jobsadditionally runs the job worker loop.- Long-running operations (library pulls, provider imports, test runs, renders, git exports, restores, integration installs, collections) are stored as job rows and return
202 Accepted. Workers atomically claim a row before running it, so concurrent processes never run a job twice. - The scheduler runs in whichever process sets
OGRL_RUN_SCHEDULER=true: the API process in the default single-task deployment, or the job service whenEnableJobServiceis on. - With
OGRL_QUEUE_URLset, an API process that does not run the scheduler enqueues the job ID after writing the row. The message is a wake-up hint; the database claim stays authoritative, so redeliveries are no-ops. Unacknowledged messages reappear after two hours and move to the dead-letter queue after five deliveries.
#AI assistant
Agents are optional. With no model configured they are omitted and the rest of the application runs unchanged. Agents use the same write paths as people and are blocked in code from crossing human review gates; see RFC 0003 §4. Configuration lives in ogrl/agent/config.py:
| Variable | Meaning |
|---|---|
OGRL_AI_MODEL | Explicit model spec, such as anthropic:claude-sonnet-4-5, openai:gpt-4o, or openai:llama3.2 with OGRL_AI_BASE_URL. |
ANTHROPIC_API_KEY | Enables Anthropic. Default model anthropic:claude-sonnet-4-5. |
OPENAI_API_KEY | Enables OpenAI. Default model openai:gpt-4o. |
OGRL_AI_BASE_URL / OGRL_AI_API_KEY | Custom OpenAI-compatible endpoint and key (OpenRouter, Ollama, LiteLLM, vLLM). A generic key starting sk-ant- selects Anthropic. |
OGRL_AI_ACTOR_ID | Party ID stamped onto agent drafts. Default party--ogrl-agent. |
On AWS, the stack's ConfigurationPrefix output names model/api-key under the SSM prefix as the place for a model key. The template's task definitions do not set any of the variables above.
#Integrations
Integrations are specified in RFC 0005; see also Integrations and the Integration SDK.
- Installed archives. An install records a row and copies the archive into object storage under
integrations/<id>/<version>/<digest>.tar.gz. Each process fetches and verifies it on first use and holds it in memory; nothing is unpacked to disk. - Directory packages.
OGRL_INTEGRATIONS_DIRpoints at unpacked packages, loaded only whenOGRL_ALLOW_LOCAL_INTEGRATIONS=true. If the directory is set without that flag, the server logs a warning and ignores it. - Trust tier. Until Sigstore verification ships with the registry, every archive installs as
local, so archive installs also needOGRL_ALLOW_LOCAL_INTEGRATIONS=true. Compose sets it; the CloudFormation template does not. See RFC 0005 §4. - Connection secrets. Stored in SSM under
OGRL_SSM_PREFIXwhen set, else inOGRL_SECRETS_FILE, else in memory. - OAuth connections need
OGRL_PUBLIC_URLfor/v1/oauth/callback(RFC 0005 §5). - AWS connections assume each connection's role with the process's
AWS_*credentials. - Schedule. Integration test runs fire every
OGRL_INTEGRATION_TICKseconds in the scheduler process.
#Library source
OGRL_LIBRARY_REPO is the git repository the server pulls the standard library from. Unset, it uses a local library/ or ../ogrl-library/library checkout if present, else https://github.com/adversitydotdev/ogrl-library. Library pulls run as jobs. Once an organization pulls a pinned library revision, its database is the source of truth for its program. Library building and linting use the standalone CLI; see CLI.
#Production on AWS
deploy/aws/template.yaml provisions networking, RDS for PostgreSQL, a private S3 bucket, two ECR repositories (<prefix>/api, <prefix>/web), task definitions, IAM roles, CloudWatch log groups, and an SES domain identity when a domain is given. Leaving the SES sandbox is an account-level step for the operator. Topology rationale: RFC 0003 §9.
Default topology: one Linux/ARM Fargate task (0.25 vCPU, 1 GB) running the ogrl and web containers, and one single-AZ db.t4g.micro with 20 GB gp3. No load balancer, NAT gateway, RDS Proxy, or SQS. The task sits in a public subnet and reaches git remotes and model APIs directly. The web container owns the public port: 443 with TLS terminated on the task, or 3000 behind the load balancer. It proxies /v1 and /health to the API over loopback. RDS sits in a private subnet reachable only from the task security groups.
#Deploy
CloudFormation cannot create SecureStrings, so write the database password before the first apply:
aws ssm put-parameter \
--name /ogrl/ogrl/database/password \
--type SecureString \
--value 'replace-with-at-least-16-characters'
aws cloudformation deploy \
--template-file deploy/aws/template.yaml \
--stack-name ogrl \
--capabilities CAPABILITY_IAM
The password cannot contain a slash, an at-sign, a quote, or a space. The stack name ogrl is the path on the log groups and the SSM prefix (/ogrl/<stack>). After rotating the password, deploy again with DatabasePasswordVersion set to the new SSM version so the database picks it up.
The first apply leaves EnableServices false so the ECR repositories exist before images do. Push the API and web images, built for CpuArchitecture, to the ApiRepositoryUri and WebRepositoryUri outputs, then deploy again with services on:
aws cloudformation deploy \
--template-file deploy/aws/template.yaml \
--stack-name ogrl \
--capabilities CAPABILITY_IAM \
--parameter-overrides EnableServices=true
With TLS on the task, put the PEM certificate at tls/certificate and the key at tls/private-key under the SSM prefix before the first apply. Harness values go under harness/.
The API task runs OGRL_PROCESS=api with OGRL_RUN_SCHEDULER=true unless EnableJobService is on; the job task runs OGRL_PROCESS=jobs with the scheduler. Both receive the OGRL_DATABASE_* settings (with sslmode=require), OGRL_S3_BUCKET, OGRL_SSM_PREFIX, OGRL_PUBLIC_URL, and OGRL_QUEUE_URL. The password is injected from SSM. Schema migrations (alembic upgrade head) are a separate step; the server does not run them.
#Parameters
| Parameter | Default | Effect |
|---|---|---|
EnableServices | false | Start the tasks. Leave false until images are pushed. |
TaskSize | small | API task: small 0.25 vCPU/1 GB, medium 0.5/2, large 1/2, xlarge 2/4, 2xlarge 4/8. |
CpuArchitecture | ARM64 | ARM64 or X86_64. Images must match. |
RepositoryPrefix | ogrl | ECR repositories prefix/api and prefix/web. One pair per account. |
ApiImageTag / WebImageTag | latest | Image tags. |
EnableJobService | false | Second task from the API image runs the schedule and claimed jobs; the API task stops scheduling. |
JobTaskSize | small | Job task size. |
DatabaseInstanceClass | db.t4g.micro | db.t4g.micro through db.t4g.large, single-AZ. |
DatabaseAllocatedStorage | 20 | Initial gp3 GB. 20 is the minimum. |
DatabaseMaxAllocatedStorage | 100 | Storage autoscaling ceiling in GB. |
DatabaseEngineVersion / DatabaseFamily | 18.6 / postgres18 | Keep on the same major version. |
DatabaseName / DatabaseUsername | ogrl / ogrl | Initial database and master user. |
DatabasePasswordVersion | 1 | SSM version of /ogrl/STACK/database/password. Increment after rotating. |
DeletionProtection | true | Set false before deleting the stack. |
DomainName | empty | SES identity, and the alias record with a hosted zone and load balancer. Empty skips mail. |
PublicUrl | empty | Stable https:// origin; becomes OGRL_PUBLIC_URL. Needed for OAuth connections. |
HostedZoneId | empty | Route 53 zone for DomainName: SES DKIM records and the load balancer alias. Requires DomainName. |
EnableLoadBalancer | false | ALB terminating TLS for a stable name. Requires CertificateArn once services are on. |
CertificateArn | empty | ACM certificate in the stack's region. |
EnableNatGateway | false | Tasks move to the private subnet behind one NAT gateway; S3 uses a free gateway endpoint. Requires EnableLoadBalancer once services are on. |
EnableRdsProxy | false | RDS Proxy in front of Postgres; stores the password in Secrets Manager. |
EnableQueue | false | SQS queue and dead-letter queue; sets OGRL_QUEUE_URL. |
AvailabilityZoneA / AvailabilityZoneB | empty | Set both or neither. Empty uses the region's first two AZs. |
RFC 0003 recommends raising TaskSize and the RDS class before splitting out a job service, and enabling the load balancer once a stable DNS name across task replacements is needed. Without it, the API service's public address changes when the task is replaced.
Outputs include BucketName, ApiRepositoryUri, WebRepositoryUri, ConfigurationPrefix, DatabaseEndpoint, ClusterName, the service names, and, when enabled, QueueUrl, ProxyEndpoint, LoadBalancerDnsName, ApplicationUrl, and the SES DKIM records.
#Estimated monthly cost
From the repository README. AWS on-demand list prices for US East (N. Virginia) as of 9 November 2026; 730-hour month; 12-month free tier not subtracted. The two containers share one task, so vCPU and memory are billed once.
| Line | Rate | Per month |
|---|---|---|
| Fargate, 0.25 vCPU | $0.03238 per vCPU-hour | $5.91 |
| Fargate, 1 GB memory | $0.00356 per GB-hour | $2.60 |
| Public IPv4 on the task | $0.005 per hour | $3.65 |
RDS for PostgreSQL, db.t4g.micro | $0.016 per hour | $11.68 |
| RDS gp3, 20 GB | $0.115 per GB-month | $2.30 |
| S3 Standard, 5 GB of evidence | $0.023 per GB-month | $0.12 |
| SSM Parameter Store, standard parameters | no charge | $0.00 |
| SES, no mail sent | $0.10 per 1,000 messages | $0.00 |
| CloudWatch Logs, under 5 GB | $0.50 per GB ingested after the included 5 GB | $0.00 |
| Total | $26.26 |
That is the idle bill: the task and database run all month, evidence is about 5 GB, and mail, logs, and data transfer stay inside the included amounts. Automated backups up to the 20 GB volume are included. Not included: the model provider's token bill, data transfer out past 100 GB ($0.09 per GB), backup storage past 20 GB, SES once it sends, and ECR storage ($0.10 per GB-month). Before EnableServices is true the bill is the database, about $13.98.
| Change | Added per month |
|---|---|
EnableJobService at small | $12.16, the second task ($8.51) and its public IPv4 ($3.65) |
EnableLoadBalancer | $23.73 before any traffic: the balancer at $0.0225 per hour ($16.43) and a public IPv4 in each of two zones ($7.30). LCUs are $0.008 per LCU-hour on top. |
EnableNatGateway | $36.50 before any data: the gateway at $0.045 per hour ($32.85) and its public IPv4 ($3.65). Data through it is $0.045 per GB. Each task that moves private drops its own $3.65 address. The gateway bills even while no task is running. |
EnableRdsProxy | $22.30 for a db.t4g.micro: $0.015 per vCPU-hour and that class has 2 vCPUs ($21.90), plus $0.40 for the Secrets Manager secret the proxy requires. It bills whether or not a task is connected. |
EnableQueue | $0 at one worker. SQS includes 1 million requests a month, and a long poll every 20 seconds stays under that. After the free tier, requests are $0.40 per million. |
TaskSize and DatabaseInstanceClass move the existing lines; medium is 0.5 vCPU and 2 GB.
#Observability
Detail: RFC 0003 §11. Application code logs through Python logging; ogrl/telemetry.py is the only module that configures Logfire or OpenTelemetry.
| Setting | Destination |
|---|---|
| none (default) | Single-line structured JSON to stdout, collected by CloudWatch Logs on AWS. No trace export. |
OTEL_EXPORTER_OTLP_ENDPOINT | Any OTLP collector. |
LOGFIRE_TOKEN | Hosted Logfire. |
OGRL_LOG_LEVEL sets the log level (default INFO). OTEL_SERVICE_NAME sets the service name (default ogrl). Trace export needs the optional telemetry extra (logfire[fastapi,sqlalchemy,httpx]). The Dockerfile installs without extras, so in the stock image a configured endpoint logs a warning and falls back to JSON stdout.
#Backups and export
Git snapshot export (RFC 0002 §8). Set OGRL_EXPORT_REMOTE to a git remote the organization controls. The scheduler process then exports every OGRL_EXPORT_INTERVAL seconds (default daily); POST /exports/git triggers one on demand. A snapshot holds every organization-owned object, policy and procedure bodies, a bundle manifest pinning the library and provider bundles, and read-only provider projections. Evidence blobs are not committed; only their metadata with resource.uri and resource.digest. The export commits only when the tree changed and pushes without pulling. If the remote has commits the job did not produce, export halts and alerts. The running tool never reads the snapshot back. The CloudFormation template does not set OGRL_EXPORT_REMOTE, so export is off until you add it.
Restore. POST /restore loads a snapshot at a given commit into an empty organization database and returns 409 Conflict if any organization objects exist. It pulls the pinned library, verifies provider projections against their digests, validates the whole graph, and copies evidence blobs into the new deployment's object storage. Revision history restarts at the restore time, so RFC 0002 advises keeping database backups alongside git snapshots when historical audit playback matters.
Database backups. On AWS, RDS automated backups are included up to the size of the 20 GB volume.
OSCAL. POST /programs/{id}/renders with view: oscal renders the OSCAL package as a job.