ssh root@your-server-ip

# Check all Coolify containers are running
docker ps | grep coolify

# Check Traefik (reverse proxy) is healthy
docker ps | grep traefik

# Verify Coolify API is responding
curl -I http://localhost:8000
# Should return 200

# For GitHub — add webhook via API:
curl -X POST https://api.github.com/repos/YOUR_ORG/YOUR_REPO/hooks \
  -H "Authorization: Bearer YOUR_GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "active": true,
    "events": ["push"],
    "config": {
      "url": "https://coolify.yourdomain.com/webhooks/source/github/events/manual?token=YOUR_COOLIFY_WEBHOOK_TOKEN",
      "content_type": "json",
      "insecure_ssl": "0"
    }
  }'

# Alternatively: in GitHub repo → Settings → Webhooks → Add webhook
# Paste the URL from Coolify's Webhooks tab
# Content type: application/json
# Events: Just the push event

# Recommended multi-environment setup in Coolify:

# Production app:
# Repository: github.com/yourorg/yourapp
# Branch: main
# Domain: app.yourdomain.com
# Environment: Production env vars

# Staging app:
# Repository: github.com/yourorg/yourapp
# Branch: staging
# Domain: staging.yourdomain.com
# Environment: Staging env vars (staging DB, test API keys)

# Preview app (optional — per PR):
# Coolify supports preview deployments natively
# Enable in app settings: "Enable Preview Deployments"
# Each PR gets its own subdomain: pr-42.yourdomain.com

# In your Dockerfile, reference build args safely:
FROM node:20-alpine AS builder

# Build arg — only available during build, not in final image
ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
RUN npm ci
RUN rm ~/.npmrc  # Remove before final layer

FROM node:20-alpine AS runtime
COPY --from=builder /app/dist ./dist
# Runtime env vars injected by Coolify at container start
CMD ["node", "dist/server.js"]

# In Coolify: Application → Build Arguments
# NPM_TOKEN = your-npm-token (marked as secret)

# Coolify provides two connection strings per database:

# Internal URL (use this when app is on same Coolify server):
# postgresql://user:pass@postgres-container-name:5432/dbname
# Faster, doesn't leave the Docker network, no firewall rules needed

# External URL (use for external tools, local dev):
# postgresql://user:pass@your-server-ip:EXPOSED_PORT/dbname
# Only available if "Publicly available" is enabled

# In your app's Environment Variables in Coolify:
# DATABASE_URL = postgresql://coolify:generatedpass@myapp-postgres-prod:5432/myapp

# Verify connectivity from inside the app container:
docker exec YOUR_APP_CONTAINER \
  sh -c 'pg_isready -h myapp-postgres-prod -U coolify'
# Should output: myapp-postgres-prod:5432 - accepting connections

# Coolify backup settings (configured in dashboard):
# S3 Endpoint: https://s3.yourdomain.com  (or s3.amazonaws.com for AWS)
# S3 Bucket: your-backup-bucket
# S3 Access Key: YOUR_ACCESS_KEY
# S3 Secret Key: YOUR_SECRET_KEY
# S3 Region: us-east-1  (or your region)
# Backup Schedule: 0 2 * * *  (daily at 2am)
# Retention: 30  (keep 30 backups)

# Test the backup manually:
# Database → Backups → Run Now

# Verify backup landed in S3:
aws s3 ls s3://your-backup-bucket/coolify/ --recursive | tail -5
# Or with mc if using MinIO:
mc ls minio/your-backup-bucket/coolify/

# On the REMOTE server — prepare it to accept Coolify management:
# 1. Install Docker (Coolify will do this if you let it)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 2. Generate an SSH key pair ON THE COOLIFY SERVER:
ssh-keygen -t ed25519 -C "coolify-server-key" -f ~/.ssh/coolify_remote
cat ~/.ssh/coolify_remote.pub
# Copy this public key

# 3. Add the public key to the remote server's authorized_keys:
ssh root@remote-server-ip
echo "PASTE_PUBLIC_KEY_HERE" >> ~/.ssh/authorized_keys

# 4. In Coolify dashboard:
# Servers → Add Server
# IP: remote-server-ip
# Port: 22
# User: root
# Private Key: paste contents of ~/.ssh/coolify_remote

# 5. Coolify validates connectivity and installs Docker if missing
# Click "Validate & Save" then "Install Docker" if prompted

# Option 1: Health check in Dockerfile (preferred — version-controlled)
FROM node:20-alpine

# Install curl for health check
RUN apk add --no-cache curl

COPY . .
RUN npm ci --production

EXPOSE 3000

# Health check: hit /health every 30s, timeout after 10s
# Unhealthy if it fails 3 times in a row
HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=40s \
  CMD curl -f http://localhost:3000/health || exit 1

CMD ["node", "server.js"]

# Option 2: Health check in Coolify Advanced settings:
# Health Check Command: curl -f http://localhost:3000/health
# Interval: 30
# Timeout: 10
# Retries: 3
# Start Period: 40

// health.js — add to your Express/Fastify/Hono app
app.get('/health', async (req, res) => {
  const checks = {};
  let healthy = true;

  // Check database connectivity
  try {
    await db.query('SELECT 1');
    checks.database = 'ok';
  } catch (err) {
    checks.database = 'error';
    healthy = false;
  }

  // Check Redis connectivity
  try {
    await redis.ping();
    checks.redis = 'ok';
  } catch (err) {
    checks.redis = 'error';
    healthy = false;
  }

  const status = healthy ? 200 : 503;
  res.status(status).json({
    status: healthy ? 'ok' : 'degraded',
    checks,
    timestamp: new Date().toISOString()
  });
});

# Resource limit guidelines by app type:

# Small web app / API (low traffic):
# CPU: 0.5 cores
# Memory: 256MB

# Medium web app / API (moderate traffic):
# CPU: 1.0 cores
# Memory: 512MB

# Node.js / Python app with background processing:
# CPU: 1.0-2.0 cores
# Memory: 1GB

# AI/ML workloads (e.g., Dify worker, n8n with complex flows):
# CPU: 2.0-4.0 cores
# Memory: 2-4GB

# Databases — let them use what they need but cap them:
# PostgreSQL: CPU 2.0, Memory 1-2GB
# Redis: CPU 0.5, Memory 512MB

# Monitor actual usage to tune:
docker stats --no-stream | sort -k4 -h
# Shows CPU and memory usage per container — sorted by memory

# In Coolify application Advanced settings:
# Rolling Update: Enabled
# Start Period: 40s  (time to wait before checking health)
# Health Check must be configured for this to work

# Verify zero-downtime is working:
# Run a continuous curl loop during a deploy:
while true; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://app.yourdomain.com/health)
  echo "$(date +%H:%M:%S) - $STATUS"
  sleep 1
done
# Should show 200 throughout the deploy, never going to 000 or 503

# Example scheduled tasks to configure in Coolify:

# Run database migrations after each deploy:
# Name: DB Migrations
# Command: node dist/migrate.js
# Schedule: (run after deploy, not on cron)

# Daily cache clear:
# Name: Clear Cache
# Command: node dist/scripts/clear-cache.js
# Schedule: 0 3 * * *

# Weekly report generation:
# Name: Weekly Report
# Command: python scripts/generate_report.py --send-email
# Schedule: 0 8 * * 1  (Monday 8am)

# Or run one-off commands manually via Coolify's terminal:
# Application → Execute Command
docker exec -it YOUR_APP_CONTAINER node -e "console.log(process.env.NODE_ENV)"

# View detailed build logs:
# Application → Deployments → [Failed deployment] → Logs

# Or from the server:
docker logs coolify --tail 50 | grep -i error

# Common build failures:

# 1. Out of disk space during build:
df -h /var/lib/docker
# Fix: prune unused Docker artifacts:
docker system prune -af --volumes
# Warning: this removes all stopped containers and unused images

# 2. Out of memory during build (npm install, webpack):
free -h
# Fix: add swap space:
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 3. Nixpacks wrong language detected:
# Force the builder in app settings:
# Build Pack: Dockerfile
# Then add a minimal Dockerfile

# 502 = Traefik can reach the container but the app isn't listening
# Most common cause: wrong internal port configured in Coolify

# Find what port the app is actually listening on:
docker exec YOUR_APP_CONTAINER sh -c 'ss -tlnp || netstat -tlnp'

# Or check the app logs for the bound port:
docker logs YOUR_APP_CONTAINER --tail 30 | grep -iE 'listen|port|started|running'

# Update the port in Coolify:
# Application → Configuration → Ports → Internal Port
# Set to match what your app actually binds to
# Save and redeploy

# Check Traefik routing is correct:
docker exec coolify-proxy traefik healthcheck
docker logs coolify-proxy --tail 20 | grep -i error

# Test webhook manually with curl:
curl -X POST "https://coolify.yourdomain.com/webhooks/source/github/events/manual?token=YOUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ref": "refs/heads/main", "repository": {"full_name": "org/repo"}}'

# Check GitHub webhook delivery history:
# GitHub → Repo → Settings → Webhooks → [webhook] → Recent Deliveries
# Look for failed deliveries and their response codes

# Common causes:
# 1. Coolify domain not accessible from GitHub's servers
#    Test: curl -I https://coolify.yourdomain.com from any external machine

# 2. Wrong branch — deployment branch in Coolify must match the pushed branch
#    Check: Application → Configuration → Git → Branch

# 3. Token mismatch — regenerate webhook token in Coolify and update GitHub

# Update via the dashboard (recommended):
# Settings → Update Coolify → Update

# Or via CLI on the server:
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
# The installer is idempotent — safely updates existing installs

# Verify update:
docker inspect coolify | jq -r '.[0].Config.Image'

# All your apps, databases, and configs are preserved
# Coolify data lives in Docker volumes, not the container
docker volume ls | grep coolify