CapRover Management Skill

intent

deploy, configure, and manage applications on a self-hosted CapRover PaaS instance via REST API. use this skill when you need to create apps, deploy from docker images or build custom dockerfiles on the host, configure networking (ports for http and non-http services), mount persistent volumes, set environment variables, or read build and runtime logs. critical for multi-arch deployments where native image builds are required (e.g., arm64 hosts).

inputs

CapRover Instance

• CAPROVER_HOST: fully qualified domain (e.g., https://captain.example.com). must be accessible over https. self-signed certificates are common and supported.
• CAPROVER_PASSWORD: admin password for /api/v2/login endpoint.

Network & Auth

• network access to the captain domain on port 443 (https)
• ssl verification can be disabled for self-signed certs (see procedure step 1)
• auth token expires after some time (check CapRover docs for ttl); refresh token required for long-running jobs

App Deployment

• docker image name (e.g., nginx:latest) or tar.gz file containing captain-definition and Dockerfile
• if deploying from tar: root must contain captain-definition file with schema version and dockerfile path
• if using volumes: volume name (caprover auto-prefixes with captain--)

External Connections

• docker registry (docker hub, private registry, etc.) if pulling pre-built images; no explicit auth setup needed unless private (then use caprover ui to add registry creds)
• local filesystem access if preparing tar.gz files for custom builds

procedure

step 1: authenticate and get token

input: caprover host, admin password

import urllib.request, json, ssl

ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE  # self-signed cert is common on caprover

BASE = "https://<captain-domain>"  # e.g., https://captain.example.com

def api(path, data=None, token=None, timeout=60):
    body = json.dumps(data).encode() if data else None
    headers = {"Content-Type": "application/json"}
    if token:
        headers["x-captain-auth"] = token
    req = urllib.request.Request(f"{BASE}{path}", data=body, headers=headers)
    try:
        resp = urllib.request.urlopen(req, context=ctx, timeout=timeout)
        return json.loads(resp.read())
    except urllib.error.HTTPError as e:
        return {"error": e.code, "msg": e.reason, "body": e.read().decode()}

token = api("/api/v2/login", {"password": "<password>"})["data"]["token"]

output: auth token (string), valid for session

step 2: create app (register)

input: token, app name, persistent data flag

api("/api/v2/user/apps/appDefinitions/register",
    {"appName": "myapp", "hasPersistentData": False}, token)

set hasPersistentData: True if the app writes data that must survive restarts (database, file uploads, cache, etc.)

output: app registered in caprover, ready for deployment config

step 3a: deploy from pre-built docker image

input: token, app name, image name (docker hub or registry url)

# set the image
api("/api/v2/user/apps/appDefinitions/update",
    {"appName": "myapp", "imageName": "nginx:latest"}, token)

# trigger redeploy
api("/api/v2/user/apps/appData/myapp/redeploy",
    {"appName": "myapp", "gitHash": ""}, token)

output: caprover pulls image from registry and runs container, logs available after ~10-30 seconds

step 3b: deploy from custom dockerfile (build on host)

input: token, app name, tar.gz file with dockerfile and captain-definition

pack dockerfile, captain-definition, and any support files into tar.gz:

app.tar.gz root must contain:
  captain-definition (json file)
  Dockerfile
  [any other build context files]

captain-definition format:

{
  "schemaVersion": 2,
  "dockerfilePath": "./Dockerfile"
}

upload and build:

with open("app.tar.gz", "rb") as f:
    tar_data = f.read()

boundary = "----FormBoundaryCaprover"
body = (
    f"--{boundary}\r\n"
    f'Content-Disposition: form-data; name="sourceFile"; filename="app.tar.gz"\r\n'
    f"Content-Type: application/octet-stream\r\n\r\n"
).encode() + tar_data + f"\r\n--{boundary}--\r\n".encode()

req = urllib.request.Request(
    f"{BASE}/api/v2/user/apps/appData/myapp",
    data=body,
    headers={
        "Content-Type": f"multipart/form-data; boundary={boundary}",
        "x-captain-auth": token,
    },
)
resp = urllib.request.urlopen(req, context=ctx, timeout=180)

output: caprover builds image natively on host (critical for arm64 hosts), container deployed after ~30-120 seconds depending on dockerfile complexity

step 4: configure ports, env vars, volumes

input: token, app name, ports list, env vars list, volumes list, instance count

api("/api/v2/user/apps/appDefinitions/update", {
    "appName": "myapp",
    "envVars": [
        {"key": "MY_VAR", "value": "hello"},
        {"key": "DB_HOST", "value": "postgres.local"}
    ],
    "ports": [
        {"hostPort": 80, "containerPort": 8080},    # http
        {"hostPort": 25565, "containerPort": 7777}  # tcp (minecraft, game server, etc)
    ],
    "volumes": [
        {"containerPath": "/data", "volumeName": "myapp-data"},
        {"containerPath": "/var/lib/postgres", "volumeName": "myapp-postgres"}
    ],
    "instanceCount": 1,
}, token)

ports: any hostPort under 1024 requires root. non-http servers (game servers, databases, cache) just list them here without caprover trying to proxy them.

volumes: caprover auto-prefixes volume name with captain--. so volumeName: "myapp-data" becomes captain--myapp-data on the docker swarm side.

output: app config updated, redeploy triggered

step 5: advanced docker swarm settings (serviceUpdateOverride)

input: token, app name, swarm override json (mounts, dns, resource limits, etc.)

for settings not exposed in the standard api, use serviceUpdateOverride:

override = json.dumps({
    "TaskTemplate": {
        "ContainerSpec": {
            "Mounts": [{
                "Type": "volume",
                "Source": "captain--myapp-data",
                "Target": "/data"
            }],
            "DNSConfig": {
                "Nameservers": ["8.8.8.8", "8.8.4.4"]
            }
        },
        "Resources": {
            "Limits": {
                "MemoryBytes": 536870912  # 512 mb
            }
        }
    }
})

api("/api/v2/user/apps/appDefinitions/update",
    {"appName": "myapp", "serviceUpdateOverride": override}, token)

output: swarm task template updated, container restarts with new limits/mounts

step 6: read build logs

input: token, app name

r = api("/api/v2/user/apps/appData/myapp", token=token)
build_lines = r["data"]["logs"]["lines"]
print("\n".join(build_lines))

output: list of build log lines (stdout + stderr from dockerfile build)

step 7: read runtime logs

input: token, app name

r = api("/api/v2/user/apps/appData/myapp/logs", token=token)
raw_logs = r["data"]["logs"]
print(raw_logs)

output: raw string of container stdout/stderr

step 8: query node and cluster info

input: token

r = api("/api/v2/user/system/info", token=token)
nodes = r["data"]["nodes"]
print(f"nodes: {len(nodes)}, arch: {nodes[0].get('architecture', 'unknown')}")

output: dict with node count, architecture (x86_64 or aarch64), docker version, caprover version

decision points

if deploying pre-built image vs custom dockerfile

• use pre-built image (step 3a) if image exists in docker hub or private registry and matches your host architecture. faster, no build overhead.
• use custom dockerfile (step 3b) if you need custom dependencies, multi-stage builds, or native arm64 binary. required for arm64 hosts deploying amd64-only images.

if app needs persistent data

• set hasPersistentData: True at step 2 if app writes user data, database files, cache, logs, etc. that must survive container restarts.
• set False if app is stateless (nginx, api gateway, cache that can rebuild).

if port update fails with http 500

• caprover has a known bug where the ports field sometimes returns 500. workaround: set ports once at app creation (step 2) and do not update later. alternatively, use serviceUpdateOverride to manage ports