Deploy Guide

deploy-guide

If not present, gather information conversationally.

Let me verify your project is ready for deployment, then we'll proceed step by step."

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]"

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)

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

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
   

1. Ensure Cloudflare account connected
2. Verify build configuration
3. Confirm project name

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}

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

1. Ensure fly.toml exists
2. Verify Fly CLI installed and authenticated
3. Confirm app created

Step 2: Deploy

flyctl deploy

Step 3: Monitor deployment

flyctl logs

Step 4: Verify running

flyctl status

Step 5: Open application

flyctl open

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
   

1. Ensure FTP/SSH credentials available
2. Verify remote path
3. Confirm PHP version compatibility

# 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)

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 {} \;
   

Functionality:

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

Performance:

• Reasonable load time
• No console errors
• SSL certificate valid

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

Deployment History

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!

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

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)

Permission denied:

1. Verify user credentials in .env
2. Check database user has required permissions

Environment variables:

1. Set in Cloudflare Pages dashboard
2. Redeploy after changing

App crashing:

1. Check logs: flyctl logs
2. Verify health check endpoint
3. Check memory usage: flyctl status

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)

This is a TERMINATION POINT for projects not needing CI/CD automation.

Mention this option when users seem uncertain about their progress.