Spectrum on AWS

01What's live, right now

One paragraph, then the receipts.

Spectrum's cockpit, orders tab, strategy tab, architecture tab, and this deployment guide are all served over HTTPS at https://spectrummomentum.com, from one small EC2 instance in us-east-1, behind Caddy for automatic TLS. The app, its systemd timers (weekly momentum rebuild, twice-daily cockpit refresh, nightly backup), and its history database all run on that one box. Nothing here places real orders; nothing here is investment advice.

02Infrastructure diagram

03Resource inventory

Every real identifier, so future-you never has to hunt for it in the console.

04Security model

• No SSH port anywhere. The security group has only 80 and 443. All shell access is via SSM Session Manager, which authenticates through IAM, not a key you can lose or leak.
• Secrets never touch disk in plaintext for long. Polygon and Adanos keys live in SSM Parameter Store as SecureStrings (KMS-encrypted); the instance decrypts them at boot into /opt/spectrum/.env, mode 600, owned by the unprivileged spectrum user.
• Least-privilege instance role. The EC2 role can only: read objects under s3://spectrum-deploy-814203451977/releases/*, read/write under backups/*, read the two /spectrum/* parameters, and use SSM Session Manager. It cannot list the bucket, touch other AWS services, or read other parameters.
• The app runs as a non-root system user (spectrum), not root, with Restart=on-failure so a crash doesn't take the site down for good.
• Public exposure is minimal by design. Only 80/443 face the internet; port 80 exists solely for Let's Encrypt's ACME challenge and to redirect to HTTPS.

05Cost — real numbers

Biggest lever if this needs to be cheaper: stop the instance when not in use (EBS still bills, EC2 compute doesn't — but the site goes down while stopped, so this only suits a dev/demo pattern, not a daily-use cockpit), or move to a t3.micro / t4g.small; the app's own footprint is tiny (a few hundred MB RAM), t3.small has ample headroom to spare.

06Incidents hit during this deploy, and the fixes

Recorded honestly — this is exactly what to check first if a future redeploy breaks the same way.

07Runbook: access the server

No SSH key exists for this instance on purpose. Get a shell with:

export PATH="$HOME/Library/Python/3.9/bin:$PATH"   # this session's aws CLI location
aws ssm start-session --target i-0bc7afe752c9ef8b5 --profile spectrum --region us-east-1

For a single command without a full session (what this deployment used throughout):

aws ssm send-command --instance-ids i-0bc7afe752c9ef8b5 \
  --document-name "AWS-RunShellScript" \
  --parameters 'commands=["systemctl status spectrum.service --no-pager"]' \
  --profile spectrum --region us-east-1 --query 'Command.CommandId' --output text
# then, with the returned id:
aws ssm get-command-invocation --command-id <ID> --instance-id i-0bc7afe752c9ef8b5 \
  --profile spectrum --region us-east-1 --query '[Status,StandardOutputContent,StandardErrorContent]' --output text

Useful checks once connected

systemctl status spectrum.service --no-pager        # is the app up?
journalctl -u spectrum.service -n 50 --no-pager      # app logs
systemctl status snap.caddy.server.service           # is Caddy up?
journalctl -u caddy-config.service -n 20 --no-pager   # did the Caddyfile load?
systemctl list-timers --no-pager | grep spectrum      # when do the jobs next run?

08Runbook: redeploy new code

Whenever the Spectrum codebase changes on this Mac, ship it with:

# 1. package (from the repo root, excludes .venv and the local bar cache)
tar czf /tmp/spectrum-app.tar.gz --exclude='.venv' --exclude='data/bars' \
  --exclude='*.pyc' --exclude='__pycache__' --exclude='.env' spectrum pyproject.toml

# 2. upload
aws s3 cp /tmp/spectrum-app.tar.gz s3://spectrum-deploy-814203451977/releases/spectrum-app.tar.gz \
  --profile spectrum --region us-east-1

# 3. pull + reinstall on the instance
aws ssm send-command --instance-ids i-0bc7afe752c9ef8b5 --document-name "AWS-RunShellScript" \
  --parameters 'commands=[
    "aws s3 cp s3://spectrum-deploy-814203451977/releases/spectrum-app.tar.gz /tmp/a.tar.gz --region us-east-1",
    "tar xzf /tmp/a.tar.gz -C /opt/spectrum",
    "chown -R spectrum:spectrum /opt/spectrum",
    "sudo -u spectrum /opt/spectrum/.venv/bin/pip install --quiet -e /opt/spectrum",
    "systemctl restart spectrum.service"
  ]' --profile spectrum --region us-east-1

If a web page (HTML/CSS/JS) changed but no Python did, the same steps still apply — the tarball includes spectrum/web/. FastAPI serves those files fresh on every request, so once the tarball lands there's no extra caching step to bust.

09Runbook: rotate secrets

Get a new key from Polygon.io or Adanos, then, without ever pasting it into a command that gets logged with tracing on:

aws ssm put-parameter --name /spectrum/POLYGON_API_KEY --value "NEW_KEY_HERE" \
  --type SecureString --overwrite --profile spectrum --region us-east-1

aws ssm send-command --instance-ids i-0bc7afe752c9ef8b5 --document-name "AWS-RunShellScript" \
  --parameters 'commands=[
    "P=$(aws ssm get-parameter --name /spectrum/POLYGON_API_KEY --with-decryption --region us-east-1 --query Parameter.Value --output text)",
    "A=$(aws ssm get-parameter --name /spectrum/ADANOS_API_KEY --with-decryption --region us-east-1 --query Parameter.Value --output text)",
    "printf \"POLYGON_API_KEY=%s\\nADANOS_API_KEY=%s\\n\" \"$P\" \"$A\" > /opt/spectrum/.env",
    "chown spectrum:spectrum /opt/spectrum/.env && chmod 600 /opt/spectrum/.env",
    "systemctl restart spectrum.service"
  ]' --profile spectrum --region us-east-1

Note this command block intentionally avoids set -x and never echoes the variables — the lesson from Incident 1.

10Runbook: backup & disaster recovery

spectrum-backup.timer runs nightly at 05:00 UTC and copies spectrum.db, momentum.json and ops.json to s3://spectrum-deploy-814203451977/backups/. The bucket has versioning enabled, so every night's backup is a separate recoverable version even though the object key never changes.

To restore onto a fresh instance

aws s3 cp s3://spectrum-deploy-814203451977/backups/spectrum.db /opt/spectrum/data/spectrum.db
aws s3 cp s3://spectrum-deploy-814203451977/backups/momentum.json /opt/spectrum/data/momentum.json
aws s3 cp s3://spectrum-deploy-814203451977/backups/ops.json /opt/spectrum/data/ops.json
chown spectrum:spectrum /opt/spectrum/data/*
systemctl restart spectrum.service

To recover an older version (versioned bucket)

aws s3api list-object-versions --bucket spectrum-deploy-814203451977 --prefix backups/spectrum.db \
  --profile spectrum --region us-east-1
# then restore a specific VersionId with:
aws s3api get-object --bucket spectrum-deploy-814203451977 --key backups/spectrum.db \
  --version-id <VERSION_ID> /tmp/spectrum-old.db --profile spectrum --region us-east-1

The 10-year price-bar cache (data/bars/*.parquet) is not backed up — it's disposable and rebuilds automatically from Polygon on the next spectrum momentum run if ever lost, at the cost of one API pass over ~133 symbols.

11Domain & DNS reference

If the Elastic IP ever changes

(It won't unless the EIP is explicitly released — but if it ever does:)

aws route53 change-resource-record-sets --hosted-zone-id Z05618432FZYFBPA2TK4Y \
  --change-batch '{"Changes":[
    {"Action":"UPSERT","ResourceRecordSet":{"Name":"spectrummomentum.com","Type":"A","TTL":300,
      "ResourceRecords":[{"Value":"NEW.IP.HERE"}]}},
    {"Action":"UPSERT","ResourceRecordSet":{"Name":"www.spectrummomentum.com","Type":"A","TTL":300,
      "ResourceRecords":[{"Value":"NEW.IP.HERE"}]}}]}' \
  --profile spectrum --region us-east-1

12What's NOT done yet

• No login. The site is public to anyone with the URL — there's no password or Google login in front of it yet (see the earlier conversation on adding one; still a contained, hour-or-two change whenever you want it).
• IAM user is broader than it needs to be — spectrum-deploy has AdministratorAccess (§4). Fine for now, worth scoping down later.
• No monitoring/alerting — if the instance or the app crashes outside Restart=on-failure's reach (e.g. the instance itself stops), nothing pages you. A cheap next step: a CloudWatch alarm on instance status checks, or an uptime-checker hitting /api/momentum every few minutes.
• Single instance, single region. No failover. Acceptable for a personal research cockpit; would not be for anything with real money automatically moving.
• Deploys are manual (§8's runbook) — no CI/CD. Reasonable at this scale; revisit if deploys become frequent enough to be annoying.