Deploy on AWS Lightsail

Run Gatehouse on one Amazon Lightsail server with HTTPS, daily snapshots and encrypted off-site backups.

This guide puts Gatehouse on a single Amazon Lightsail instance with:

• HTTPS from Let's Encrypt, renewed automatically by Caddy
• Gatehouse reachable only through Caddy (port 8787 is never exposed)
• a firewall with only 80, 443 open, and SSH from your IP only
• daily instance snapshots (Lightsail keeps 7)
• encrypted database backups every 24 hours, kept 30 days on the server and in a private Lightsail bucket
• automatic OS security updates

Everything lives in deploy/lightsail/. It works the same on any Linux VM with Docker.

#What it costs

#1. Create the resources

On your laptop, with the AWS CLI signed in:

REGION=us-east-1 DOMAIN=usegatehouse.com ./deploy/lightsail/provision.sh

It creates the instance (Docker is installed on first boot), a static IP, the firewall rules, automatic snapshots, a private backup bucket with its own access key, and, if you want, a Lightsail DNS zone for your domain. At the end it prints the backup settings to copy into .env. The bucket secret is shown once.

If your DNS is elsewhere (Route 53, Cloudflare, your registrar), create two A records pointing at the static IP: usegatehouse.com and www.usegatehouse.com.

#2. Copy the code

aws lightsail --region us-east-1 download-default-key-pair --query privateKeyBase64 --output text > ~/.ssh/lightsail-us-east-1.pem
chmod 600 ~/.ssh/lightsail-us-east-1.pem
./deploy/lightsail/push.sh ubuntu@<static-ip>

push.sh copies only files tracked in git: no .env, keys or databases. Once releases are published from GitHub, set GATEHOUSE_IMAGE in .env and the server pulls signed images instead of building.

#3. Start Gatehouse

ssh -i ~/.ssh/lightsail-us-east-1.pem ubuntu@<static-ip>
cd gatehouse/deploy/lightsail
./setup.sh

On first run setup.sh:

1. creates the master key in master.key (readable only by the app),
2. asks for your domain and creates .env,
3. builds and starts Caddy, Gatehouse and the backup service,
4. prints the one-time setup code.

Copy master.key somewhere safe that isn't the server, such as your password manager. Backups and stored credentials can't be decrypted without it.

Then add the backup, email and Slack settings to .env and run ./setup.sh again. Open https://usegatehouse.com/setup, enter the setup code and create the owner account.

#Updating

cd gatehouse/deploy/lightsail
./update.sh          # takes a backup, rebuilds and restarts
./update.sh 0.3.0    # or switch to a published image version

Copy the new code with push.sh first when building on the server.

#Checking on it

• docker compose ps shows the three services and their health.
• docker compose logs -f gatehouse follows the app; docker compose logs backup shows each backup.
• Settings → General → Data protection shows when the last backup ran, and whether it reached the bucket.
• Add an uptime check on https://usegatehouse.com/healthz (Lightsail metric alarms, UptimeRobot or Better Stack) so you hear about outages first.

#Email

For invites and password resets, verify your domain in Amazon SES, create SMTP credentials, and set SMTP_HOST, SMTP_PORT=587, SMTP_USER, SMTP_PASSWORD and SMTP_FROM in .env. New SES accounts start in a sandbox; request production access before inviting people outside your team.

See Backups and restore for restoring, and Self-hosting for Kubernetes and other options.