Documentation

Self-hosting the OGRL application

Version 0.1.0
Stack Python (FastAPI), PostgreSQL, Next.js
Reading time 14 min
On this page

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.

ComponentRole
ogrl serverFastAPI HTTP server, background job runner, scheduler, and agents. The only process that writes to Postgres. Console entry point ogrl (ogrl.main:run).
Web UINext.js. Reads and writes only through the HTTP API. Proxies /v1 and /health to OGRL_API_ORIGIN (default http://127.0.0.1:8080).
PostgreSQLOrganization database and auth tables. Schema changes ship as Alembic migrations; the server never migrates on startup.
Object storageS3 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.

bash
docker compose up --build
open http://localhost:3000

Services, in start order:

ServiceWhat it does
postgresPostgres 18, user/password/db ogrl, port 5432.
s3SeaweedFS S3 on port 8333, keys from deploy/local/s3.json.
s3-bucketCreates the private ogrl bucket, as the CloudFormation stack does in production.
migrateRuns alembic upgrade head against Postgres, then exits.
apiThe ogrl server on http://localhost:8080. Connection secrets persist in the secrets volume.
seeddeploy/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.
webNext.js UI on http://localhost:3000.

Boot an empty workspace instead of the seeded one:

bash
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:

bash
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:

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

TaskRuns
verify:pyuv run ruff check ., uv run ruff format --check ., uv run pytest -q
verify:webIn web/: pnpm lint, pnpm typecheck, pnpm e2e (Playwright against a mock-mode build)
verifyBoth. Screenshots land in web/e2e/.screenshots/.
bash
mise run verify

#Configuration

The server reads its configuration from the environment. The module docstring of ogrl/main.py is the source of truth.

VariableMeaning
OGRL_PROCESSapi (default) or jobs. See Processes.
OGRL_BINDhost:port to bind. Default 0.0.0.0:8080; falls back to PORT.
OGRL_API_TOKENSJSON 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_PROVIDERSJSON map of OIDC providers: {"okta": {"issuer": "...", "client_id": "...", "client_secret": "...", "redirect_uri": "..."}}.
OGRL_BOOTSTRAP_ADMIN_EMAILSComma-separated emails granted administrator on first OIDC login.
OGRL_ALLOWED_ORIGINSComma-separated extra origins accepted by the cookie CSRF check.
OGRL_LIBRARY_REPOGit repository for the OGRL standard library. See Library source.
OGRL_DATABASE_URLPostgres 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_BUCKETBucket for evidence bytes, document bodies, and render files.
OGRL_S3_ENDPOINTOnly for an S3-compatible server, such as the compose stack.
OGRL_S3_ACCESS_KEY_ID / OGRL_S3_SECRET_ACCESS_KEYThat server's keys. Separate from AWS_*, which stay free for the credentials that assume integration roles.
OGRL_S3_PREFIXKey prefix inside the bucket. Optional.
OGRL_BLOB_DIRA local directory instead of S3. With neither a bucket nor a directory, blobs are kept in memory.
OGRL_EXPORT_REMOTEGit remote for the snapshot. Unset: export is disabled.
OGRL_RUN_SCHEDULERtrue runs the export and integration schedules in this process.
OGRL_EXPORT_INTERVALSeconds between scheduled exports. Default 86400.
OGRL_INTEGRATION_TICKSeconds between scheduled integration test runs. Default 300. Runs where OGRL_RUN_SCHEDULER=true.
OGRL_PUBLIC_URLThe deployment's stable origin, such as https://grc.acme.com. OAuth connections need it for /v1/oauth/callback.
OGRL_SNAPSHOT_REUSESeconds a snapshot may be reused before a run collects again. Default 3600.
OGRL_QUEUE_URLOptional SQS queue URL for job worker wakeups.
OGRL_SSM_PREFIXSSM Parameter Store prefix (for example /ogrl/ogrl) for secrets.
OGRL_HARNESS_USEROperating-system user the shell runner switches to.
OGRL_HARNESS_<NAME>The value of run.env name <NAME> for the harness.
OGRL_INTEGRATIONS_DIRDirectory of unpacked integration packages. Loaded only with OGRL_ALLOW_LOCAL_INTEGRATIONS=true.
OGRL_ALLOW_LOCAL_INTEGRATIONStrue permits the local trust tier (directory packages and unsigned archives). Default false.
OGRL_SECRETS_FILEJSON file for connection secrets when OGRL_SSM_PREFIX is unset. With neither, connection secrets are kept in memory.
OTEL_EXPORTER_OTLP_ENDPOINT / LOGFIRE_TOKENOptional 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=api serves HTTP. OGRL_PROCESS=jobs additionally 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 when EnableJobService is on.
  • With OGRL_QUEUE_URL set, 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:

VariableMeaning
OGRL_AI_MODELExplicit model spec, such as anthropic:claude-sonnet-4-5, openai:gpt-4o, or openai:llama3.2 with OGRL_AI_BASE_URL.
ANTHROPIC_API_KEYEnables Anthropic. Default model anthropic:claude-sonnet-4-5.
OPENAI_API_KEYEnables OpenAI. Default model openai:gpt-4o.
OGRL_AI_BASE_URL / OGRL_AI_API_KEYCustom OpenAI-compatible endpoint and key (OpenRouter, Ollama, LiteLLM, vLLM). A generic key starting sk-ant- selects Anthropic.
OGRL_AI_ACTOR_IDParty 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_DIR points at unpacked packages, loaded only when OGRL_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 need OGRL_ALLOW_LOCAL_INTEGRATIONS=true. Compose sets it; the CloudFormation template does not. See RFC 0005 §4.
  • Connection secrets. Stored in SSM under OGRL_SSM_PREFIX when set, else in OGRL_SECRETS_FILE, else in memory.
  • OAuth connections need OGRL_PUBLIC_URL for /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_TICK seconds 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:

bash
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:

bash
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

ParameterDefaultEffect
EnableServicesfalseStart the tasks. Leave false until images are pushed.
TaskSizesmallAPI task: small 0.25 vCPU/1 GB, medium 0.5/2, large 1/2, xlarge 2/4, 2xlarge 4/8.
CpuArchitectureARM64ARM64 or X86_64. Images must match.
RepositoryPrefixogrlECR repositories prefix/api and prefix/web. One pair per account.
ApiImageTag / WebImageTaglatestImage tags.
EnableJobServicefalseSecond task from the API image runs the schedule and claimed jobs; the API task stops scheduling.
JobTaskSizesmallJob task size.
DatabaseInstanceClassdb.t4g.microdb.t4g.micro through db.t4g.large, single-AZ.
DatabaseAllocatedStorage20Initial gp3 GB. 20 is the minimum.
DatabaseMaxAllocatedStorage100Storage autoscaling ceiling in GB.
DatabaseEngineVersion / DatabaseFamily18.6 / postgres18Keep on the same major version.
DatabaseName / DatabaseUsernameogrl / ogrlInitial database and master user.
DatabasePasswordVersion1SSM version of /ogrl/STACK/database/password. Increment after rotating.
DeletionProtectiontrueSet false before deleting the stack.
DomainNameemptySES identity, and the alias record with a hosted zone and load balancer. Empty skips mail.
PublicUrlemptyStable https:// origin; becomes OGRL_PUBLIC_URL. Needed for OAuth connections.
HostedZoneIdemptyRoute 53 zone for DomainName: SES DKIM records and the load balancer alias. Requires DomainName.
EnableLoadBalancerfalseALB terminating TLS for a stable name. Requires CertificateArn once services are on.
CertificateArnemptyACM certificate in the stack's region.
EnableNatGatewayfalseTasks move to the private subnet behind one NAT gateway; S3 uses a free gateway endpoint. Requires EnableLoadBalancer once services are on.
EnableRdsProxyfalseRDS Proxy in front of Postgres; stores the password in Secrets Manager.
EnableQueuefalseSQS queue and dead-letter queue; sets OGRL_QUEUE_URL.
AvailabilityZoneA / AvailabilityZoneBemptySet 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.

LineRatePer 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 parametersno 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.

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

SettingDestination
none (default)Single-line structured JSON to stdout, collected by CloudWatch Logs on AWS. No trace export.
OTEL_EXPORTER_OTLP_ENDPOINTAny OTLP collector.
LOGFIRE_TOKENHosted 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.