home / skills / shipshitdev / library / ec2-backend-deployer

ec2-backend-deployer skill

/bundles/infrastructure/skills/ec2-backend-deployer

This skill helps you deploy backend applications to EC2 using Docker, CI/CD, and GitHub Actions with secure, automated workflows.

npx playbooks add skill shipshitdev/library --skill ec2-backend-deployer

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.5 KB

---
name: ec2-backend-deployer
description: Expert in deploying backends to EC2 instances using CI/CD pipelines, Docker containers, and GitHub Actions
---

# EC2 Backend Deployer

Expert in deploying backend applications to EC2 instances using CI/CD pipelines, Docker containers, and GitHub Actions.

## When to Use This Skill

Use when you're:

- Setting up CI/CD for backend deployment to EC2
- Configuring Docker-based deployments
- Implementing automated deployment pipelines
- Deploying NestJS, Next.js, or Express backends
- Setting up container registries and image management
- Configuring secure EC2 access (Tailscale)

## Quick Workflow

1. **Dockerfile**: Multi-stage build (base → builder → production)
2. **Registry**: GitHub Container Registry (ghcr.io) recommended
3. **CI/CD**: GitHub Actions with Tailscale for secure SSH
4. **Deploy**: Docker Compose on EC2 with health checks
5. **Verify**: Health endpoint + deployment verification

## Key Components

### Docker

- Multi-stage builds for smaller images
- Non-root user for security
- HEALTHCHECK for container orchestration
- BuildKit secrets for sensitive data

### GitHub Actions

- `docker/build-push-action` for image building
- `tailscale/github-action` for secure access
- `appleboy/ssh-action` for deployment

### EC2

- Docker Compose v2 required
- Health check verification
- Rollback procedures

## References

- [Full guide: Dockerfile, CI/CD workflow, deployment, troubleshooting](references/full-guide.md)

Overview

This skill deploys backend applications to AWS EC2 instances using Docker, GitHub Actions CI/CD, and secure remote access. It packages apps with multi-stage Dockerfiles, pushes images to a container registry, and orchestrates releases on EC2 with Docker Compose. The focus is repeatable, secure deployments with health checks and rollback support.

How this skill works

The pipeline builds a slim production image using a multi-stage Dockerfile, then pushes the image to a registry such as GitHub Container Registry (ghcr.io). GitHub Actions runs the build and uses Tailscale for secure connectivity to the target EC2 host. A deployment job uses SSH (appleboy/ssh-action) to pull the image and run Docker Compose on the EC2 instance, then verifies a health endpoint and performs rollbacks if checks fail.

When to use it

You need a reproducible CI/CD flow for backend services (NestJS, Next.js API, Express).
You want to deploy containerized apps to single EC2 hosts using Docker Compose.
You require secure remote access to EC2 without exposing SSH publicly (use Tailscale).
You need image management and a private registry (ghcr.io) integrated with CI.
You want automated health checks and rollback on failed deployments.

Best practices

Use multi-stage Dockerfiles and a non-root runtime user to minimize image size and security surface.
Store sensitive build secrets in BuildKit or GitHub Actions secrets; avoid embedding credentials in images.
Run health checks inside Docker and verify the health endpoint from CI before marking deployment successful.
Use Tailscale or VPN for secure CI-to-EC2 connectivity instead of opening SSH to the internet.
Keep Docker Compose v2 on EC2 and define clear start/stop/rollback commands for deployment scripts.

Example use cases

Deploying an Express API to a single EC2 instance with automated nightly builds and zero-downtime restarts.
CI pipeline for a NestJS backend that builds, pushes to ghcr.io, and updates EC2 Compose stacks using Tailscale.
Rolling back a failed Next.js API deployment automatically when post-deploy health checks fail.
Using GitHub Actions to build container images with BuildKit secrets and push to a private registry.

FAQ

Do I need a container registry?

Yes—use a registry like ghcr.io to store and version images so EC2 can pull specific tags during deployment.

How does Tailscale fit into the workflow?

Tailscale provides secure, ephemeral connectivity from GitHub Actions to EC2 so you can SSH or run remote commands without exposing ports.

What triggers a rollback?

A rollback is triggered when the CI deployment job fails health checks or when Docker Compose reports startup errors; include rollback commands in the deployment step.