Deployment Model

📦 Understanding WEMAZU's deployment architecture, lifecycle, and rollback mechanisms.

This document explains how WEMAZU handles deployments, from the moment you trigger a deployment to its completion or failure.

Table of Contents

1. Core Principles
2. Branch-to-Domain Mapping
3. Deployment Lifecycle
4. Deployment Phases
5. Deployment Types
6. Rollbacks
7. What Rollbacks Do NOT Do

Core Principles

WEMAZU's deployment model is built on three core principles:

1. Predictability

Every deployment follows the same predictable flow:

• ✅ Same steps every time
• ✅ Clear status transitions
• ✅ Comprehensive logging at each step
• ✅ No "magic" or hidden operations

2. Safety

Deployments are designed to be safe:

• ✅ No automatic rollbacks (you control when to rollback)
• ✅ Previous deployments remain intact
• ✅ Failed deployments don't affect live sites
• ✅ Full audit trail of all actions

3. Transparency

You always know what's happening:

• ✅ Real-time status updates
• ✅ Detailed logs for every step
• ✅ Clear error messages when things fail
• ✅ Complete deployment history

Branch-to-Domain Mapping

How Branches Map to Domains

WEMAZU does not create Git branches. We read branches from your GitHub repository. You map a branch to a domain, server, and deploy path when you add or edit a domain. You can add as many branch→domain/server mappings as you want.

Example:

Domain: staging.example.com
└── Branch: develop → Server A → /var/www/staging

Domain: example.com
└── Branch: main → Server B → /var/www/production

Domain Branches

Each domain can have multiple branch configurations (each with its own server and deploy path):

Example Configuration:

Project: My Web App
Domain: example.com
├── Branch: main → Server A → /var/www/production (auto-deploy: ON)
├── Branch: develop → Server A → /var/www/staging (auto-deploy: ON)
└── Branch: feature/test → Server A → /var/www/test (auto-deploy: OFF)

Key Points:

• ✅ Branches are read from GitHub; you select which branch to deploy for each row
• ✅ Multiple branches can deploy to the same domain (with different paths)
• ✅ Each branch row has its own server and deploy path
• ✅ Auto-deploy can be enabled/disabled per branch
• ✅ Branch names are case-insensitive (normalized)

Branch Path Resolution

When deploying, WEMAZU uses the deploy path for the branch configuration (domain_branches row) you are deploying. If that row has a deploy_path set, that is used; otherwise the domain’s default deploy_path is used. If no path is found, deployment fails with a clear error message.

Deployment Lifecycle

High-Level Flow

graph TD
    A[Trigger Deployment] --> B[Create Deployment Record]
    B --> C[Status: queued]
    C --> D[Status: building]
    D --> E{Deployment Type}
    E -->|FTP/SFTP| F[Download Archive]
    E -->|SSH/VPS| G[Git Operations]
    F --> H[Extract & Upload]
    G --> I[Git Pull]
    H --> J{Success?}
    I --> J
    J -->|Yes| K[Status: success]
    J -->|No| L[Status: failed]
    K --> M[Update Domain Status]
    L --> N[Log Error]

Status Transitions

Deployments follow a strict status flow:

queued → building → success
                    ↓
                 failed

Status Meanings:

• queued: Deployment is created and waiting to start
• building: Deployment is actively executing
• success: Deployment completed successfully
• failed: Deployment encountered an error

Important: Once a deployment reaches success or failed, it cannot transition to another status. To redeploy, a new deployment record is created.

Deployment Phases

Phase 1: Queued

What Happens:

1. Deployment record is created in database
2. Status is set to queued
3. Deployment is ready to execute

Deployment Record:

• Deployment is created with a unique ID
• Status is set to queued
• All deployment metadata is stored

Logs:

• ✅ Deployment creation logged to logs table
• ✅ File log entry in deployment-debug.log

Duration: < 1 second (immediate)

Phase 2: Building

What Happens:

1. Status updates to building
2. build_started_at timestamp is set
3. Domain status updates to deploying (if domain exists)
4. Actual deployment execution begins

Status Update:

• Status changes to building
• Build start timestamp is recorded

Logs:

• ✅ Status change logged
• ✅ Build start logged with server and path information

Duration: Varies based on deployment type and repository size

Phase 3: Execution

This is where the actual deployment happens. The process differs based on deployment type:

FTP/SFTP Deployment Execution

Steps:

1. Fetch Repository Archive

   • Calls GitHub API: GET /repos/{owner}/{repo}/zipball/{branch}
   • Downloads ZIP archive to temporary location
   • Handles HTTP errors (404, 403, 500) with retries

2. Extract Archive

   • Extracts ZIP to temporary directory
   • Handles extraction errors

3. Upload Files

   • FTP: Uses FtpAdapter to upload files via FTP
   • SFTP: Uses SftpAdapter to upload files via SFTP
   • Uploads all files from extracted archive
   • Preserves directory structure

4. Cleanup

   • Removes temporary files
   • Closes FTP/SFTP connections

Logs:

• ✅ Archive download progress
• ✅ Extraction status
• ✅ Upload progress (file count, errors)
• ✅ Connection status

Common Errors:

• ❌ GitHub API rate limit exceeded
• ❌ Invalid repository or branch
• ❌ FTP/SFTP connection failure
• ❌ Permission denied on server
• ❌ Disk space full on server

SSH/VPS Deployment Execution

Steps:

1. Verify Path Exists

   • Checks if deploy path exists on server
   • Verifies path is accessible

2. Git Operations

   cd /var/www/production
   git fetch origin
   git checkout main
   git pull origin main
   

3. Verify Success

   • Checks git command exit codes
   • Verifies files were updated

Prerequisites:

• ✅ Repository must already exist on server (WEMAZU does not clone)
• ✅ Git must be installed on server
• ✅ SSH user must have write permissions
• ✅ Server must have network access to GitHub

Logs:

• ✅ SSH connection status
• ✅ Git command output (stdout/stderr)
• ✅ File change detection
• ✅ Error messages from git commands

Common Errors:

• ❌ Repository not found on server
• ❌ Git not installed
• ❌ Permission denied
• ❌ Branch does not exist
• ❌ Merge conflicts (git pull fails)

Phase 4: Success

What Happens:

1. Status updates to success
2. build_completed_at timestamp is set
3. Domain status updates to active (if domain exists)
4. Deployment output is saved (for SSH deployments)

Status Update:

• Status changes to success
• Build completion timestamp is recorded
• Deployment output is saved (for SSH deployments)

Logs:

• ✅ Success logged with deployment ID
• ✅ Output saved (for SSH deployments)
• ✅ Domain status update logged

Duration: < 1 second (status update only)

Phase 5: Failed

What Happens:

1. Status updates to failed
2. build_completed_at timestamp is set
3. Error message is saved
4. Domain status updates to error (if domain exists)
5. Full error context is logged

Status Update:

• Status changes to failed
• Build completion timestamp is recorded
• Error message and output are saved

Logs:

• ✅ Error logged with full context
• ✅ Stack trace saved (truncated to 1000 chars)
• ✅ Suggested action included
• ✅ Domain status update logged

Error Information:

• Error message
• Stack trace (if available)
• Deployment context (project, domain, branch, commit)
• Suggested action (e.g., "Check server connection")

Deployment Timeline

Visual Timeline

Time    Status      Action
─────────────────────────────────────────
00:00   queued      Deployment created
00:01   building    Status updated, execution starts
00:02   building    [FTP] Downloading archive...
00:05   building    [FTP] Extracting archive...
00:06   building    [FTP] Uploading files...
00:30   building    [FTP] Upload complete
00:31   success     Deployment completed

Typical Durations

Note: Durations vary significantly based on:

• Repository size
• Network speed
• Server performance
• Number of files

Deployment Types

FTP Deployment

Use Case: Traditional shared hosting with FTP access

How It Works:

1. Downloads repository ZIP archive from GitHub
2. Extracts archive to temporary directory
3. Uploads all files via FTP to deploy path
4. Preserves directory structure

Requirements:

• ✅ FTP server accessible
• ✅ Valid FTP credentials
• ✅ Write permissions on deploy path
• ✅ GitHub token with repo scope (for archive download)

Limitations:

• ❌ No Git history on server
• ❌ Full file upload every time (no incremental updates)
• ❌ Slower for large repositories

SFTP Deployment

Use Case: Secure file transfer to servers without Git

How It Works:

1. Downloads repository ZIP archive from GitHub
2. Extracts archive to temporary directory
3. Uploads all files via SFTP to deploy path
4. Preserves directory structure

Requirements:

• ✅ SFTP server accessible
• ✅ Valid SFTP credentials (or SSH key)
• ✅ Write permissions on deploy path
• ✅ GitHub token with repo scope

Advantages over FTP:

• ✅ Encrypted transfer
• ✅ More secure authentication
• ✅ Better error handling

Limitations:

• ❌ No Git history on server
• ❌ Full file upload every time
• ❌ Slower than SSH/VPS deployments

SSH/VPS Deployment

Use Case: Virtual Private Servers with Git installed

How It Works:

1. Connects to server via SSH
2. Navigates to deploy path (must be existing Git repository)
3. Runs: git fetch origin
4. Runs: git checkout {branch}
5. Runs: git pull origin {branch}

Requirements:

• ✅ SSH access to server
• ✅ Git installed on server
• ✅ Repository already cloned on server
• ✅ Write permissions on deploy path
• ✅ Network access to GitHub from server

Advantages:

• ✅ Fast (only downloads changes)
• ✅ Preserves Git history
• ✅ Can use Git hooks (pre-deploy, post-deploy)
• ✅ Can handle merge conflicts (manual resolution)

Limitations:

• ❌ Requires Git on server
• ❌ Repository must be pre-cloned
• ❌ More complex setup

Rollbacks

What is a Rollback?

A rollback in WEMAZU means: Deploying a previous successful commit to the same domain.

Important: Rollbacks are not automatic. You must manually trigger them.

How Rollbacks Work

Step 1: Select Previous Deployment

1. Go to your Project → Deployments tab
2. Find a previous successful deployment
3. Click "Rollback" button

Step 2: Rollback Process

WEMAZU:

1. ✅ Identifies the target deployment's commit SHA
2. ✅ Creates a new deployment record (not modifying the old one)
3. ✅ Deploys that commit to the same domain
4. ✅ Follows the same deployment lifecycle as a normal deployment

Rollback Process:

• WEMAZU finds the previous successful deployment for the domain
• Creates a new deployment record with that commit SHA
• Executes the deployment using the same process as a normal deployment

Step 3: Execution

The rollback deployment executes exactly like a normal deployment:

• ✅ Same deployment type (FTP/SFTP/SSH)
• ✅ Same deploy path
• ✅ Same server
• ✅ Same lifecycle (queued → building → success/failed)

Rollback Limitations

What Rollbacks CANNOT Do:

1. ❌ Restore Database Changes: If your code changes included database migrations, rolling back code does not roll back the database
2. ❌ Restore File Deletions: If files were deleted in a later deployment, rolling back may not restore them (depends on deployment type)
3. ❌ Undo Configuration Changes: Server configuration changes are not affected
4. ❌ Restore External Dependencies: Changes to external services (APIs, CDNs) are not rolled back

What Rollbacks CAN Do:

1. ✅ Restore Code: Previous version of your code is deployed
2. ✅ Restore File Structure: File structure from previous deployment is restored (for FTP/SFTP)
3. ✅ Git Checkout: For SSH/VPS, performs git checkout {previous_commit}

Rollback Best Practices

1. Test First: Test rollbacks on a non-production domain or path before using on live
2. Document Dependencies: Keep track of database migrations and external changes
3. Monitor After Rollback: Check logs and application behavior after rollback
4. Plan Ahead: Know which deployments are "safe" to roll back to

Rollback Example

Scenario:

Deployment #10: Commit abc123 (success) ← Current live
Deployment #11: Commit def456 (success) ← New deployment
Deployment #12: Commit ghi789 (failed) ← Broken deployment

Rollback Process:

1. Click "Rollback" on Deployment #10
2. WEMAZU creates Deployment #13 with commit abc123
3. Deployment #13 executes and succeeds
4. Your site is now back to the state of Deployment #10

Result:

• ✅ Code is restored to commit abc123
• ❌ Database changes from Deployment #11 are NOT rolled back
• ❌ External API changes are NOT rolled back

What Rollbacks Do NOT Do

1. Database Rollbacks

Problem: If your deployment included database migrations, rolling back code does not roll back the database.

Example:

Deployment #10: Added users table (migration)
Deployment #11: Modified users table structure
Rollback to #10: Code is rolled back, but database still has new structure

Solution: Maintain separate database migration rollback scripts if needed.

2. File Deletion Recovery

Problem: If a later deployment deleted files, rolling back may not restore them.

FTP/SFTP:

• ✅ Files are uploaded from archive, so deleted files are restored
• ⚠️ But if files were added after the rollback target, they remain

SSH/VPS:

• ✅ git checkout restores files from that commit
• ⚠️ But uncommitted files on server are not affected

3. Configuration Changes

Problem: Server configuration changes (.htaccess, nginx.conf, etc.) are not rolled back if they were made outside WEMAZU.

Example:

Deployment #10: Code only
Manual change: Modified .htaccess on server
Deployment #11: Code update
Rollback to #10: Code is rolled back, but .htaccess changes remain

4. External Dependencies

Problem: Changes to external services are not rolled back.

Examples:

• API endpoints changed
• CDN configuration updated
• Third-party service integrations modified

5. Environment Variables

Problem: Environment variable changes on the server are not rolled back.

Example:

Deployment #10: Uses API_KEY=v1
Manual change: API_KEY=v2 set on server
Deployment #11: Code update
Rollback to #10: Code is rolled back, but API_KEY=v2 remains

Deployment Records

What Gets Stored

Every deployment creates a deployment record with the following information:

Deployment Information:

• Unique deployment ID
• Associated project
• Target domain and branch (the branch→domain/server mapping you configured)
• Git branch deployed
• Commit SHA deployed
• Current status (queued/building/success/failed)
• Build start and completion timestamps
• Deployment output (for SSH deployments)
• Error message (if failed)
• User who triggered deployment
• Creation and update timestamps

Deployment History

You can view deployment history in:

• Project Detail Page → Deployments tab
• Dashboard → Deployments list

Filters:

• Filter by project
• Filter by domain
• Filter by status
• Filter by date range

Troubleshooting

Deployment Stuck in "Queued"

Problem: Deployment never transitions to "building".

Possible Causes:

• Deployment service is not running
• Database connection issue
• Exception thrown before status update

Solution:

1. Check deployment-debug.log for errors
2. Verify deployment service is running
3. Check database connectivity

Deployment Stuck in "Building"

Problem: Deployment never completes.

Possible Causes:

• Long-running operation (large repository)
• Network timeout
• Server connection lost
• Process killed

Solution:

1. Check deployment-debug.log for last activity
2. Verify server is accessible
3. Check network connectivity
4. Consider increasing timeout values

"Deployment failed" with No Error Message

Problem: Deployment shows "failed" but no error details.

Solution:

1. Check Dashboard → Logs for detailed error
2. Check deployment-debug.log file
3. Verify server logs for connection issues

FTP/SFTP Upload Fails

Problem: Files fail to upload.

Check:

1. Permissions: Ensure FTP/SFTP user has write permissions
2. Disk Space: Verify server has enough disk space
3. Path: Ensure deploy path exists and is correct
4. Connection: Test FTP/SFTP connection manually

SSH Git Pull Fails

Problem: git pull fails during deployment.

Check:

1. Repository: Ensure repository exists on server
2. Permissions: Ensure SSH user can write to repository
3. Git: Verify Git is installed on server
4. Network: Ensure server can access GitHub
5. Merge Conflicts: Check for uncommitted changes or merge conflicts

Next Steps:

• 📖 Environments & Domains - Configure your deployment targets
• 📖 Logs & Monitoring - Monitor your deployments
• 📖 Security & Responsibility Boundaries - Understand security practices