**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`:

```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:

| Application | Managed By | Deployment |
|------------|-----------|------------|
| PostgreSQL | Coolify | Docker container |
| Redis | Coolify | Docker container |
| Main web app | Coolify | Git push → Coolify builds Docker image |
| Marketing site (static) | DeployHQ | Git push → build → SFTP to `/var/www/marketing/` |
| Legacy PHP admin | DeployHQ | Git push → SFTP to `/var/www/admin/` |
| API microservice | DeployHQ | Git push → build → PM2 reload |

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](https://www.deployhq.com/signup) — free for one project.

Questions? Contact [support@deployhq.com](mailto:support@deployhq.com) or on [Twitter/X](https://x.com/deployhq).