Status: Phase 180.C.14.08 reference procedure.
This document defines the first AWS reference deployment notes for Bellona
Remote Gateway. It documents a gateway deployment shape with TLS, storage,
Redis/Postgres placeholders, logs, and smoke tests without claiming the later
production deployment from 180.C.25.09.
Sources Reviewed#
Primary references verified on 2026-04-23:
- AWS Application Load Balancer overview: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html
- AWS Certificate Manager public certificates: https://docs.aws.amazon.com/acm/latest/userguide/acm-public-certificates.html
- AWS Certificate Manager DNS validation: https://docs.aws.amazon.com/acm/latest/userguide/dns-validation.html
- Amazon EC2 security group rules: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-rules.html
- Amazon CloudWatch agent: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html
- Amazon S3 default bucket encryption: https://docs.aws.amazon.com/AmazonS3/latest/userguide/default-bucket-encryption.html
- Amazon RDS for PostgreSQL SSL/TLS: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/PostgreSQL.Concepts.General.SSL.html
- Amazon ElastiCache in-transit encryption: https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/in-transit-encryption.html
Repo-local implementation references:
apps/bellona/remote-gateway/README.mdapps/bellona/remote-gateway/src/config.tsapps/bellona/remote-host/README.mdlibs/bellona/README.mdlibs/bellona/event-handlers/src/storage/postgres.tslibs/bellona/event-handlers/src/storage/cache.tsdocs/domains/bellona/extras/remote-control/hetzner-reference-deployment.mddocs/domains/bellona/extras/remote-control/local-cloud-agent-simulation.md
Current Scope#
This stage documents an AWS reference edge:
- Public Route 53 or external DNS points
bellona-gateway.example.comto an internet-facing Application Load Balancer. - AWS Certificate Manager issues the public certificate, preferably with DNS validation for automated renewal.
- ALB terminates HTTPS/WSS on
443and redirects HTTP80to HTTPS. - ALB forwards
/health,/ready, and/v1/*to a private EC2 gateway target group on port4070. - Bellona Remote Gateway runs as a systemd service on EC2 and listens only on a
private interface or
0.0.0.0protected by security groups. - Remote Host connects outbound over
wss://bellona-gateway.example.com/v1/hosts/connect.
The current gateway runtime still persists to the first-stage JSON store. S3, RDS/Postgres, and Redis are documented as reference AWS dependencies and reserved environment bindings, but the Remote Gateway does not use them until later persistence, artifact, and locking tasks add those code paths.
Baseline Topology#
| Component | AWS Reference Value | Current Status |
|---|---|---|
| DNS | Route 53 alias or external CNAME to ALB | Required for ACM/TLS |
| TLS edge | Public ALB listener with ACM certificate | Reference path for HTTPS/WSS |
| Compute | EC2 Auto Scaling group or one EC2 instance | One instance is enough for MVP notes |
| Gateway port | 4070/tcp, target from ALB security group only |
Current app port |
| Current store | Encrypted EBS volume path for gateway JSON store | Used by current Remote Gateway |
| Artifact storage | Private S3 bucket with default encryption | Placeholder until S3 integration lands |
| Postgres | RDS PostgreSQL in private subnets with TLS | Reserved for later gateway persistence |
| Redis | ElastiCache for Redis OSS or Valkey with TLS | Reserved for later locks/cache/pubsub |
| Logs | journald plus CloudWatch agent file collection | Reference operational log path |
| TURN | Not included in this task | Later AWS production task covers TURN |
Security Groups#
Use security group references rather than public source ranges for private AWS service access.
| Security Group | Inbound Rules | Outbound Rules |
|---|---|---|
bellona-alb |
80/tcp and 443/tcp from 0.0.0.0/0 and ::/0 |
4070/tcp to bellona-gateway |
bellona-gw |
4070/tcp from bellona-alb; SSH only if needed |
HTTPS egress, RDS SG, Redis SG, S3 VPC |
bellona-rds |
5432/tcp from bellona-gw |
Default managed service behavior |
bellona-redis |
6379/tcp from bellona-gw |
Default managed service behavior |
Prefer AWS Systems Manager Session Manager over public SSH. If SSH is required
for the MVP, restrict 22/tcp to named operator CIDRs and remove it after
commissioning.
Do not allow public inbound access to:
- gateway port
4070 - Remote Host health ports
- Blender localhost ports
- Chrome/CDP ports
- desktop helper ports
- Redis or Postgres
- MCP stdio or any future MCP HTTP listener before auth/session binding is enforced
TLS And ALB#
Request an ACM public certificate for bellona-gateway.example.com in the same
region as the ALB. DNS validation is preferred because ACM can renew the
certificate automatically while the validation records remain present.
Reference listener shape:
| Listener | Action |
|---|---|
80 |
Redirect to https://#{host}:443/#{path} |
443 |
Forward to target group bellona-gateway |
Reference target group:
| Setting | Value |
|---|---|
| Protocol | HTTP |
| Port | 4070 |
| Target type | Instance or IP |
| Health path | /health |
| Success codes | 200 |
| Idle timeout | At least 120 seconds on ALB |
The host WebSocket route is /v1/hosts/connect; keep the ALB idle timeout
longer than the gateway heartbeat interval and below the host heartbeat timeout.
The current defaults are 30000 ms interval and 90000 ms timeout.
EC2 Gateway Runtime#
The reference EC2 layout mirrors the Hetzner runbook but uses ALB security groups instead of a local reverse proxy.
sudo apt-get update
sudo apt-get install -y git jq curl
sudo mkdir -p /opt/oshun /var/lib/bellona/remote-gateway /var/log/bellona
sudo useradd --system --home /var/lib/bellona --shell /usr/sbin/nologin bellona
sudo chown -R bellona:bellona /var/lib/bellona /var/log/bellona
Install and configure amazon-cloudwatch-agent with the AWS package flow for
the selected AMI. Do not rely on a distro package name without confirming it is
available for that image.
Deploy the repo:
cd /opt/oshun/current
pnpm install --frozen-lockfile
pnpm nx build @bellona/remote-gateway --skip-nx-cache --verbose
sudo chown -R bellona:bellona /opt/oshun/current /var/lib/bellona /var/log/bellona
Gateway Environment#
Create /etc/bellona/remote-gateway.env with root-only write access.
NODE_ENV=production
BELLONA_REMOTE_GATEWAY_HOST=0.0.0.0
BELLONA_REMOTE_GATEWAY_PORT=4070
BELLONA_REMOTE_GATEWAY_LOG_LEVEL=info
BELLONA_REMOTE_GATEWAY_STORE_FILE=/var/lib/bellona/remote-gateway/store.json
BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET=replace-with-32-plus-byte-secret
BELLONA_REMOTE_GATEWAY_HOST_TOKEN_TTL_MS=7776000000
BELLONA_REMOTE_GATEWAY_PAIRING_CODE_TTL_MS=600000
BELLONA_REMOTE_GATEWAY_APPROVAL_REQUEST_TTL_MS=60000
BELLONA_REMOTE_GATEWAY_HOST_HEARTBEAT_INTERVAL_MS=30000
BELLONA_REMOTE_GATEWAY_HOST_HEARTBEAT_TIMEOUT_MS=90000
BELLONA_REMOTE_GATEWAY_SHUTDOWN_GRACE_MS=5000
# Reserved for later Bellona AWS data-plane tasks. Current Remote Gateway does
# not read these values yet.
AWS_REGION=us-east-1
BELLONA_AWS_ARTIFACT_BUCKET=oshun-bellona-remote-artifacts-prod
BELLONA_AWS_ARTIFACT_KMS_KEY_ARN=arn:aws:kms:us-east-1:123456789012:key/example
BELLONA_DATABASE_URL=postgresql://bellona:REDACTED@bellona-postgres.example:5432/bellona?sslmode=require
REDIS_URL=rediss://bellona-redis.example.cache.amazonaws.com:6379
Required production changes from local defaults:
BELLONA_REMOTE_GATEWAY_HOST=0.0.0.0is acceptable only when EC2 security groups restrict4070to the ALB security group.BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRETmust be unique, high entropy, at least 32 bytes, and stored outside the repo.BELLONA_REMOTE_GATEWAY_STORE_FILEmust be on encrypted persistent EBS until RDS-backed gateway persistence exists.BELLONA_DATABASE_URLandREDIS_URLare reserved for later code paths; do not mark RDS/Redis integration live from this runbook alone.
systemd Unit#
Create /etc/systemd/system/bellona-remote-gateway.service:
[Unit]
Description=Bellona Remote Gateway
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=bellona
Group=bellona
WorkingDirectory=/opt/oshun/current
EnvironmentFile=/etc/bellona/remote-gateway.env
ExecStart=/usr/bin/env pnpm nx start @bellona/remote-gateway
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
ReadWritePaths=/var/lib/bellona /var/log/bellona /opt/oshun/current
StandardOutput=append:/var/log/bellona/remote-gateway.log
StandardError=append:/var/log/bellona/remote-gateway.err.log
[Install]
WantedBy=multi-user.target
Enable and start:
sudo systemctl daemon-reload
sudo systemctl enable --now bellona-remote-gateway
sudo systemctl status bellona-remote-gateway --no-pager
Storage Notes#
Current storage:
- Use encrypted EBS for
/var/lib/bellona/remote-gateway/store.json. - Back up the JSON store before destructive maintenance.
- Do not mount the store on ephemeral instance storage.
S3 artifact placeholder:
- Create a private bucket such as
oshun-bellona-remote-artifacts-prod. - Keep S3 Block Public Access enabled.
- Use default encryption. SSE-S3 is automatic for new objects, but SSE-KMS is preferred when Bellona needs explicit key policy, rotation, and audit control.
- Use bucket lifecycle rules for screenshots, logs, browser traces, exports, and
diagnostic bundles after
180.C.22.05adds object-storage integration.
Postgres placeholder:
- Provision RDS PostgreSQL in private subnets.
- Require SSL/TLS in the connection string with
sslmode=requireor stricter client verification when supported by the consuming package. - Restrict
5432/tcpto the gateway security group. - Existing Bellona event-handler storage uses
BELLONA_DATABASE_URLorDATABASE_URL; the Remote Gateway does not yet use Postgres.
Redis placeholder:
- Use ElastiCache for Redis OSS or Valkey in private subnets.
- Enable in-transit encryption and use
rediss://client URLs for future gateway code paths. - Restrict
6379/tcpto the gateway security group. - Existing Bellona cache/event components use
REDIS_URL; the Remote Gateway does not yet use Redis.
Logs#
Local service logs:
journalctl -u bellona-remote-gateway -f
tail -f /var/log/bellona/remote-gateway.log
tail -f /var/log/bellona/remote-gateway.err.log
CloudWatch agent should collect at least:
/var/log/bellona/remote-gateway.log/var/log/bellona/remote-gateway.err.log- ALB access logs, if enabled to S3
Example CloudWatch agent log collection fragment:
{
"logs": {
"logs_collected": {
"files": {
"collect_list": [
{
"file_path": "/var/log/bellona/remote-gateway.log",
"log_group_name": "/bellona/remote-gateway/app",
"log_stream_name": "{instance_id}"
},
{
"file_path": "/var/log/bellona/remote-gateway.err.log",
"log_group_name": "/bellona/remote-gateway/error",
"log_stream_name": "{instance_id}"
}
]
}
}
}
}
Expected gateway event names for MVP triage:
remote gateway listeningremote host handshake acceptedremote gateway command receivedremote gateway command dispatchedremote gateway command result received
Operational logs do not replace audit. Audit and timeline evidence remain gateway-owned and must be exported through Bellona evidence paths as those features mature.
Smoke Test#
Run after DNS, ACM validation, ALB listener rules, target group health, EC2 service startup, and security groups are in place:
COMMIT_SHA="$(git -C /opt/oshun/current rev-parse HEAD)"
echo "Bellona AWS smoke commit: ${COMMIT_SHA}"
curl -fsS https://bellona-gateway.example.com/health | jq .
curl -fsS https://bellona-gateway.example.com/ready | jq .
aws elbv2 describe-target-health \
--target-group-arn "$BELLONA_AWS_TARGET_GROUP_ARN" \
--query 'TargetHealthDescriptions[].TargetHealth'
sudo journalctl -u bellona-remote-gateway --since "5 minutes ago" --no-pager
sudo tail -n 100 /var/log/bellona/remote-gateway.log
Expected results:
- ALB target health is
healthy. /healthreturnsstatus: "healthy"over public HTTPS./readyreturnsstatus: "ready"withchecks.config,checks.deviceRegistry, andchecks.shuttingDown.- Gateway logs show
remote gateway listening. - No security group exposes
4070to the public internet.
Optional AWS dependency smoke, only when placeholders are provisioned:
aws rds describe-db-instances --db-instance-identifier bellona-postgres
aws elasticache describe-serverless-caches --serverless-cache-name bellona-redis
aws s3api get-bucket-encryption --bucket oshun-bellona-remote-artifacts-prod
aws logs describe-log-groups --log-group-name-prefix /bellona/remote-gateway
From the Remote Host MacBook, configure:
BELLONA_REMOTE_HOST_GATEWAY_URL=wss://bellona-gateway.example.com/v1/hosts/connect
BELLONA_REMOTE_HOST_PAIRING_EXCHANGE_URL=https://bellona-gateway.example.com/v1/pairing/exchange
The full cloud-agent MVP smoke remains 180.C.14.09; this task's smoke proves
the AWS gateway edge, TLS, readiness, logging, security-group boundary, and
reserved data-plane dependencies.
Evidence To Record#
For each AWS reference deployment trial, record:
- AWS account alias/id, region, VPC id, subnet ids, and deployment commit SHA.
- ACM certificate ARN and validation method, without private keys.
- ALB ARN, listener rules, target group ARN, and target health result.
- Security group rules proving
4070, Redis, and Postgres are not public. - EC2 instance id, AMI, instance type, and EBS encryption status.
- Gateway service status and recent startup logs.
- CloudWatch log group names and the most recent gateway log event timestamp.
/healthand/readyJSON outputs over public HTTPS.- S3 bucket encryption status if the placeholder bucket exists.
- RDS and Redis endpoint names if placeholders exist, without credentials.
- Any failed smoke command and exact remediation used.
Limitations#
- This is not the production-ready AWS deployment from
180.C.25.09. - The current Remote Gateway still uses the first-stage JSON store on EBS, not RDS/Postgres.
- The current Remote Gateway does not read
REDIS_URLor S3 artifact bucket settings. - The current MCP package exposes stdio locally; remote/cloud MCP HTTP transport remains a later implementation task.
- No live Blender, browser, desktop, remote MacBook, or cloud-agent MVP command
flow is certified until
180.C.14.09runs the deployed gateway smoke path.