Coolify Deployment¶

Coolify is a self-hosted PaaS (Platform as a Service) that manages Docker deployments with automatic TLS certificates, reverse proxying, and a web UI. It's the recommended method for deploying Dreadnought on a cloud VPS.

Why Coolify? - Handles TLS certificates automatically via Let's Encrypt - Built-in reverse proxy (Traefik) - Data directory permissions are managed automatically - GUI for environment variables — no SSH needed for config changes - Built-in deployment logs and container management

Prerequisites¶

A VPS or server with Coolify installed
A domain name you control (e.g. yourdomain.com)
DNS for that domain managed by Cloudflare (or any other provider with A records pointed at your server)
A Cloudflare API token — see Cloudflare Setup

Architecture with Coolify¶

Internet
    │
    ▼
Coolify's Traefik  (manages TLS and routing)
    │
    ├── ddns.yourdomain.com          ──► web container (port 3000)
    │
    └── ddns-api.yourdomain.com      ──► api container (port 8000)

worker container (no domain, runs in background)

You'll need two subdomains: - One for the web dashboard (e.g. ddns.yourdomain.com) - One for the API (e.g. ddns-api.yourdomain.com)

Point both of these as A records to your VPS's IP address before deploying.

Step 1 — Create DNS Records for Your Subdomains¶

In your DNS provider (this can be Cloudflare too):

Type	Name	Value
A	ddns	your-vps-ip
A	ddns-api	your-vps-ip

Wait for DNS to propagate (usually a few minutes with Cloudflare's short TTL).

Step 2 — Create a New Resource in Coolify¶

Log in to your Coolify instance
Go to your Project (or create a new one)
Click New Resource
Select Docker Compose

Step 3 — Point to the Repository¶

Option A — Public GitHub repository (simplest): 1. Select GitHub as the source 2. Enter the repository URL: https://github.com/dreadnought-0/Dreadnought-DDNS 3. Branch: main

Option B — Deploy from a Git URL directly: 1. Select Git source type 2. Enter: https://github.com/dreadnought-0/Dreadnought-DDNS.git

Coolify will use the docker-compose.yml in the repository root.

Step 4 — Set Environment Variables¶

In the Coolify resource settings, navigate to the Environment Variables section.

Add each variable:

Variable	Value
`CF_API_TOKEN`	Your Cloudflare API token
`ADMIN_EMAIL`	Your login email
`ADMIN_PASSWORD`	A strong password
`SECRET_KEY`	Output of `openssl rand -hex 32`
`POLL_INTERVAL_SECONDS`	`300`
`IPV6_ENABLED`	`false`
`DISCORD_WEBHOOK_URL`	(leave blank or paste webhook URL)
`TZ`	Your timezone (e.g. `America/New_York`)
`NEXT_PUBLIC_API_URL`	`https://ddns-api.yourdomain.com` (your API domain)

Critical: NEXT_PUBLIC_API_URL must be set to the public HTTPS URL of the api service, not localhost. This tells the browser where to make API calls from the public internet.

Step 5 — Assign Domains to Services¶

In the Coolify resource settings:

Web service (web): - Click on the web service - Assign domain: ddns.yourdomain.com - Enable TLS (Let's Encrypt will handle the certificate) - Port: 3000

API service (api): - Click on the api service - Assign domain: ddns-api.yourdomain.com - Enable TLS - Port: 8000

Worker service (worker): - No domain needed — it runs in the background - No port exposure needed

Step 6 — Deploy¶

Click Deploy in Coolify. Coolify will: 1. Pull the repository 2. Build the Docker images 3. Start the containers 4. Obtain TLS certificates from Let's Encrypt 5. Configure Traefik routing

Build time: 2–5 minutes on a typical VPS.

Watch the deployment log in Coolify's interface.

Step 7 — Verify¶

Once deployed, open:

https://ddns.yourdomain.com

You should see the Dreadnought login page. Log in with your ADMIN_EMAIL and ADMIN_PASSWORD.

Test the API directly:

https://ddns-api.yourdomain.com/health

Expected response: {"status": "ok"}

Step 8 — First Use¶

See First Use for adding your first domain and DNS record.

Data Persistence in Coolify¶

Coolify manages Docker volumes. Your data (ddns.db) is stored in a Docker-managed volume, not in a local folder. Coolify handles permissions automatically — you do not need to run setup.sh or chmod 777 ./data.

To find where data is stored: - In Coolify, go to your resource → Volumes - Or on the server: docker volume ls | grep dreadnought

To back up the database:

# SSH into your server
docker cp $(docker ps -qf name=dreadnought-api):/data/ddns.db ./ddns_backup.db

Updating in Coolify¶

In Coolify, go to your resource
Click Redeploy (or set up webhook-based auto-deploy from GitHub)
Coolify pulls the latest code, rebuilds, and restarts

Data is preserved across redeployments.

Configuring Auto-Deploy from GitHub¶

Coolify can automatically redeploy when you push to the repository:

In Coolify, go to your resource → Webhooks
Copy the webhook URL
In GitHub, go to your fork → Settings → Webhooks → Add webhook
Paste the Coolify webhook URL
Set content type to application/json
Select Just the push event

Now every push to main triggers a Coolify rebuild.

Troubleshooting Coolify Deployments¶

"NEXT_PUBLIC_API_URL still localhost"¶

The frontend was built before NEXT_PUBLIC_API_URL was set. This variable is baked in at build time.

Solution: Set the variable in Coolify, then force a full rebuild (not just restart): - In Coolify, click Rebuild (not just Redeploy)

TLS certificate not issued¶

Common reasons: - DNS hasn't propagated yet (wait 5–10 minutes and try again) - The domain isn't pointing to your VPS IP - Let's Encrypt rate limit (too many certificate requests for the same domain)

Check DNS:

dig ddns.yourdomain.com +short   # Should return your VPS IP

Container shows unhealthy in Coolify¶

Click on the container in Coolify and check the Logs tab.

Most common cause: missing environment variable (especially CF_API_TOKEN or SECRET_KEY).

Cannot connect to API after deployment¶

Check that: 1. NEXT_PUBLIC_API_URL is set to https://ddns-api.yourdomain.com 2. The api service has a domain assigned in Coolify and TLS is enabled 3. The domain actually resolves to your VPS: curl https://ddns-api.yourdomain.com/health