Deployment

Learn how to deploy your applications with Gokku.

Overview

Gokku uses a git-push deployment workflow:

1. Push code to Git remote on server
2. Git hook triggers automatically
3. Code is built and deployed
4. Service restarts with new version

First Deployment

1. Create gokku.yml

In your project root:

apps:
  api:
    path: ./cmd/api

2. Add Git Remote

On your local machine:

git remote add production ubuntu@server:api

3. Deploy (Auto-Setup)

git push production main

The first push automatically creates:

• Git repository
• App directories
• Docker containers
• Environment file from gokku.yml

Watch the deployment:

Counting objects: 100, done.
-----> Deploying api to production...
-----> Extracting code to /opt/gokku/apps/api/production/releases/1
-----> Building api...
-----> Build complete (binary: 5.2M)
-----> Creating symlink: current -> releases/1
-----> Restarting api-production...
-----> Deploy successful!
To ubuntu@server:api
   abc1234..def5678  main -> main

5. Verify

# Check container status
ssh ubuntu@server "docker ps | grep api"

# Check logs
ssh ubuntu@server "docker logs -f api"

# Test endpoint
curl http://your-server:8080/health

Deployment Flow

Docker Apps

Directory Structure

Docker Deployment

/opt/gokku/apps/api/production/
├── .env            # Environment variables
├── deploy.log      # Deployment logs
└── (Docker images stored in Docker)

Deployment Settings

Configure in gokku.yml:

apps:
  api:
    deployment:
      keep_releases: 10       # Number of releases to keep
      keep_images: 10         # Number of Docker images to keep
      restart_policy: always  # Restart policy
      restart_delay: 5        # Seconds between restarts

Restart Policies

• always - Always restart on failure (default)
• on-failure - Restart only on non-zero exit
• no - Never restart

Atomic Deployments

Gokku uses atomic deployments for zero-downtime:

How It Works

1. Build in new directory - New release doesn't affect running app
2. Update symlink atomically - Instant switch to new version
3. Restart service - Picks up new code

# Old version running
current -> releases/3

# New version built
releases/4/  (ready)

# Atomic switch
current -> releases/4  (instant)

# Restart picks up new code
docker restart api

Downtime

• Standard Docker: ~2-5 seconds during container swap
• Blue-Green (ZERO_DOWNTIME=1): Zero downtime with instant traffic switch

Add remotes:

git remote add production ubuntu@server:api
git remote add staging ubuntu@server:api

Deploy

# Deploy to staging
git push staging staging

# Test staging
curl https://staging.example.com/health

# Deploy to production
git push production main

Deployment Strategies

1. Direct to Production

Simple and fast:

git push production main

Pros:

• Fast
• Simple

Cons:

• No testing
• Risky

Use when:

• Small projects
• Solo developer
• Low traffic

2. Staging → Production

Test before production:

# 1. Deploy to staging
git push staging main

# 2. Test
./test-staging.sh

# 3. Deploy to production
git push production main

Pros:

• Catch bugs early
• Safe

Cons:

• Slower
• More setup

Use when:

• Team projects
• Critical apps
• Customer-facing

3. Feature Branches

Deploy branches to test:

# Deploy feature branch to staging
git push staging feature/new-ui

# Test
curl https://staging.example.com

# Merge and deploy to production
git checkout main
git merge feature/new-ui
git push production main

Next Steps

• Rollback - Revert failed deployments
• Environment Variables - Configure apps
• Docker Support - Deploy with Docker
• Examples - Real-world examples