CapRover Custom Buildpacks and Deployment

What is CapRover?

CapRover is a free, open-source PaaS that simplifies deploying web applications on your own server. It uses Docker and Nginx under the hood, providing automatic HTTPS, one-click app deployment, and a clean web interface. CapRover supports any language or framework through Docker and custom buildpacks.

Installation

# Install Docker
sudo apt update && sudo apt install -y docker.io
sudo systemctl enable --now docker

# Run CapRover
docker run -p 80:80 -p 443:443 -p 3000:3000 \
    -e ACCEPTED_TERMS=true \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /captain:/captain \
    caprover/caprover

# Install CLI and setup
npm install -g caprover
caprover serversetup

Custom Dockerfile Deployments

# captain-definition in project root:
{
    "schemaVersion": 2,
    "dockerfilePath": "./Dockerfile"
}

# Multi-stage Dockerfile example
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/server.js"]

# Deploy via CLI
caprover deploy -a my-app

Using Nixpacks Buildpacks

# captain-definition for Nixpacks auto-detection:
{
    "schemaVersion": 2,
    "nixpacksFileName": "./nixpacks.toml"
}

# nixpacks.toml for Python
[phases.setup]
nixPkgs = ["python311", "gcc"]
[phases.install]
cmds = ["pip install -r requirements.txt"]
[start]
cmd = "gunicorn app:app -b 0.0.0.0:$PORT"

One-Click Apps

CapRover has a marketplace of 100+ one-click apps including WordPress, PostgreSQL, MongoDB, Redis, Gitea, MinIO, and Grafana. Access via Dashboard > Apps > One-Click Apps, search, configure, and deploy.

Environment Variables and Persistent Storage

# Environment variables via Dashboard or CLI:
# App > App Configs > Environmental Variables

# Internal DNS for inter-app communication:
# srv-captain--app-name (resolves within Docker network)

# Persistent storage:
# App > App Configs > Persistent Directories
# Map container paths to host directories

Custom Domains and SSL

# 1. Add wildcard DNS: *.apps.yourdomain.com -> server IP
# 2. Add custom domain in app settings
# 3. Enable HTTPS (auto Let us Encrypt)
# 4. Force HTTPS redirect

Multi-Server Clustering

# CapRover supports Docker Swarm clustering
# On worker node:
docker swarm join --token YOUR_TOKEN CAPTAIN_IP:2377
# Add in Dashboard > Cluster
# Use placement constraints for specific apps

CI/CD Integration

# GitHub Actions example
name: Deploy to CapRover
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: caprover/deploy-from-github@v1
        with:
          server: https://captain.yourdomain.com
          app: my-app
          token: ${{ secrets.CAPROVER_TOKEN }}

Best Practices

• Use multi-stage Docker builds to minimize image size
• Set CPU/memory limits per app in CapRover settings
• Use internal DNS for inter-app communication
• Enable auto-deploy from Git for CI/CD
• Back up the /captain directory regularly
• Use persistent directories for data that must survive deployments