Coolify Production Deployment

Coolify is a self-hosted PaaS that simplifies Docker-based deployments. Quark Commerce is optimized for Coolify's docker-compose workflow.

Setup Steps

1. Create a New Resource

In Coolify, create a new resource of type Docker Compose. Point it to your Git repository containing the docker-compose.yml.

Shared server, several installations

For a new installation, set the resource's Docker Compose Location to /docker-compose.coolify.yml. That file runs the API in Production, keeps RabbitMQ and Qdrant private to the stack, publishes nothing on the host, and takes every installation-specific value from environment variables — so several installations can share one Coolify server and one repository without sharing any configuration.

PostgreSQL is external, typically a standalone database service on the same Coolify server. Give each installation its own database and its own role:

CREATE ROLE acme LOGIN PASSWORD '...';
CREATE DATABASE acme OWNER acme;
REVOKE CONNECT ON DATABASE acme FROM PUBLIC;

The file attaches the API and the embedding worker to Coolify's shared coolify network, so the database's internal hostname works as-is. Leave Connect To Predefined Network off: it would expose the stack's private services on the shared network under short names (rabbitmq) that other stacks may use too. You fill in three variables — the stack refuses to start until they are set:

Variable	Notes
DATABASE_CONNECTION_STRING	Host=...;Port=5432;Database=...;Username=...;Password=...
API_PUBLIC_URL	Public API origin without a trailing slash, e.g. https://api.yourdomain.com; media URLs derive from it
LICENSE_FILE_BASE64	See Licensing

LICENSE_PUBLIC_KEY_BASE64 is optional: without it the licence is verified against the public key bundled in the image.

Coolify generates and keeps the secrets itself (SERVICE_PASSWORD_RABBITMQ, SERVICE_PASSWORD_64_JWT, SERVICE_PASSWORD_ADMIN). The last one is the first-login password of the seeded administrator — read it from the resource's environment variables; a change is forced on first login.

In the environment list, rows marked Managed mirror the compose file and need no attention, and Preview rows only matter when preview deployments are enabled. Set the domain on the api service with the container port appended — https://api.yourdomain.com:80; without it Coolify reports "Port missing" and creates no route. With this file, skip step 3 below.

2. Configure Volumes

In the Coolify Storage tab, ensure these volumes are defined:

Volume	Mount Path	Purpose
api_media	/app/wwwroot/media	Media files (images, documents)

info

For docker-compose based apps in Coolify, volumes are read-only in the dashboard. They must be defined in the compose file itself. After modifying docker-compose.yml, reload the configuration in Coolify.

3. Set Environment Variables

In the Coolify Environment Variables tab:

# Database
ConnectionStrings__DefaultConnection=Host=your-db-host;Port=5432;Database=HeadlessEcommerce;Username=postgres;Password=your-secure-password

# RabbitMQ (use service name if in same compose)
RabbitMQ__Host=rabbitmq
RabbitMQ__Port=5672
RabbitMQ__Username=guest
RabbitMQ__Password=guest

# JWT — use a strong random key (min 32 chars)
Jwt__SecretKey=your-production-jwt-secret-minimum-32-characters

# Licensing
Licensing__PublicKeyBase64=your-base64-encoded-rsa-public-key
Licensing__LicenseFileBase64=your-base64-encoded-license-file

# Storage — must match your public domain
Storage__BaseUrl=https://quarkapi.yourdomain.com/media

# Payment Providers (optional)
Stripe__SecretKey=sk_live_...
Iyzico__ApiKey=...
Iyzico__SecretKey=...

# Notifications (optional)
# Configured via Backoffice Settings UI

4. Configure Domain & HTTPS

In Coolify's Settings tab:

• Set your custom domain (e.g., quarkapi.yourdomain.com)
• Enable HTTPS (Coolify handles Let's Encrypt automatically)

5. CORS Configuration

The API reads allowed origins from appsettings.Production.json. Ensure your storefront and backoffice domains are listed:

{
  "AllowedCorsOrigins": [
    "https://store.yourdomain.com",
    "https://admin.yourdomain.com"
  ]
}

Or set via environment variable:

AllowedCorsOrigins__0=https://store.yourdomain.com
AllowedCorsOrigins__1=https://admin.yourdomain.com

Deploying Frontends

Backoffice Panel

The Backoffice is a static Angular build (included with Quark Commerce). Deploy it as a separate Coolify resource:

1. Create a resource from the Backoffice repository with the Dockerfile build pack (port 80).
2. Set the API_URL environment variable to the API origin (e.g., https://quarkapi.yourdomain.com — the /api suffix is appended for you). The container writes it to assets/app-config.json at start, so the same image serves any installation; no per-installation build is needed.
3. Assign the Backoffice domain.

Storefront (Customer-Built)

The Storefront is not included — customers build their own using any tech stack (React, Vue, Angular, Next.js, mobile apps, etc.) against the Storefront API. Deployment depends on the chosen framework.

Monitoring

• Health check: GET /health — returns 200 OK if the API is operational
• Swagger: GET /swagger — API documentation (consider restricting in production)
• RabbitMQ Management: Port 15672 — monitor message queues and event delivery
• Outbox Monitor: Available in the Backoffice under Settings → Event System