Coolify

Coolify is a self-hosted platform-as-a-service (like Heroku or Vercel) that can deploy Docker Compose projects from a Git repository. This guide covers deploying Cognova on Coolify.

Prerequisites

• A running Coolify instance (v4+)
• A server connected to Coolify with Docker installed

Setup Steps

1. Create a New Project

In the Coolify dashboard, create a new project and add a new resource.

2. Add a Docker Compose Resource

Select Docker Compose as the resource type and connect to the Cognova Git repository:

https://github.com/Patrity/cognova.git

Coolify will detect the docker-compose.yml at the repository root.

3. Configure Environment Variables

In the resource settings, add environment variables. See the Configuration reference for all available variables. At minimum, set:

VAULT_PATH=/vault
BETTER_AUTH_SECRET=<generate with: openssl rand -base64 32>
BETTER_AUTH_URL=https://your-domain.com
DATABASE_URL=postgres://postgres:postgres@db:5432/cognova
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=<your-password>
ADMIN_NAME=Admin

4. Enable the Database Profile

To use the bundled PostgreSQL container, add the Docker Compose profile. In Coolify's Docker Compose settings, ensure the local profile is active so the db service starts alongside the app.

Alternatively, create a separate PostgreSQL database resource in Coolify and point DATABASE_URL to it.

5. Configure Volumes

Ensure Coolify persists the named volumes defined in the Compose file:

• postgres_data -- database storage
• claude_home -- Claude Code config and credentials

For the vault, either use the default bind mount or configure a persistent volume.

6. Set Up a Domain

In the resource networking settings, assign a domain and enable HTTPS. Coolify handles TLS certificates automatically via Let's Encrypt.

7. Deploy

Click Deploy. Coolify will:

1. Clone the repository
2. Build the Docker image
3. Start the Compose services
4. Run the health check (GET /api/health)

Post-Deployment

Claude Code Authentication

After the container is running:

1. Open the Cognova web UI at your configured domain
2. Log in with your admin credentials
3. Open the built-in terminal
4. Run claude auth to authenticate Claude Code

Updates

To update, push changes to the connected Git repository (or point to a new tag) and redeploy from the Coolify dashboard. Database migrations run automatically on startup.

Troubleshooting

Build fails with out-of-memory error: The Dockerfile sets NODE_OPTIONS=--max-old-space-size=4096. If your Coolify server has less than 4 GB RAM, increase swap or use a larger instance.

Auth callbacks fail: Verify BETTER_AUTH_URL matches the exact URL shown in your browser, including protocol (https://) and any port.

Database connection refused: If using the bundled db service, ensure the local profile is active. The app waits for the database health check before starting.