apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-09 01:35:18 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Document AWS build variant and bearer-token sources

Browse source 
- docs/deployment.md: new "Token sources" section listing the three
  bearer-token source precedences (AWS SM, JSON file/env, single token).
  New "Build Variants" section explaining default vs aws builds and
  their release-artifact naming. New "AWS Secrets Manager" section
  covering env var, secret payload format, IAM role credential
  discovery, and the hard error for feature-less builds.
- CONTRIBUTING.md: documents the `aws` feature and the two test
  commands contributors should run when touching auth code.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
andrew 2026-04-18 04:04:45 +03:00
parent 7a3bf5c758
commit d830ebcb64
2 changed files with 73 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

60
docs/deployment.md
View file

@ -110,11 +110,65 @@ docker run --rm -p 8080:8080 \
## Auth
The server can run unauthenticated for local development, but any shared or
internet-facing deployment should set:
internet-facing deployment should set a bearer token source.
- `OMNIGRAPH_SERVER_BEARER_TOKEN`
### Token sources
The health endpoint `/healthz` remains suitable for load balancer health checks.
The server reads bearer tokens from one of three places, in precedence order:
1. **AWS Secrets Manager** (build with `--features aws`, see below) — set
`OMNIGRAPH_SERVER_BEARER_TOKENS_AWS_SECRET` to the secret ID or ARN.
2. **JSON file or env** — set one of:
- `OMNIGRAPH_SERVER_BEARER_TOKENS_FILE` — path to a JSON `{"actor": "token", ...}` file.
- `OMNIGRAPH_SERVER_BEARER_TOKENS_JSON` — the JSON literal inline.
3. **Single-token env** — `OMNIGRAPH_SERVER_BEARER_TOKEN` (assigns the
implicit actor `default`).
Tokens are hashed with SHA-256 immediately on ingest; plaintext does not
persist in process memory after startup.
The health endpoint `/healthz` remains suitable for load balancer health checks
and is never gated.
## Build Variants
The server binary ships in two flavors:
| Variant | Command | Contents |
|---------|---------|----------|
| **Default** (on-prem / local dev) | `cargo build --release` | Core server, no AWS SDK |
| **AWS** | `cargo build --release --features aws` | Adds AWS Secrets Manager backend for bearer tokens |
Release artifacts are published with matching suffixes —
`omnigraph-server-<version>-<platform>.tar.gz` for the default build and
`omnigraph-server-<version>-<platform>-aws.tar.gz` for the AWS-enabled build.
The AWS build adds ~150 transitive deps and ~30-60s of first-build compile
time. Default builds don't pay that cost.
## AWS Secrets Manager
When the binary is built with `--features aws`, set
`OMNIGRAPH_SERVER_BEARER_TOKENS_AWS_SECRET` to the ARN or name of a Secrets
Manager secret whose `SecretString` is a JSON object of
`{"actor_id": "token", ...}`:
```bash
omnigraph-server-aws s3://my-bucket/repos/example ...
# Environment:
# OMNIGRAPH_SERVER_BEARER_TOKENS_AWS_SECRET=arn:aws:secretsmanager:us-east-1:123456789012:secret:omnigraph-tokens-AbCdEf
```
Credentials are resolved via the AWS default chain (env vars, shared config,
IMDSv2 instance role, ECS task role) — no explicit credential plumbing is
needed when running under an IAM instance role on EC2/ECS/EKS.
The IAM role must permit `secretsmanager:GetSecretValue` on the referenced
secret.
Setting the env var without building with `--features aws` is a hard error
with a rebuild instruction — it does not silently fall back to the env/file
source.
## S3-Compatible Storage