Coolify Security

Coolify Security

Covers secrets management, RBAC, network isolation, resource limits, and access control for Coolify v4 self-hosted.

Self-Hosted Responsibility: Coolify self-hosted means YOU own server security. Coolify manages application-layer orchestration, not OS-level hardening.

Secrets Management

Three Types of Secrets in Coolify

Decision Tree: Where to Put a Secret

START: When is this secret needed?
│
├─ Only at runtime (app needs it while running)?
│  └─► Runtime Environment Variable
│      Set "Build Variable" = OFF in Coolify
│
├─ Only at build time (npm install, Docker build)?
│  ├─ Is it acceptable if this value appears in image layers?
│  │  ├─ Yes → Build-time Environment Variable
│  │  └─ No  → Docker Build Secret
│  │          (requires Dockerfile with --mount=type=secret)
│  │
│  └─ None of the above → Docker Build Secret (safest)
│
├─ Needed at both build AND runtime?
│  └─► Two separate entries: one build-time, one runtime
│      Do NOT use build-time alone (baked into image)
│
└─ Shared across multiple apps?
   └─► Shared Environment Variable (project-level or team-level)
       Coolify supports shared variables that multiple resources reference

Docker Build Secrets Pattern

For secrets that must not appear in image layers:

In Coolify: Enable "Use Docker Build Secrets" checkbox on the environment variable. Coolify automatically:

1. Passes each build variable via --secret id=KEY,env=KEY instead of --build-arg
2. Prepends # syntax=docker/dockerfile:1 to the Dockerfile if missing
3. Auto-injects --mount=type=secret into every RUN instruction (no manual Dockerfile changes needed)
4. Generates COOLIFY_BUILD_SECRETS_HASH to maintain build cache integrity

No Dockerfile modification required — Coolify handles the BuildKit secret injection automatically. Coolify uses BuildKit by default, so this works without additional server configuration.

Manual Dockerfile approach (if you prefer explicit control):

# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
COPY . .
RUN npm run build

Shared Variables (project, environment, team, server scopes)

New in beta.471 (April 2026): Coolify expanded shared variables to four scopes with explicit interpolation syntax. Earlier versions only supported project-level shared variables.

Four scopes available:

Reference example:

DATABASE_URL={{environment.DATABASE_URL}}
STRIPE_KEY={{project.STRIPE_PUBLISHABLE_KEY}}
SLACK_WEBHOOK={{team.SLACK_DEPLOY_WEBHOOK}}

Rotation: Update the shared variable and redeploy affected applications. There is no automatic propagation — redeployment is required. Plan rotation around your deployment cadence.

Older Coolify versions: Only project-level shared variables exist; the team/environment/server scopes are unavailable. Verify coolify_version MCP tool returns ≥ beta.471 before relying on them.

RBAC (Role-Based Access Control)

Team Roles

Permission Scope

Coolify v4 RBAC operates at the team level:

• Each team has its own servers, projects, and resources
• Users can belong to multiple teams with different roles
• Resources (servers, apps, databases) belong to a team
• No per-app or per-server granular permissions within a team
• API tokens are team-scoped with permission levels: read-only, read:sensitive, * (full CRUD), or deploy (trigger deploy only)

Known RBAC Limitations

• No per-resource permissions (e.g., "admin can deploy app A but not app B") — planned for v4 stable or v5
• No custom roles (only Owner/Admin/Member)
• No SAML/LDAP/OIDC natively — only OAuth via GitHub, GitLab, Google, Azure, Bitbucket
• No audit log for who changed what (environment variables, settings) — Issue #2525
• Terminal access is all-or-nothing per server (cannot selectively disable for Members while keeping it for Admins)
• All env vars in Docker Compose projects are injected into ALL containers — Issue #7655 (deferred to v5)

Workaround for per-app isolation: Create separate teams for each project or security boundary. Each team has its own resources and RBAC.

Network Isolation

The coolify Docker Network

All Coolify-managed containers join the coolify Docker network (bridge mode):

• All containers on the same server CAN reach each other by container name
• Traefik routes external HTTP/HTTPS traffic to containers
• Non-HTTP ports are not exposed externally by default

Isolating Apps from Each Other

To prevent two apps on the same server from communicating:

1. Separate Docker networks — Coolify does not natively support per-app networks. Workaround: use Docker Compose with custom networks.
2. Separate servers — The only guaranteed isolation is running on different servers.
3. Application-level firewall — Use iptables rules inside the container (complex, fragile).

Reality: Coolify's networking model assumes trust within a server. For true multi-tenant isolation, use separate servers or a container orchestrator with network policies (Kubernetes).

Exposing Ports

Security rule: Only expose ports that must be accessible externally. Default to internal-only.

UFW and Docker — The Known Conflict

The Problem

Docker modifies iptables directly, bypassing UFW rules. This means:

• UFW deny rules do NOT block Docker-published ports
• A database exposed on port 5432 is accessible to the internet even if UFW blocks 5432

The Fix

# Option 1: Disable Docker's iptables manipulation (affects ALL containers)
# /etc/docker/daemon.json
{
  "iptables": false
}
# Then restart Docker: systemctl restart docker
# WARNING: This breaks inter-container networking; requires manual iptables rules

# Option 2 (Recommended): Use ufw-docker utility
# https://github.com/chaifeng/ufw-docker
wget -O /usr/local/bin/ufw-docker https://github.com/chaifeng/ufw-docker/raw/master/ufw-docker
chmod +x /usr/local/bin/ufw-docker
ufw-docker install

# Allow specific access
ufw-docker allow <CONTAINER_NAME> 5432/tcp
ufw-docker allow <CONTAINER_NAME> 5432/tcp from 203.0.113.50

Best Practice

• Bind database ports to 127.0.0.1 only: 127.0.0.1:5432:5432 (not 0.0.0.0:5432:5432)
• Use SSH tunnels for remote database access instead of exposing ports
• Install ufw-docker to make UFW rules apply to Docker containers

Resource Limits

Setting Limits

In application or database settings:

OOM Behavior

When a container hits its memory limit:

1. Docker's OOM killer terminates the container process
2. Coolify's restart policy (unless-stopped) restarts the container
3. If the container OOMs repeatedly, it enters a restart loop
4. Check with: docker inspect <CONTAINER> | grep -i oom

Build Process Limits

Build processes do NOT have separate resource limits in Coolify. A runaway build can consume all server resources. Mitigation:

• Use a separate build server (see coolify-infrastructure)
• Set NODE_OPTIONS=--max-old-space-size=2048 for Node.js builds
• Monitor server resources during builds

Terminal Access and Auditing

Terminal Access

Coolify provides a web terminal in the UI for running commands inside containers:

• Admin and Developer roles can access the terminal
• Viewer role cannot access the terminal
• Terminal sessions are not logged or audited

Locking Down Terminal Access

• Assign the Viewer role to team members who should not have shell access
• Create separate teams with appropriate roles for different access levels
• There is no way to allow deployment but deny terminal access within the same role

Audit Logging

Current state: Coolify v4 has limited audit logging:

• Deployment history is logged (who triggered, when, status)
• Environment variable changes are NOT audited
• Terminal sessions are NOT logged
• API access is NOT logged per-request

Workaround: Enable server-level auditd for SSH and Docker command logging.

Anti-Patterns

Related Skills

• coolify-deploy — Build secrets configuration, environment variable setup
• coolify-databases — Database credential management, SSL configuration
• coolify-infrastructure — Server-level security, SSH configuration
• coolify-troubleshoot — Diagnosing OOM kills, network issues

Additional Resources

Reference Files

• references/hardening-checklist.md — Step-by-step server and Coolify hardening guide
• references/ufw-docker-guide.md — Complete UFW + Docker configuration with ufw-docker utility