Deployment

Onprest OSS deployment is the gateway binary plus the agent binary.

Deployment Units

The repository does not need to be deployed from source. Build artifacts can be copied to another directory or host.

New Customer Setup

1. Generate an agent key pair with onprest-gateway create-agent-secret.
2. Generate one or more API keys with onprest-gateway create-key.
3. Create a customer-specific gateway.env.
4. Start a dedicated gateway process for the customer.
5. Deliver onprest-agent and a capability.yaml template to the on-prem environment.
6. Fill in gateway URL, agent private key, DB credentials, and capabilities.
7. Start the agent.
8. Verify /healthz, /openapi.json, REST, and MCP.

Binary Deployment

This is the primary deployment path for legacy environments without Docker.

set -a
. ./gateway.env
set +a
./onprest-gateway

./onprest-agent --config ./capability.yaml

Keep the agent binary and capability.yaml together. Agent local logs are written next to the agent binary.

Self-Hosted Minimal Settings

For a self-hosted gateway, configure at least:

GATEWAY_AGENT_PUBLIC_KEY=base64url-ed25519-public-key
GATEWAY_API_KEYS_JSON='[{"name":"internal","key_hash":"$2a$10$xxxxx","capabilities":["*"]}]'

Then decide whether to set:

• GATEWAY_ADDR when the default listen address :8080 is not suitable.
• GATEWAY_PUBLIC_URL for reverse proxy or load balancer deployments so OpenAPI servers points at the external URL.
• GATEWAY_CORS_ALLOWED_ORIGINS when browser-based clients on another origin need to call gateway directly.
• GATEWAY_IP_ALLOW_LIST for caller IP restrictions.
• GATEWAY_TRUSTED_PROXY_CIDRS when running behind a reverse proxy or load balancer.
• GATEWAY_RATE_LIMIT_REQUESTS_PER_SECOND and GATEWAY_RATE_LIMIT_BURST for per-source rate limiting.
• GATEWAY_EMIT_OPENAPI_SNAPSHOT=true only when an operator needs the full OpenAPI document on gateway stdout for collection.

For the agent, configure capability.yaml and pass it with --config. If --config and AGENT_CAPABILITY_FILE are both omitted, the agent reads capability.yaml next to the onprest-agent binary. AGENT_CAPABILITY_FILE remains available for environments that prefer env-based configuration:

AGENT_CAPABILITY_FILE=/path/to/capability.yaml

For OS-managed binary operation, register the agent and start it through the host service manager:

./onprest-agent service install --config /absolute/path/capability.yaml
./onprest-agent service start
./onprest-agent service status
./onprest-agent service stop
./onprest-agent service uninstall

service install can omit --config; in that case it registers capability.yaml next to the onprest-agent binary. It does not enable automatic start on OS boot. Configure boot-time startup separately with the host OS if required.

When the agent runs as an OS service, stdout/stderr are handled by the service manager. On macOS service installs, process events go to /var/log/onprest-agent.stdout.log and fatal stderr output goes to /var/log/onprest-agent.stderr.log. DB-specific detail still belongs in onprest-agent.log next to the agent binary.

Docker Optional Usage

Docker images and Docker Compose are supported operational paths, but Docker is not required by the OSS core. Container env-file handling must preserve GATEWAY_API_KEYS_JSON and bcrypt $ characters.

docker build --build-arg TARGET=gateway -t onprest-gateway .
docker build --build-arg TARGET=agent -t onprest-agent .

When running the agent container, mount capability.yaml and pass it to the container entrypoint:

docker run --rm -v "$PWD/capability.yaml:/config/capability.yaml:ro" onprest-agent --config /config/capability.yaml

The mounted capability.yaml must use database and gateway addresses reachable from inside the container. Container platforms manage process start/stop and stdout/stderr collection. Do not use onprest-agent service install inside a container. docker-compose.yml is a convenience for local or container-based evaluation, not a required production deployment model.

Reverse Proxy Optionality

TLS termination and reverse proxy selection are outside the OSS implementation boundary. The gateway works directly exposed or behind a compatible reverse proxy / LB.

OSS and Managed

Onprest is dual-distributed:

• OSS: self-host the gateway and agent on your own infrastructure.
• Managed: Onprest operates the customer-dedicated gateway, monitors agent connectivity, handles patching, retains operational logs, and takes responsibility for the connection layer.

Both use the same OSS core. You can move from managed to self-hosted with the same binaries and capability.yaml. Your database, SQL, credentials, and capability definitions stay under your control.