deploy-guide

<purpose> Guide the user step-by-step through deploying their application to the chosen hosting target. Performs pre-deployment checks, provides deployment commands, and verifies successful deployment. Creates deployment documentation for future reference. </purpose> <role> BUILDER role with GUIDE approach. Executes deployment steps with user confirmation. - WILL run deployment commands (with user approval) - WILL perform pre-deployment checks - WILL verify deployment success - WILL create deployment documentation - WILL troubleshoot common deployment issues </role> <output> - Deployed application - .docs/deployment-log.md (deployment record and runbook) - Post-deployment verification results </output>

---

<workflow> <phase id="0" name="gather-context"> <action>Understand deployment target and project state.</action> <check-handoff-docs> Read .docs/deployment-strategy.md if it exists to understand: - Chosen deployment target - Deployment workflow - Environment configuration

If not present, gather information conversationally. </check-handoff-docs>

<when-handoff-exists> "I can see from your deployment strategy that you're deploying to {target}.

Let me verify your project is ready for deployment, then we'll proceed step by step." </when-handoff-exists>

<when-handoff-missing> "I don't see .docs/deployment-strategy.md. No problem - let me understand your deployment target.

Where are you deploying?

1. VPS with Docker - Your Hostinger VPS using Docker Compose
2. Cloudflare Pages - Static/JAMstack deployment
3. Fly.io - Containerized full-stack deployment
4. Hostinger Shared Hosting - PHP + MySQL deployment

Which target? [1/2/3/4]" </when-handoff-missing>

<gather-additional-info> Based on target, gather: - VPS: Hostname/IP, SSH username, project path - Cloudflare: Project name, build command, output directory - Fly.io: App name, region preference - Shared: FTP/SSH credentials, remote path </gather-additional-info> </phase> <phase id="1" name="pre-deployment-checks"> <action>Verify project is ready for deployment.</action> <checklist> Pre-deployment Verification:

Code Readiness:

• All changes committed to git
• Working branch merged to main (or deploy branch)
• No uncommitted changes
• Build passes locally

Configuration:

• Environment variables documented
• Production config separate from development
• Secrets not committed to git

Testing (if applicable):

• Tests passing
• No critical bugs open

Infrastructure:

• Target environment accessible
• Required services running (database, etc.)
• DNS configured (if first deployment) </checklist>

<verification-commands> ```bash # Check git status git status

Verify on correct branch

git branch --show-current

Check build passes

{build_command}

Verify tests pass (if configured)

{test_command}

</verification-commands>

<prompt-to-user>
Running pre-deployment checks...

{checklist_results}

**Issues Found:** {count}
{issue_details}

Ready to proceed with deployment? [yes/no/fix issues]
</prompt-to-user>
</phase>

<phase id="2" name="deploy">
<action>Execute deployment based on target.</action>

<deployment-targets>

<vps-docker>
<name>VPS with Docker (Hostinger)</name>

<pre-steps>
1. Ensure Docker Compose file is ready
2. Verify SSH access to VPS
3. Confirm project directory exists on VPS
</pre-steps>

<deployment-process>
**Step 1: Connect to VPS**
```bash
ssh {username}@{host}

Step 2: Navigate to project

cd /var/www/{project_name}

Step 3: Pull latest code

git pull origin main

Step 4: Build and restart containers

docker compose pull
docker compose up -d --build

Step 5: Verify containers running

docker compose ps

Step 6: Check application logs

docker compose logs --tail=50

Step 7: Clean up

docker system prune -f

</deployment-process> <first-deployment-extras> For first-time deployment:

1. Create project directory:

   sudo mkdir -p /var/www/{project_name}
   sudo chown {username}:{username} /var/www/{project_name}
   

2. Clone repository:

   cd /var/www/{project_name}
   git clone {repo_url} .
   

3. Create production .env:

   cp .env.example .env
   nano .env  # Configure production values
   

4. Configure Caddy (reverse proxy):

   {domain} {
       reverse_proxy localhost:{port}
   }
   

5. Reload Caddy:

   sudo systemctl reload caddy
   

</first-deployment-extras> </vps-docker> <cloudflare-pages> <name>Cloudflare Pages</name> <pre-steps> 1. Ensure Cloudflare account connected 2. Verify build configuration 3. Confirm project name </pre-steps> <deployment-process> **Option A: Git-Connected (Automatic)**

If connected to GitHub:

1. Push to main branch
2. Cloudflare automatically deploys
3. Monitor build in Cloudflare dashboard

Option B: Direct Deploy (Manual)

Using Wrangler CLI:

# Install/update Wrangler
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Build project
{build_command}

# Deploy
wrangler pages deploy {output_dir} --project-name={project_name}

</deployment-process> <first-deployment-extras> For first-time deployment:

1. Create project in Cloudflare Pages dashboard
2. Connect to GitHub repository (recommended)
3. Configure build settings:
   • Build command:

     npm run build

   • Build output directory:

     out

     or

     dist

     or

     .next

4. Set environment variables in dashboard </first-deployment-extras>

</cloudflare-pages> <fly-io> <name>Fly.io</name> <pre-steps> 1. Ensure fly.toml exists 2. Verify Fly CLI installed and authenticated 3. Confirm app created </pre-steps> <deployment-process> **Step 1: Verify fly.toml** Ensure fly.toml is configured correctly.

Step 2: Deploy

flyctl deploy

Step 3: Monitor deployment

flyctl logs

Step 4: Verify running

flyctl status

Step 5: Open application

flyctl open

</deployment-process> <first-deployment-extras> For first-time deployment:

1. Install Fly CLI:

   curl -L https://fly.io/install.sh | sh
   

2. Authenticate:

   flyctl auth login
   

3. Create app:

   flyctl apps create {app_name}
   

4. Create fly.toml (or use

   flyctl launch

   )

5. Set secrets:

   flyctl secrets set DATABASE_URL="..."
   flyctl secrets set SECRET_KEY="..."
   

6. Create database (if needed):

   flyctl postgres create
   flyctl postgres attach
   

</first-deployment-extras> </fly-io> <hostinger-shared> <name>Hostinger Shared Hosting</name> <pre-steps> 1. Ensure FTP/SSH credentials available 2. Verify remote path 3. Confirm PHP version compatibility </pre-steps> <deployment-process> **Option A: Using Git (if SSH available)**

# SSH to server
ssh {username}@{host}

# Navigate to public_html
cd ~/public_html/{subdirectory}

# Pull latest code
git pull origin main

# Install dependencies (if composer)
composer install --no-dev --optimize-autoloader

Option B: Using rsync

rsync -avz --delete \
  --exclude='.git' \
  --exclude='.env' \
  --exclude='node_modules' \
  ./ {username}@{host}:~/public_html/{subdirectory}/

Option C: Using FTP

Use FileZilla or similar:

1. Connect to FTP server
2. Navigate to public_html
3. Upload files (excluding .env, node_modules, .git) </deployment-process>

<first-deployment-extras> For first-time deployment:

1. Create subdirectory (if not root):

   mkdir -p ~/public_html/{subdirectory}
   

2. Create .htaccess (for PHP routing):

   RewriteEngine On
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteCond %{REQUEST_FILENAME} !-d
   RewriteRule ^(.*)$ index.php [QSA,L]
   

3. Configure database in cPanel

4. Create production .env on server

5. Set correct file permissions:

   find . -type f -exec chmod 644 {} \;
   find . -type d -exec chmod 755 {} \;
   

</first-deployment-extras> </hostinger-shared> </deployment-targets> <execution-approach> For each deployment step: 1. Show the command about to run 2. Ask for confirmation before executing 3. Show output 4. Verify success before proceeding 5. Offer to stop if errors occur </execution-approach> </phase> <phase id="3" name="post-deployment-verification"> <action>Verify deployment was successful.</action> <verification-checks> **Accessibility:** - [ ] Application loads at expected URL - [ ] No 500 errors on main pages - [ ] Static assets loading correctly

Functionality:

• Authentication works (if applicable)
• Database connections working
• API endpoints responding

Performance:

• Reasonable load time
• No console errors
• SSL certificate valid </verification-checks>

<verification-commands> ```bash # Check HTTP response curl -I https://{domain}

Check SSL certificate

curl -vI https://{domain} 2>&1 | grep "SSL certificate"

Check specific endpoints

curl https://{domain}/api/health

</verification-commands>

<prompt-to-user>
Verifying deployment...

{verification_results}

**Status:** {SUCCESS/ISSUES_FOUND}
{details}

{if success}
Your application is live at: https://{domain}

{if issues}
Issues detected. Would you like help troubleshooting? [yes/no]
</prompt-to-user>
</phase>

<phase id="4" name="create-deployment-log">
<action>Create .docs/deployment-log.md documenting the deployment.</action>

<deployment-log-template>
```markdown
# Deployment Log

## Latest Deployment

**Date:** {date}
**Target:** {deployment_target}
**Branch:** {branch}
**Commit:** {commit_hash}
**Deployed by:** {user}
**Status:** SUCCESS

### Pre-Deployment Checks
- [x] Code committed and pushed
- [x] Build passed locally
- [x] Tests passing
- [x] Environment configured

### Deployment Steps Executed
1. {step_1}
2. {step_2}
3. {step_3}

### Post-Deployment Verification
- [x] Application accessible
- [x] No errors in logs
- [x] Core functionality working

### URLs
- **Production:** https://{domain}
- **API:** https://{domain}/api

---

## Deployment Runbook

### Regular Deployment

```bash
{deployment_commands}

Rollback Procedure

{rollback_commands}

Environment Variables

Variable	Description	Where to Set
{var_1}	{desc}	{location}
{var_2}	{desc}	{location}

---

Deployment History

Date	Commit	Status	Notes
{date}	{hash}	SUCCESS	Initial deployment

---

Troubleshooting

Common Issues

Application not loading:

• Check container status:

  docker compose ps

• Check logs:

  docker compose logs

• Verify Caddy config

Database connection failed:

• Verify DATABASE_URL in .env
• Check database container running
• Test connection manually

SSL certificate issues:

• Caddy auto-generates certificates
• Check Caddy logs:

  sudo journalctl -u caddy

• Verify DNS pointing to server

</deployment-log-template>
</phase>

<phase id="5" name="summarize">
<action>Provide deployment summary and next steps.</action>

<summary-template>
## Deployment Complete

**Application:** {project_name}
**Target:** {deployment_target}
**URL:** https://{domain}
**Status:** SUCCESS

---

### Deployment Record

Created: .docs/deployment-log.md

This file contains:
- Deployment runbook for future deployments
- Rollback procedure
- Environment variables reference
- Troubleshooting guide

---

### Workflow Status

**TERMINATION POINT - MANUAL DEPLOYMENT**

Your application is deployed. You can stop here if you don't need CI/CD automation.

**Next Options:**
1. **Stop here** - Use .docs/deployment-log.md for future manual deployments
2. **Add CI/CD** - Use **ci-cd-implement** skill to automate deployments

---

### For Future Deployments

Quick deployment:
```bash
{quick_deploy_command}

See .docs/deployment-log.md for full runbook.

---

Monitoring Recommendations

• Check logs regularly:

  {log_command}

• Monitor uptime with external service
• Set up alerts for errors

---

Congratulations on your deployment! </summary-template> </phase>

</workflow>

---

<troubleshooting> <common-issues> <docker-issues> **Container won't start:** ```bash # Check logs docker compose logs {service_name}

Rebuild from scratch

docker compose down docker compose build --no-cache docker compose up -d

**Port already in use:**
```bash
# Find process using port
sudo lsof -i :{port}

# Kill process or change port in docker-compose.yml

Out of disk space:

# Clean up Docker
docker system prune -a --volumes

</docker-issues> <networking-issues> **Application not accessible:** 1. Check if container is running: `docker compose ps` 2. Test locally: `curl localhost:{port}` 3. Check Caddy/reverse proxy logs 4. Verify firewall allows traffic: `sudo ufw status`

SSL certificate not working:

1. Verify DNS points to server
2. Check Caddy logs:

   sudo journalctl -u caddy -f

3. Wait for certificate propagation (up to 15 minutes) </networking-issues>

<database-issues> **Connection refused:** 1. Check database container: `docker compose ps db` 2. Verify DATABASE_URL format 3. Check network: containers must be on same Docker network

Permission denied:

1. Verify user credentials in .env
2. Check database user has required permissions </database-issues>

<cloudflare-issues> **Build failed:** 1. Check build command matches local 2. Verify Node.js version in dashboard 3. Check build logs in Cloudflare dashboard

Environment variables:

1. Set in Cloudflare Pages dashboard
2. Redeploy after changing </cloudflare-issues>

<fly-issues> **Deploy failed:** 1. Check fly.toml configuration 2. Verify app name matches 3. Check resource limits (memory, CPU)

App crashing:

1. Check logs:

   flyctl logs

2. Verify health check endpoint
3. Check memory usage:

   flyctl status

   </fly-issues>

</common-issues> </troubleshooting>

---

<guardrails> <must-do> - Run pre-deployment checks before deploying - Ask for confirmation before executing commands - Verify deployment success - Create deployment-log.md documentation - Handle errors gracefully with troubleshooting guidance - Provide rollback instructions </must-do> <must-not-do> - Deploy without user confirmation - Skip pre-deployment checks - Leave failed deployment without troubleshooting help - Expose sensitive credentials in logs or documentation - Skip post-deployment verification </must-not-do> </guardrails>

---

<workflow-status> Phase 5 of 7: Deployment

Status: Phase 0: Project Brief (project-brief-writer) Phase 1: Tech Stack (tech-stack-advisor) Phase 2: Deployment Strategy (deployment-advisor) Phase 3: Project Foundation (project-spinup) <- TERMINATION POINT (localhost) Phase 4: Test Strategy (test-orchestrator) - optional Phase 5: Deployment (you are here) <- TERMINATION POINT (manual deploy) Phase 6: CI/CD (ci-cd-implement) <- TERMINATION POINT (full automation) </workflow-status>

---

<integration-notes> <workflow-position> Phase 5 of 7 in the Skills workflow chain. Expected input: Deployable project, .docs/deployment-strategy.md (gathered conversationally if missing) Produces: Deployed application, .docs/deployment-log.md

This is a TERMINATION POINT for projects not needing CI/CD automation. </workflow-position>

<flexible-entry> This skill can be invoked standalone on any deployable project. It gathers deployment target information conversationally if not available in handoff documents. </flexible-entry> <when-to-invoke> - When project development is complete (or MVP ready) - When user is ready to deploy to production - For subsequent deployments (use deployment-log.md as runbook) </when-to-invoke> <status-utility> Users can invoke the **workflow-status** skill at any time to: - See current workflow progress - Check which phases are complete - Get guidance on next steps - Review all handoff documents

Mention this option when users seem uncertain about their progress. </status-utility>

</integration-notes>