deploy-preview
npx machina-cli add skill xvirobotics/metaskill/deploy-preview --openclawYou are a deployment preview agent. Your job is to build and launch a local preview environment using Docker, then verify it is healthy.
Current State
Current branch: !git branch --show-current
Git status: !git status --short
Deployment Steps
Step 1: Verify Docker is Available
docker --version && docker compose version
If Docker is not available, report that Docker must be installed and stop.
Step 2: Stop Any Existing Preview
docker compose -f docker-compose.yml down --remove-orphans 2>/dev/null || true
Step 3: Build Docker Images
Build the application image using the multi-stage Dockerfile:
docker compose -f docker-compose.yml build --no-cache
If the build fails, report the full error output. Common issues: missing files in build context (check .dockerignore), npm install failures, TypeScript compilation errors.
Step 4: Start Services
docker compose -f docker-compose.yml up -d
Wait for services to be healthy:
echo "Waiting for services to start..."
sleep 5
docker compose -f docker-compose.yml ps
Step 5: Run Database Migrations
docker compose -f docker-compose.yml exec -T app npx prisma migrate deploy
If migrations fail, report the error. Common issues: database not ready yet (may need longer wait), migration conflicts.
Step 6: Health Check
Verify the application is responding:
curl -sf http://localhost:3000/api/health || echo "HEALTH CHECK FAILED"
If the health check fails, inspect the logs:
docker compose -f docker-compose.yml logs --tail=50 app
Step 7: Report
## Preview Deployment Results
**Branch:** [branch name]
**Status:** RUNNING / FAILED at [step]
### Services
| Service | Status | Port |
|---------|--------|------|
| app | running/stopped | 3000 |
| db | running/stopped | 5432 |
| client | running/stopped | 5173 |
### Access URLs
- API: http://localhost:3000/api
- Frontend: http://localhost:5173
- Health: http://localhost:3000/api/health
### Cleanup
To stop the preview environment:
docker compose -f docker-compose.yml down
Source
git clone https://github.com/xvirobotics/metaskill/blob/main/examples/fullstack-web/.claude/skills/deploy-preview/SKILL.mdView on GitHub Overview
This skill automates building Docker images and launching a local preview environment with docker-compose, so you can test the full stack before merging. It emphasizes health checks and migrations to ensure reliability.
How This Skill Works
As a deployment preview agent, it verifies Docker availability, stops any existing preview, builds images using the multi-stage Dockerfile, and starts services with docker compose. It then runs database migrations via npx prisma migrate deploy and performs a health check against /api/health, reporting status or logs on failure.
When to Use It
- Preview a feature branch locally before merging to main
- Validate database migrations against a local environment
- Debug multi-service startup and connectivity issues
- Perform a quick end-to-end sanity check of API and frontend
- Generate a health-check report for stakeholders or PR notes
Quick Start
- Step 1: Verify Docker is installed: docker --version && docker compose version
- Step 2: Build and start the preview: docker compose -f docker-compose.yml build --no-cache; docker compose -f docker-compose.yml up -d
- Step 3: Run migrations and health check: docker compose -f docker-compose.yml exec -T app npx prisma migrate deploy; curl -sf http://localhost:3000/api/health || echo "HEALTH CHECK FAILED"
Best Practices
- Ensure Docker and Docker Compose are installed and running
- Keep docker-compose.yml updated with correct service definitions
- Keep the build context clean and verify .dockerignore excludes unnecessary files
- Run migrations after services start and monitor for conflicts
- Document and share access URLs and status in PR notes
Example Use Cases
- Previewing a new checkout flow by launching the full stack locally
- Testing Prisma migrate deploy against a local Postgres instance
- Smoke-testing API endpoints alongside frontend rendering
- Debugging service startup order and container networking locally
- Preparing a health-check report for a feature branch demo
