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

Merge pull request #31 from ModernRelay/docs/aws-build-variant

Browse source 
Document AWS build variant and bearer-token sources
This commit is contained in:
Andrew Altshuler 2026-04-18 05:32:25 +03:00 • committed by GitHub
commit 4c298bab12
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 73 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

16
CONTRIBUTING.md
View file

@ -16,6 +16,22 @@ cargo test --workspace
If you touch S3-backed flows, the CI model uses a local RustFS instance for
integration tests.
### Cargo features
`omnigraph-server` has an optional `aws` feature that pulls in the AWS
Secrets Manager SDK for a bearer-token backend. Default builds omit it —
most contributors never compile the AWS code path.
When you touch `crates/omnigraph-server/src/auth.rs` or any AWS-conditional
code, verify both configurations:
```bash
cargo test -p omnigraph-server # default
cargo test -p omnigraph-server --features aws # AWS enabled
```
CI runs both.
## Pull Requests
- keep changes focused

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