/deploying-containers-to-amazon-lightsail

name: deploying-containers-to-amazon-lightsail
description: >
  Deploys, hosts, or runs a container or Docker app on Amazon Lightsail Container Service and returns a live,
  managed HTTPS URL at a flat monthly price — no cluster, VPC, load balancer, or registry to set up. Used when
  deploying a container image to Lightsail from a local Docker build, a public registry image, or a GitHub repo,
  or when a Lightsail container deployment fails or won't serve — including when the request doesn't name
  Lightsail but asks to run one always-on container behind a public URL at a flat, predictable monthly price.
  Not for running an app on a Lightsail instance (VM) or Amazon EC2 instead of the container service, and not
  for workloads needing Kubernetes, autoscaling, scale-to-zero, or per-request pricing (use Amazon ECS/EKS or
  ECS Express Mode).
version: 1

Deploying containers to Amazon Lightsail

Overview

Amazon Lightsail Container Service runs a container image behind a managed, HTTPS URL for a flat monthly price. The URL, TLS certificate, and load balancing are included — there is no cluster, VPC, load balancer, or registry to set up.

This skill takes a container image from any source to a live, serving Lightsail deployment, and diagnoses one that won't serve. Creating the service requires two choices: **`power`**, the memory and vCPUs of each node, and **`scale`**, how many nodes run, each running a full copy of the deployment. Capacity never changes on its own — there is no autoscaling and no scale-to-zero — so you raise `power` or `scale` yourself when a service needs more.

Prerequisites

Before creating anything:

• **Clarify** the image source, the port the app listens on, and the region.
• **Discover options at runtime** — the available powers and regions — instead of hardcoding them.
• **Confirm the plan and price.** State the flat monthly price (power × scale, charged even with no traffic) and confirm

before creating billable resources — unless the user has already told you to proceed. Never create them silently. See the Pricing section below for where to read the figures.

• **Fixed caps aren't adjustable.** The nodes-per-service cap is the ceiling on `scale`; containers per deployment and

deployment versions are capped too. Read the values in [Lightsail quotas](https://docs.aws.amazon.com/general/latest/gr/lightsail.html) rather than offering an increase. An account's actual quota may be lower than the published default if the account was recently created or is used minimally.

• **Permissions.** The calling identity needs the Lightsail actions in the Operations table below; a missing one

surfaces as an access-denied error on the first call, not as a tooling or quota problem. See the Security considerations section below for scoping them.

Tools: the **AWS CLI** (v2) is all a public-registry-image deploy needs — and its operations run either through the AWS MCP tools (preferred, see below) or the CLI directly. A local build or push also needs `docker` (running) and — for the `push-container-image` shortcut — the `lightsailctl` plugin (the plugin-free push uses `docker` + `register-container-image` instead).

Running AWS operations: prefer the AWS MCP execution tool **`aws___run_script`** when it is available, and keep each call **short** — one operation that returns right away, not a long-running one (a call still running after ~30 seconds is cut off and drops the session). It isn't required: the same operations run through the local **`aws` CLI**, which is the fallback when no MCP tool is available. Note the build and push of a **local** image are Docker/`lightsailctl` operations that run on your machine, never through the MCP tools.

Installing `lightsailctl`: needed only for the `push-container-image` shortcut, and it needs AWS CLI v2 plus a running Docker:

• **macOS:** `brew install aws/tap/lightsailctl`
• **Linux:** `curl "https://s3.us-west-2.amazonaws.com/lightsailctl/latest/linux-amd64/lightsailctl" -o /usr/local/bin/lightsailctl && chmod +x /usr/local/bin/lightsailctl`
• **Windows:** download `https://s3.us-west-2.amazonaws.com/lightsailctl/latest/windows-amd64/lightsailctl.exe` and add it to `PATH`.

If an install is blocked or the plugin still isn't found, see the troubleshooting reference — or skip the plugin entirely with the plugin-free push in [references/local-image.md](references/local-image.md).

References

The step-by-step detail lives in reference files bundled with this skill. **You MUST read the reference matching your image source, or the step you're about to do, before doing it** — each carries the exact sequence and requirements (ports, image architecture, push method) that are easy to get wrong.

To open one: on the AWS MCP server, retrieve it with the skill's content-retrieval tool; otherwise read it from this skill's own directory (its location was shown to you when the skill loaded), e.g. `<skill-dir>/references/NAME.md`. **DON'T read from a bare `references/NAME.md`** — it resolves against your working directory, not the skill, and fails with "No files found"; if you hit that, prepend the skill directory and retry.

• [references/public-image.md](references/public-image.md) — a public registry image (no build, no push).
• [references/local-image.md](references/local-image.md) — build a local image and push it into the service's

registry (`docker`; `push-container-image` or the plugin-free sequence).

• [references/github-source.md](references/github-source.md) — clone and build from a GitHub repo, then follow the

local-image path.

• [references/deployment.md](references/deployment.md) — the deployment shape (`containers` + `publicEndpoint` + health

check), how to poll to `ACTIVE`, roll back, and tear down.

• [references/troubleshooting.md](references/troubleshooting.md) — `lightsailctl` not found, a `FAILED` deployment,

502/503, and `exec format error` (a CPU-architecture mismatch).

Service, deploymen