@ossy/deployment-tools

@ossy/deployment-tools

Infrastructure and CDK tooling for the Ossy platform EC2 host.

The host runs Caddy as a reverse proxy plus several Docker containers managed by systemd. Apps are deployed by running ossy app publish.

Architecture

Internet → Caddy (:443)
             ├── api.ossy.se          → ossy-api (:3001)
             ├── ossy.se              → ossy-website-ossy (:3002)  ← temporary
             ├── www.plexus-sanitas.com → ossy-website-plexus-sanitas (:3003)  ← temporary
             └── *.* (on-demand TLS)  → ossy-platform (:3000)
                                           └── loads build from CMS on first request

Caddy uses on-demand TLS: before issuing a certificate for any domain, it calls GET http://localhost:3001/api/v0/apps/ask?domain=<domain>. If the domain is registered (i.e. ossy app publish has been run for it), Caddy issues the cert and proxies to the platform runtime.

Services

All services run as Docker containers managed by systemd. Service files are written to the EC2 host by CDK user data at instance creation.

Service	Unit file	Port	Image
Caddy	caddy-route53.service	80, 443	—
Ossy API	ossy-api.service	3001	ghcr.io/ossy-se/api:latest
Ossy Platform	ossy-runtime.service	3000	ghcr.io/ossy-se/platform:latest
configured via services	<name>.service	per config	per config

Additional services are generated automatically from the services array in platforms.json — see the Configuration section below.

Configuration — platforms.json

packages/infrastructure/platforms.json is the single source of truth for a platform. Each entry becomes a CDK Stage with its own set of stacks.

Field	Required	Description
platformName	Yes	Unique name, used as the CDK stage name and CloudFormation stack prefix
awsAccountId	Yes	AWS account ID
awsKeyPairName	Yes	EC2 key pair name for SSH access
awsInstanceClass	No	EC2 instance class (e.g. t3, t4g, m5). Defaults to t3
awsInstanceSize	No	EC2 instance size (e.g. small, medium, large). Defaults to small
sesDomains	No	Domains to configure SES email identity for
domains	No	Domains to create Route53 A records for, pointing to the EC2 Elastic IP. Supports wildcards (e.g. *.ossy.se).
services	No	Per-platform container services (see below)
dnsRecords	No	Additional DNS records by root domain (currently supports MX)
env	No	Environment variables written to /etc/environment on the EC2 host at boot. Never uploaded to S3.

services — container/domain mapping

Services come in two flavours: HTTP (routed through Caddy) and TCP/UDP (raw socket, bypasses Caddy). Both generate a systemd unit that pulls the image on every restart and forwards /etc/environment to the container.

HTTP service (default)

Generates a Caddy reverse-proxy block with Route53 TLS. The container must listen on port 3000.

"services": [
  {
    "name": "ossy-website-ossy",
    "domain": "ossy.se",
    "image": "ghcr.io/ossy-se/website-ossy:latest"
  }
]

Field	Description
name	Unique service name — Docker container name and systemd unit (<name>.service).
domain	Hostname routed by Caddy to this container (Route53 TLS via dns route53).
image	Docker image to pull and run.

Host ports are auto-assigned starting at 3002, counting only HTTP services (TCP entries are skipped). Appending new HTTP entries is safe; avoid reordering existing ones.

TCP/UDP service

No Caddy block. Ports are mapped directly (HOST:CONTAINER) and opened in the EC2 security group. Use this for game servers or any other raw socket protocol.

"services": [
  {
    "name": "minecraft",
    "type": "tcp",
    "image": "itzg/minecraft-server",
    "ports": [25565],
    "protocol": "tcp"
  }
]

Field	Description
name	Unique service name — Docker container name and systemd unit.
type	Must be "tcp" to enable this mode.
image	Docker image to pull and run.
ports	Array of port numbers to expose on the host and open in the security group.
protocol	"tcp" (default), "udp", or "both".

Fixed built-in services (always present, not configurable via services):

• ossy-api — the Ossy API (ghcr.io/ossy-se/api:latest, port 3001)
• ossy-runtime — the platform runtime serving all CMS-published apps (ghcr.io/ossy-se/platform:latest, port 3000, catch-all)

Custom domains: For customer-owned domains (e.g. woodhill.com), the customer adds an A record pointing to the Elastic IP at their registrar. No infrastructure change needed — Caddy's on-demand TLS issues the cert automatically once the domain is registered via ossy app publish.

Wildcard subdomains: Add *.ossy.se to domains for a Route53 wildcard A record. This covers any *.ossy.se subdomain without individual records.

MEDIA_REPOSITORY and MEDIA_CDN_DOMAIN_NAME are derived automatically from the provisioned S3 bucket and CloudFront distribution — do not set them in env.

To add a new platform, add an entry to platforms.json. No bucket name or CDN domain is needed; these are auto-generated by CloudFormation.

CDK Stacks

Each platform is a CDK Stage containing five stacks:

Stack	Description
storage-static	S3 bucket (auto-named), daily backup plan, CloudFront CDN for /media. Kept separate from the EC2 stack so storage resources are never touched during instance updates.
deployment-target	EC2 instance with Elastic IP. Imports the S3 bucket from storage-static via cross-stack reference.
dns	Route53 A records for all domains in platforms.json, pointing to the Elastic IP.
ses	SES email sending identity and DKIM records.

The Elastic IP ensures the EC2 instance can be replaced (instance type changes, user data updates) without breaking DNS or CloudFormation cross-stack exports.

Bootstrapping a new platform

cd packages/deployment-tools
npx cdk deploy 'ossybot/**' --profile ossybot --require-approval never

CDK provisions the instance, writes all service files, writes /etc/environment from platforms.json, and starts all services automatically. No manual SSH steps are required.

Note: EC2 user data only runs on first boot. To apply infrastructure changes to an existing instance you must terminate and recreate it, or SSH in and apply changes manually.

Deploying changes

Target a single platform:

npx cdk deploy 'ossybot/**' --profile ossybot

Target all platforms:

npx cdk deploy '**' --profile ossybot

Preview changes without deploying:

npx cdk diff 'ossybot/**' --profile ossybot

List all stacks:

npx cdk list

Redeploying after a code change

All services pull the latest image from GHCR on every restart — no manual build step needed.

# API — push to main triggers CI → ghcr.io/ossy-se/api:latest
sudo systemctl restart ossy-api

# Platform runtime — merge to main in ossy monorepo → ghcr.io/ossy-se/platform:latest
sudo systemctl restart ossy-runtime

# website-ossy — push to main in website-ossy repo → ghcr.io/ossy-se/website-ossy:latest
sudo systemctl restart ossy-website-ossy

# website-plexus-sanitas — push to main → ghcr.io/ossy-se/website-plexus-sanitas:latest
sudo systemctl restart ossy-website-plexus-sanitas

Environment variables

Defined in the env block of platforms.json, written to /etc/environment at boot. The following variables are injected automatically by CDK and should not be set manually:

Variable	Source
MEDIA_REPOSITORY	S3 bucket name from storage-static stack
MEDIA_CDN_DOMAIN_NAME	CloudFront domain from storage-static stack

All other env vars:

Variable	Used by	Description
DB_URL	API	Atlas MongoDB connection string
DB_NAME	API	MongoDB database name
TOKEN_SECRET	API	JWT signing secret
AWS_ACCESS_KEY_ID	API	AWS credentials for S3
AWS_SECRET_ACCESS_KEY	API	AWS credentials for S3
OSSY_API_KEY	Platform, websites	API JWT for CMS reads
OSSY_COOKIE_SECRET	Websites	Cookie signing secret
OPENAI_API_KEY	Worker	OpenAI API key
OPENAI_ORGANIZATION	Worker	OpenAI organisation ID

Useful commands

SSH into instance

ssh -i path/to/keys ubuntu@<elastic-ip>

View service logs

journalctl -u ossy-runtime.service -n 200 -f
journalctl -u ossy-api.service -n 200 -f
journalctl -u ossy-website-ossy.service -n 200 -f
journalctl -u caddy-route53.service -n 200 -f

View running containers

docker ps

View container logs

docker logs ossy-runtime
docker logs ossy-api
docker logs ossy-website-ossy

Reload Caddy config

sudo systemctl reload caddy-route53.service