Prerequisites:

• A VPS with Coolify installed
• SSH access to the Coolify server
• A Git repository for your application
• A DeployHQ account

What is Coolify?

Coolify is an open-source, self-hosted PaaS — think Heroku or Vercel, but running on your own server. It manages Docker containers, SSL certificates, reverse proxy (Traefik), databases, and Git-based deployments through a web dashboard.

When to Combine Coolify with DeployHQ

Coolify has built-in Git deployment. So why add DeployHQ?

Use Coolify alone when: - Simple Git-push-to-deploy is sufficient - Your project fits Coolify's Dockerfile or Nixpacks build model - You're deploying a single application per repository

Add DeployHQ when you need: - Custom build pipelines beyond what Coolify's Nixpacks supports - Differential file deployment (only changed files transferred) - Multi-repository deployments to the same server - Deployment approval workflows before production pushes - Non-Docker applications deployed alongside Coolify-managed services - Multiple deployment targets from a single repository

Architecture

Your VPS
├── Coolify (manages)
│   ├── Traefik (reverse proxy, SSL)
│   ├── PostgreSQL container
│   ├── Redis container
│   └── App containers (Coolify-managed)
│
└── Non-Coolify apps (DeployHQ-managed)
    ├── /var/www/static-site/      ← deployed by DeployHQ via SSH
    ├── /var/www/legacy-php-app/   ← deployed by DeployHQ via SFTP
    └── /var/www/api-service/      ← deployed by DeployHQ, managed by PM2

Option A: Deploy Alongside Coolify

Run DeployHQ-managed applications on the same server as Coolify, but outside Coolify's Docker management.

Setup

1. SSH into your Coolify server and create deployment directories: bash mkdir -p /var/www/my-app

2. Create a deployment user (avoid using root): ```bash useradd -m -s /bin/bash deployhq mkdir -p /home/deployhq/.ssh

   Add DeployHQ's public key to authorized_keys

3. In DeployHQ, add the server with SSH credentials pointing to /var/www/my-app/

4. Configure Traefik (Coolify's reverse proxy) to route traffic to your app.

Traefik Configuration

Add a file-based Traefik route for your non-Coolify app. Create /data/coolify/proxy/dynamic/my-app.yaml:

http:
  routers:
    my-app:
      rule: "Host(`myapp.example.com`)"
      service: my-app
      tls:
        certResolver: letsencrypt

  services:
    my-app:
      loadBalancer:
        servers:
          - url: "http://localhost:3000"

For static sites served by Nginx on the same server: yaml http: services: static-site: loadBalancer: servers: - url: "http://localhost:8080"

Run a lightweight Nginx instance for static sites: ```bash

Install Nginx directly (not via Docker)

apt install nginx ```

PM2 for Node.js Apps

For Node.js applications alongside Coolify: bash npm install -g pm2 pm2 start ecosystem.config.cjs --env production pm2 save && pm2 startup

DeployHQ post-deployment command: bash cd /var/www/my-app && npm ci --omit=dev && pm2 reload my-app

Option B: Deploy to Coolify-Managed Paths

If you want DeployHQ to update files inside a Coolify-managed Docker container:

1. Identify the Docker volume mount for your app in Coolify's dashboard
2. Deploy to the host path that maps to the container volume
3. The container sees the updated files immediately

Caution: This approach bypasses Coolify's build and deployment process. Only use it for specific cases like updating static assets or configuration files.

Hybrid Workflow Example

A practical setup combining both tools:

Traefik routes traffic to each service based on hostname or path.

Troubleshooting

Docker Permission Issues

The deployhq user needs access to write to deployment directories: bash chown -R deployhq:deployhq /var/www/my-app

Don't give the deploy user Docker socket access unless necessary — it's a security risk.

Traefik Routing Conflicts

If both Coolify and your manually-configured Traefik routes claim the same domain, Coolify's dynamic configuration takes precedence. Use distinct hostnames for DeployHQ-managed apps.

Port Conflicts

Coolify assigns ports dynamically. Ensure your DeployHQ-managed apps use ports that don't conflict: bash ss -tulnp | grep LISTEN

Reserve specific ports (e.g., 3001-3010) for DeployHQ-managed applications.

SSH Access

Coolify may restrict SSH access. Ensure: - SSH is enabled on the server - The deployhq user has a valid shell (/bin/bash, not /usr/sbin/nologin) - The SSH key is in the correct authorized_keys file

Conclusion

Coolify handles infrastructure (databases, SSL, Docker) while DeployHQ handles application deployment with fine-grained control (build pipelines, differential transfers, multi-repo). Together, they give you a self-hosted platform that rivals commercial PaaS offerings.

Sign up for DeployHQ — free for one project.

Questions? Contact support@deployhq.com or on Twitter/X.