Deploy — Orionis

1. Run with Docker

The published auth-server image is available from Docker Hub and GHCR for linux/amd64 and linux/arm64. Pin a release tag in deployed environments.

docker pull stremovskyy/orionis:0.6.0
# Equivalent mirror:
docker pull ghcr.io/stremovskyy/orionis:0.6.0

From the repository root, create a local config and start the release image. The read-only config mount and named volume keep configuration and generated demo keys separate.

test -f config/orionis.json || cp config/orionis.example.json config/orionis.json

docker run --rm -d \
  --name orionis-auth \
  -p 8080:8080 \
  -v "$PWD/config:/app/config:ro" \
  -v orionis-var:/app/var \
  stremovskyy/orionis:0.6.0

Or use Compose.

Use this as an alternative to the command above; both bind port 8080.

test -f config/orionis.json || cp config/orionis.example.json config/orionis.json
ORIONIS_IMAGE_TAG=0.6.0 docker compose -f docker-compose.release.yml up -d

To run the full source-built demo stack, including billing and orders, use:

docker compose up --build --wait -d orionis-auth billing-api
docker compose run --rm orders-client

2. Choose your configuration

Local files and AWS AppConfig accept JSON or YAML. Orionis detects the format from its content, independently of the filename, extension, or AppConfig content type. Both formats use the same snake_case fields and runtime validation.

go run ./cmd/orionis-auth -config ./config/orionis.example.json
# Or:
go run ./cmd/orionis-auth -config ./config/orionis.example.yaml

These equivalent excerpts illustrate the shared field names. The full checked-in examples also define signing keys, clients, and operational limits.

{
  "issuer": "http://localhost:8080",
  "access_token_ttl": "15m"
}

issuer: http://localhost:8080
access_token_ttl: "15m"

YAML must contain exactly one document. Durations use strings such as "15m". In a Docker container, pass a YAML path explicitly if you use one: the default config path remains /app/config/orionis.json.

docker run --rm \
  -p 8080:8080 \
  -v "$PWD/config:/app/config:ro" \
  -v orionis-var:/app/var \
  stremovskyy/orionis:0.6.0 \
  -config /app/config/orionis.example.yaml

See the complete JSON example and YAML example.

3. Deploy on AWS ECS

On Fargate, start Orionis with -config aws. Configuration and private signing keys arrive through separate paths.

03 / Configuration at startup

AWS APPCONFIGRuntime configuration

JSON or YAML: issuer, clients, grants, TTL, limits, and key environment references.

SECRETS MANAGERPrivate signing keys

ECS injects PEM values as environment variables before the process starts.

Load configuration ↓ ↓ Inject keys

ECS task → decode → validate → mount routes → serve

Confucius reads AppConfig once during startup, with a 30-second deadline. Invalid or unavailable configuration prevents startup; there is no background poller or fallback config.

Set the identifiers for an already deployed AppConfig configuration:

AWS_REGION=eu-central-1
AWS_APPCONFIG_APPLICATION=<APPLICATION_ID>
AWS_APPCONFIG_ENVIRONMENT=<ENVIRONMENT_ID>
AWS_APPCONFIG_PROFILE=<CONFIGURATION_PROFILE_ID>

Reference the injected signing key by environment name in the config. This excerpt is part of a complete production configuration:

active_kid: signing-key-2026-10
keys:
  - kid: signing-key-2026-10
    private_key_pem_env: ORIONIS_SIGNING_KEY_PEM

Store client secret digests in secret_sha256_hex arrays. Keep plaintext caller credentials in the callers’ secret stores; keep private-key PEMs in Secrets Manager.

AWS role responsibilities
Role	Required access
Task role	AppConfig StartConfigurationSession and GetLatestConfiguration for the selected configuration.
Task execution role	CloudWatch Logs and GetSecretValue for the signing-key secrets ECS injects.

Use the checked-in ECS templates and deployment guide for AppConfig creation, scoped IAM policies, task-definition rendering, networking, and service setup.

4. Roll out changes

A new AppConfig version takes effect when new Orionis tasks start. Use this order for a configuration rollout:

04 / Apply a configuration change

Deploy the configValidate the candidate and wait for AppConfig deployment state COMPLETE.
Replace the tasksStart new tasks with the pinned image and deployed configuration.
Prove the pathCheck readiness, token issuance, JWKS, and a protected consumer request.

AppConfig deployment prepares the version. Rolling task replacement activates it in Orionis.

For an existing ECS service, retain the current task-definition ARN and configuration version for rollback. After the AppConfig deployment completes, replace tasks using your configured cluster, service, and task definition:

aws ecs update-service \
  --cluster "$ORIONIS_ECS_CLUSTER" \
  --service "$ORIONIS_ECS_SERVICE" \
  --task-definition "$ORIONIS_TASK_DEFINITION" \
  --deployment-configuration 'minimumHealthyPercent=100,maximumPercent=200,deploymentCircuitBreaker={enable=true,rollback=true}' \
  --force-new-deployment

Set ORIONIS_TASK_DEFINITION to the task-definition ARN or revision you intend to deploy. Keep issuer and signing-key references stable when changing configuration delivery. Rollback of an AppConfig change requires restoring the previous configuration and replacing tasks again; an old task definition alone still loads the currently deployed AppConfig version.

5. Verify the result

Check the local server, or replace the base URL with your deployed HTTPS endpoint:

curl -fsS http://localhost:8080/healthz
curl -fsS http://localhost:8080/readyz
curl -fsS http://localhost:8080/.well-known/openid-configuration
curl -fsS http://localhost:8080/.well-known/jwks.json

{"service":"orionis-auth","status":"ok"}

If base_path is configured, include it in every URL and health check. Then follow the token and protected-request walkthrough. For the complete local demo, expect 201 from billing; also confirm that a missing token returns 401 and an insufficient scope returns 403.