deployment-procedures

Deployment Procedures

Deployment principles and decision-making for safe production releases. Learn to THINK, not memorize scripts.

---

⚠️ How to Use This Skill

This skill teaches deployment principles, not bash scripts to copy.

• Every deployment is unique
• Understand the WHY behind each step
• Adapt procedures to your platform

---

1. Platform Selection

Decision Tree

What are you deploying?
│
├── Static site / JAMstack
│   └── Vercel, Netlify, Cloudflare Pages
│
├── Simple web app
│   ├── Managed → Railway, Render, Fly.io
│   └── Control → VPS + PM2/Docker
│
├── Microservices
│   └── Container orchestration
│
└── Serverless
    └── Edge functions, Lambda

Each Platform Has Different Procedures

Platform	Deployment Method
Vercel/Netlify	Git push, auto-deploy
Railway/Render	Git push or CLI
VPS + PM2	SSH + manual steps
Docker	Image push + orchestration
Kubernetes	kubectl apply

---

2. Pre-Deployment Principles

The 4 Verification Categories

Category	What to Check
Code Quality	Tests passing, linting clean, reviewed
Build	Production build works, no warnings
Environment	Env vars set, secrets current
Safety	Backup done, rollback plan ready

Pre-Deployment Checklist

• All tests passing
• Code reviewed and approved
• Production build successful
• Environment variables verified
• Database migrations ready (if any)
• Rollback plan documented
• Team notified
• Monitoring ready

---

3. Deployment Workflow Principles

The 5-Phase Process

1. PREPARE
   └── Verify code, build, env vars

2. BACKUP
   └── Save current state before changing

3. DEPLOY
   └── Execute with monitoring open

4. VERIFY
   └── Health check, logs, key flows

5. CONFIRM or ROLLBACK
   └── All good? Confirm. Issues? Rollback.

Phase Principles

Phase	Principle
Prepare	Never deploy untested code
Backup	Can't rollback without backup
Deploy	Watch it happen, don't walk away
Verify	Trust but verify
Confirm	Have rollback trigger ready

---

4. Post-Deployment Verification

What to Verify

Check	Why
Health endpoint	Service is running
Error logs	No new errors
Key user flows	Critical features work
Performance	Response times acceptable

Verification Window

• First 5 minutes: Active monitoring
• 15 minutes: Confirm stable
• 1 hour: Final verification
• Next day: Review metrics

---

5. Rollback Principles

When to Rollback

Symptom	Action
Service down	Rollback immediately
Critical errors	Rollback
Performance >50% degraded	Consider rollback
Minor issues	Fix forward if quick

Rollback Strategy by Platform

Platform	Rollback Method
Vercel/Netlify	Redeploy previous commit
Railway/Render	Rollback in dashboard
VPS + PM2	Restore backup, restart
Docker	Verified previous immutable image digest
K8s	kubectl rollout undo

Rollback Principles

1. Speed over perfection: Rollback first, debug later
2. Don't compound errors: One rollback, not multiple changes
3. Communicate: Tell team what happened
4. Post-mortem: Understand why after stable

---

6. Zero-Downtime Deployment

Strategies

Strategy	How It Works
Rolling	Replace instances one by one
Blue-Green	Switch traffic between environments
Canary	Gradual traffic shift

Selection Principles

Scenario	Strategy
Standard release	Rolling
High-risk change	Blue-green (easy rollback)
Need validation	Canary (test with real traffic)

---

7. Emergency Procedures

Service Down Priority

1. Assess: What's the symptom?
2. Stabilize: Preserve logs and identify impact; restart only when the approved incident procedure supports it
3. Rollback: Use a verified compatible artifact and data migration plan when the rollback trigger is met
4. Investigate: After stable

Investigation Order

Check	Common Issues
Logs	Errors, exceptions
Resources	Disk full, memory
Network	DNS, firewall
Dependencies	Database, APIs

---

8. Anti-Patterns

❌ Don't	✅ Do
Deploy on Friday	Deploy early in week
Rush deployment	Follow the process
Skip staging	Always test first
Deploy without backup	Backup before deploy
Walk away after deploy	Monitor for 15+ min
Multiple changes at once	One change at a time

---

9. Decision Checklist

Before deploying:

• Platform-appropriate procedure?
• Backup strategy ready?
• Rollback plan documented?
• Monitoring configured?
• Team notified?
• Time to monitor after?

---

10. Best Practices

1. Small, frequent deploys over big releases
2. Feature flags for risky changes
3. Automate repetitive steps
4. Document every deployment
5. Review what went wrong after issues
6. Test rollback before you need it

---

Remember: Every deployment is a risk. Minimize risk through preparation, not speed.

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.