AWS Lightsail Provider

Deploy preview environments to AWS Lightsail instances via SSH.

How it works

• Build: Provisions a Lightsail instance (or reuses the existing one for the PR), waits for it to be fully ready, clones the repo, and runs docker build. Docker and git are pre-installed via a startup script — no manual setup required.
• Deploy: Runs the built Docker image on the same instance. Each PR gets its own dedicated Lightsail instance.
• Delete: Terminates the Lightsail instance and releases all associated resources.
• List: Lists all Lightsail instances tagged previewops: true for the repo.

Prerequisites

1. An AWS account.
2. An IAM user or role with Lightsail permissions.
3. An SSH key pair for instance access.

Step 1 — Create IAM credentials

Create an IAM user (or use an existing role) with the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lightsail:CreateInstances",
        "lightsail:DeleteInstance",
        "lightsail:GetBundles",
        "lightsail:GetInstance",
        "lightsail:GetInstances",
        "lightsail:TagResource"
      ],
      "Resource": "*"
    }
  ]
}

1. Go to the AWS IAM console → Users → Create user.
2. Give the user a name (e.g. previewops-lightsail) and click through to Set permissions.
3. Choose Attach policies directly → Create inline policy → switch to the JSON tab, paste the policy above → Next → save.
4. Open the newly created user → Security credentials tab → Create access key.
5. Select Application running outside AWS and click through to the confirmation screen.
6. Copy both values now — AWS only shows the secret access key once.

Step 2 — Create a dedicated SSH key pair

Generate a new key pair for Previewops:

ssh-keygen -t ed25519 -C "previewops-lightsail" -f ~/.ssh/previewops-lightsail

Register the public key with your Lightsail account:

1. Go to the Lightsail console → Account (top-right) → SSH keys.
2. Under Custom keys, click Upload key.
3. Click Choose File. The .ssh folder is hidden — use the shortcut for your OS to navigate to it:
   • macOS: Press Cmd+Shift+G → type ~/.ssh → press Enter
   • Linux: Press Ctrl+L → type ~/.ssh → press Enter
   • Windows: Type %USERPROFILE%\.ssh in the address bar → press Enter
4. Select previewops-lightsail.pub, then click Upload key.
5. Note the name you give the key pair — you will need it in Step 3.

Store the private key content as AWS_SSH_PRIVATE_KEY in Previewops credentials:

cat ~/.ssh/previewops-lightsail   # copy the full output including -----BEGIN/END----- lines

Step 3 — Configure the repo

keyPairName is required. All other providerConfig fields are optional:

provider: aws-lightsail
providerConfig:
  keyPairName: previewops         # required — name of the key pair registered in Step 2
  region: us-east-1               # optional (default: us-east-1)
  bundleId: micro_2_0             # optional (default: micro_2_0) — instance size
                                  # run: aws lightsail get-bundles --query 'bundles[].bundleId'
  blueprintId: ubuntu_22_04       # optional (default: ubuntu_22_04) — OS image
                                  # run: aws lightsail get-blueprints --query 'blueprints[].blueprintId'

Complete example with all options:

# .previewops.yaml
provider: aws-lightsail
providerConfig:
  keyPairName: previewops         # name of the Lightsail key pair registered in your account
  region: us-east-1               # AWS region (default: us-east-1)
  bundleId: micro_2_0             # instance size — micro_2_0 ($7/mo, default), small_2_0 ($12/mo), medium_2_0 ($20/mo)
  blueprintId: ubuntu_22_04       # OS image (default: ubuntu_22_04)

# Common options — all optional
concurrency: 3               # max simultaneous active previews per repo
ttlHours: 24                 # auto-delete after N hours (default: 24)
port: 3000                   # optional — auto-detected from your Dockerfile EXPOSE; falls back to 8080
memory: 512Mi                # container memory passed to docker run (default: 512Mi)
cpu: 1                       # CPU shares passed to docker run (default: 1)
dockerfile: Dockerfile       # Dockerfile path relative to repo root (default: Dockerfile)
buildContext: .              # Docker build context (default: .)
env:
  NODE_ENV: preview          # inject env vars into the preview container

Step 4 — Verify

Comment /validate-previewops --provider=aws-lightsail on any open PR. The bot replies with a status dashboard showing:

• BYOC Credentials — aws-lightsail with the date it was last updated.
• .previewops.yaml — the provider field and any providerConfig keys you have set.

Example output:

🔍 Credentials & configuration status

BYOC Credentials

Provider	Last Updated
aws-lightsail	2025-01-15

.previewops.yaml

Field	Value
provider	aws-lightsail
providerConfig keys	keyPairName, region

Instance sizing

Choose a bundle that has enough RAM for your Docker build. Previewops requires at least 1 GB RAM — the nano_2_0 and nano_3_0 bundles (512 MB) are too small and will be rejected before the instance is created.

Run aws lightsail get-bundles --query 'bundles[].bundleId' to list all available bundle IDs in your region.

Notes

• Instances are provisioned on-demand for each PR and terminated on delete/close.
• First deploy takes ~3 minutes (instance boot + readiness checks).
• Subsequent deploys to the same PR reuse the existing instance (~30 s).
• The preview URL is http://prev-{org5}-{repo}-pr{N}-aws-lightsail.{ip}.nip.io — a human-readable nip.io hostname that resolves to the instance's public IP ({org5} = first 5 characters of the org name, slugified). No DNS configuration required.

Troubleshooting