honeyDueAPI/docs/DOKKU_SETUP.md

Dokku Deployment Guide for honeyDue API

This guide provides step-by-step instructions for deploying the honeyDue Go API to a remote server using Dokku.

Table of Contents

1. Prerequisites
2. Server Setup
3. Install Dokku
4. Create the App
5. Configure PostgreSQL
6. Configure Redis
7. Set Environment Variables
8. Configure Storage
9. Deploy the Application
10. Configure SSL
11. Set Up Worker Process
12. Push Notifications (Optional)
13. Maintenance Commands
14. Troubleshooting

---

Prerequisites

Server Requirements

• Ubuntu 22.04 LTS (recommended) or 20.04 LTS
• Minimum 2GB RAM (4GB+ recommended for production)
• 20GB+ disk space
• Root or sudo access
• Domain name pointed to your server's IP

Local Requirements

• Git installed
• SSH key configured for server access

---

Server Setup

1. Connect to Your Server

ssh root@your-server-ip

2. Update System Packages

apt update && apt upgrade -y

3. Set Up Swap (Recommended for servers with limited RAM)

# Create 2GB swap file
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

# Make permanent
echo '/swapfile none swap sw 0 0' | tee -a /etc/fstab

4. Configure Firewall

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

---

Install Dokku

1. Download and Install Dokku

# Download the installation script
wget -NP . https://dokku.com/install/v0.34.4/bootstrap.sh

# Run the installer (takes 5-10 minutes)
sudo DOKKU_TAG=v0.34.4 bash bootstrap.sh

2. Configure Dokku

# Set your domain (replace with your actual domain)
dokku domains:set-global honeyDue.treytartt.com

# Add your SSH public key for deployments
# Run this from your LOCAL machine:
cat ~/.ssh/id_rsa.pub | ssh root@your-server-ip dokku ssh-keys:add admin

3. Install Required Plugins

# PostgreSQL plugin
dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres

# Redis plugin
dokku plugin:install https://github.com/dokku/dokku-redis.git redis

# Let's Encrypt plugin (for SSL)
dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

---

Create the App

1. Create the Dokku App

dokku apps:create honeydue-api

2. Set the Domain

dokku domains:add honeydue-api api.honeyDue.treytartt.com

3. Configure Buildpack (if needed)

The app uses a Dockerfile, so Dokku will auto-detect it. If you need to force Docker builds:

dokku builder:set honeydue-api build-dir .
dokku builder-dockerfile:set honeydue-api dockerfile-path Dockerfile

---

Configure PostgreSQL

1. Create PostgreSQL Service

# Create the database service
dokku postgres:create honeydue-db

# Link to the app (automatically sets DATABASE_URL)
dokku postgres:link honeydue-db honeydue-api

2. Verify Connection

# Check the connection info
dokku postgres:info honeydue-db

# Connect to the database
dokku postgres:connect honeydue-db

3. Set Individual Database Variables

Dokku sets DATABASE_URL automatically, but the app expects individual variables:

# Get the database credentials
dokku postgres:info honeydue-db

# Set individual variables (replace with actual values from info command)
dokku config:set honeydue-api \
  DB_HOST=dokku-postgres-honeydue-db \
  DB_PORT=5432 \
  POSTGRES_DB=honeydue_db \
  POSTGRES_USER=postgres \
  POSTGRES_PASSWORD=1mJPfu6rzG9r6xukcGbUOU5NoCg0jKfa

---

Configure Redis

1. Create Redis Service

# Create the Redis service
dokku redis:create honeydue-redis

# Link to the app (automatically sets REDIS_URL)
dokku redis:link honeydue-redis honeydue-api

2. Verify Connection

dokku redis:info honeydue-redis

---

Set Environment Variables

1. Required Variables

dokku config:set honeydue-api \
  PORT=5000 \
  DEBUG=false \
  ALLOWED_HOSTS=api.honeyDue.treytartt.com,localhost \
  TIMEZONE=UTC \
  SECRET_KEY=8553813eda361017a02677ed504abdd331537cfe6f7cc407345f037cc22c75fc

2. Email Configuration

dokku config:set honeydue-api \
  EMAIL_HOST=smtp.fastmail.com \
  EMAIL_PORT=587 \
  EMAIL_USE_TLS=true \
  EMAIL_HOST_USER=treytartt@fastmail.com \
  EMAIL_HOST_PASSWORD=2t9y4n4t497z5863 \
  DEFAULT_FROM_EMAIL="honeyDue <treytartt@fastmail.com>"

3. Apple Sign In (Optional)

dokku config:set honeydue-api \
  APPLE_CLIENT_ID=com.tt.honeyDue.honeyDueDev \
  APPLE_TEAM_ID=V3PF3M6B6U

4. Push Notifications (Optional)

The API uses direct APNs/FCM connections (no external push server needed):

dokku config:set honeydue-api \
  APNS_AUTH_KEY_PATH=/push_certs/AuthKey_R9N3SM2WD5.p8 \
  APNS_AUTH_KEY_ID=R9N3SM2WD5 \
  APNS_TEAM_ID=V3PF3M6B6U \
  APNS_TOPIC=com.tt.honeyDue.honeyDueDev \
  APNS_PRODUCTION=true \
  FCM_SERVER_KEY=your-firebase-server-key

5. Admin Panel URL

dokku config:set honeydue-api \
  NEXT_PUBLIC_API_URL=https://api.honeyDue.treytartt.com

6. View All Configuration

dokku config:show honeydue-api

---

Configure Storage

1. Create Persistent Storage Directory

# Create storage directory on host
mkdir -p /var/lib/dokku/data/storage/honeydue-api/uploads

# Set permissions
chown -R 32767:32767 /var/lib/dokku/data/storage/honeydue-api

2. Mount Storage to App

dokku storage:mount honeydue-api /var/lib/dokku/data/storage/honeydue-api/uploads:/app/uploads

---

Deploy the Application

1. Add Dokku Remote (Local Machine)

cd /path/to/honeyDueAPI-go
git remote add dokku dokku@your-server-ip:honeydue-api

2. Deploy

git push dokku master:main
# Or if your branch is already 'main':
git push dokku main

3. Watch Deployment Logs

# On server
dokku logs honeydue-api -t

4. Verify Deployment

# Check app status
dokku ps:report honeydue-api

# Check app is running
curl https://api.honeyDue.treytartt.com/api/health/

---

Configure SSL

1. Set Let's Encrypt Email

dokku letsencrypt:set honeydue-api email admin@treytartt.com

2. Enable Let's Encrypt

dokku letsencrypt:enable honeydue-api

3. Set Up Auto-Renewal

dokku letsencrypt:cron-job --add

---

Set Up Worker Process

The worker process handles background jobs (task reminders, overdue alerts, daily digests, email sending, etc.).

1. Configure Worker Environment Variables

dokku config:set honeydue-api \
  TASK_REMINDER_HOUR=20 \
  TASK_REMINDER_MINUTE=0 \
  OVERDUE_REMINDER_HOUR=9 \
  DAILY_DIGEST_HOUR=11

Schedule times are in UTC:

Variable	Default	Description
TASK_REMINDER_HOUR	20	Hour to send "task due soon" notifications (8 PM UTC)
TASK_REMINDER_MINUTE	0	Minute for task reminder
OVERDUE_REMINDER_HOUR	9	Hour to send overdue task alerts (9 AM UTC)
DAILY_DIGEST_HOUR	11	Hour to send daily summary (11 AM UTC)

2. Scale Worker Process

# Scale to 1 worker
dokku ps:scale honeydue-api worker=1

# Verify processes
dokku ps:report honeydue-api

3. Verify Worker is Running

# Check worker logs
dokku logs honeydue-api -p worker

# Should see:
# "Registered task reminder job"
# "Registered overdue reminder job"
# "Registered daily digest job"
# "Starting worker server..."

---

Maintenance Commands

View Logs

# Real-time logs
dokku logs honeydue-api -t

# Last 100 lines
dokku logs honeydue-api -n 100

# Worker logs
dokku logs honeydue-api -p worker

Database Operations

# Connect to database
dokku postgres:connect honeydue-db

# Export database backup
dokku postgres:export honeydue-db > backup.sql

# Import database backup
dokku postgres:import honeydue-db < backup.sql

Run Migrations Manually

# Enter the app container
dokku enter honeydue-api web

# Migrations run automatically on startup, but if needed:
/app/api migrate

Restart App

dokku ps:restart honeydue-api

Scale App

# Scale web process
dokku ps:scale honeydue-api web=2 worker=1

# View current scale
dokku ps:report honeydue-api

Stop/Start App

dokku ps:stop honeydue-api
dokku ps:start honeydue-api

---

Troubleshooting

Check App Status

dokku ps:report honeydue-api
dokku logs honeydue-api -n 200

Common Issues

1. App Won't Start

# Check logs for errors
dokku logs honeydue-api -n 500

# Verify environment variables
dokku config:show honeydue-api

# Check if ports are available
dokku proxy:ports honeydue-api

2. Database Connection Failed

# Verify link
dokku postgres:linked honeydue-api honeydue-db

# Check database is running
dokku postgres:info honeydue-db

# Re-link if needed
dokku postgres:unlink honeydue-db honeydue-api
dokku postgres:link honeydue-db honeydue-api

3. Redis Connection Failed

# Verify link
dokku redis:linked honeydue-api honeydue-redis

# Check Redis is running
dokku redis:info honeydue-redis

4. Storage/Upload Issues

# Check mounts
dokku storage:report honeydue-api

# Verify permissions
ls -la /var/lib/dokku/data/storage/honeydue-api/

5. SSL Certificate Issues

# Check certificate status
dokku letsencrypt:list

# Renew manually
dokku letsencrypt:enable honeydue-api

View Resource Usage

# Docker stats for all containers
docker stats

# Disk usage
dokku storage:report honeydue-api
df -h

---

Quick Reference

Command	Description
dokku apps:list	List all apps
dokku logs honeydue-api -t	Tail logs
dokku ps:restart honeydue-api	Restart app
dokku config:show honeydue-api	Show env vars
dokku postgres:connect honeydue-db	Connect to DB
dokku enter honeydue-api web	Shell into container
dokku ps:scale honeydue-api web=2	Scale processes

---

Environment Variables Reference

Variable	Required	Description
SECRET_KEY	Yes	32+ character secret key
DEBUG	Yes	Set to false in production
ALLOWED_HOSTS	Yes	Comma-separated list of domains
DATABASE_URL	Auto	Set by postgres:link
REDIS_URL	Auto	Set by redis:link
EMAIL_HOST	Yes	SMTP server
EMAIL_PORT	Yes	SMTP port (587)
EMAIL_HOST_USER	Yes	SMTP username
EMAIL_HOST_PASSWORD	Yes	SMTP password
APPLE_CLIENT_ID	No	iOS Bundle ID
APPLE_TEAM_ID	No	Apple Developer Team ID
APNS_AUTH_KEY_PATH	No	Path to APNs .p8 key
APNS_AUTH_KEY_ID	No	APNs Key ID
APNS_TEAM_ID	No	APNs Team ID
APNS_TOPIC	No	APNs topic (bundle ID)
APNS_PRODUCTION	No	Use production APNs (default: false)
FCM_SERVER_KEY	No	Firebase Cloud Messaging server key