Deployment Guide

This guide covers deploying to Coolify on Hetzner servers.

Prerequisites

Complete the pre-deployment checklist before deploying.

Server Setup (Hetzner)

1. Create server in Hetzner Cloud:

   • Ubuntu 22.04 or 24.04
   • SSH keys configured
   • Appropriate resources for your traffic

2. Configure firewall:

   Port	Source	Purpose
   80/443	Anywhere	HTTP/HTTPS
   22	Your IP	SSH

3. Run hardening script from coolifyservermanagement

4. Install Coolify proxy

Coolify Setup

Create Environment

Create separate environments for staging and production.

Add Database

1. Create PostgreSQL database in Coolify
2. For the name use the “project name” + “-db” for example “instance-studio-db”
3. Copy the connection string

Add Application

1. Select your Git repository
2. Set build type to docker
3. For the name use the “project name” for example “instance-studio”

Configuration:

Setting	Value
Domain	Your production domain
Build	docker

Environment Variables

Copy from .env.example and update:

PAYLOAD_SECRET=your-new-secure-secret
DATABASE_URI=postgres://coolify:password@host:5432/coolify
NEXT_PUBLIC_SERVER_URL=https://yourdomain.com
NEXT_PUBLIC_SITE_NAME="Your Project Name"

Tip

In Coolify, use $COOLIFY_URL for NEXT_PUBLIC_SERVER_URL.

Persistent Storage

Volume Mount

Name: next
Source Path: leave empty
Destination Path: /app/.next/cache

Directory Mount

Source Directory: add /media to the end
Destination Directory: /app/media

Set permissions:

chown -R 1001:1001 media
chmod -R 755 media

Health Check

The Dockerfile defines a built-in HEALTHCHECK that curls /healthcheck on the container’s own port every 30s (5s timeout, 10s start period, 3 retries), so Docker and Coolify report container health without extra configuration.

To also use it as Coolify’s application health check, enable it at /healthcheck.

Security Headers (HSTS) (OPTIONAL)

Coolify routes the app through Traefik. Define a security-headers middleware via container labels (Application → Configuration → Labels) to send HSTS and related hardening headers at the edge:

traefik.http.middlewares.security-headers.headers.stspreload=true
traefik.http.middlewares.security-headers.headers.stsSeconds=63072000
traefik.http.middlewares.security-headers.headers.stsIncludeSubdomains=true
traefik.http.middlewares.security-headers.headers.contentTypeNosniff=true
traefik.http.middlewares.security-headers.headers.frameDeny=true

Then append security-headers to the middlewares list on every existing router label — keep the middlewares already there (e.g. redirect-to-https):

traefik.http.routers.http-0-u135i35v2fora1wdylwegphv.middlewares=redirect-to-https,security-headers

Caution

stspreload commits the domain to HTTPS-only. Enable it only once HTTPS works on the apex domain and all subdomains.

DNS Setup

Type	Name	Value	TTL
A	@	SERVER_IP	Auto
CNAME	www	yourdomain.com	Auto

SSL certificates are automatically provisioned by Traefik.

Post-Deployment Checklist

• Site loads at https://yourdomain.com
• Admin panel works at /admin
• Uploaded media displays correctly
• Media persists between deployments
• Health check returns 200
• Headers verified with web-check.xyz (HSTS, CSP, cross-origin)

Updating

Push changes to Git. Coolify auto-deploys via webhook.

Rollback: Go to Coolify → deployments → click previous working version.

Troubleshooting

Issue	Solution
502 Bad Gateway	Check app logs, env vars, database
Uploads fail	Remove --entrypoints.https.http3 from proxy
Build fails	Check TypeScript errors in logs
SSL issues	Verify DNS points to server

Security

• SSH restricted to office IP
• Strong PAYLOAD_SECRET
• HSTS enabled
• Database backups configured