feat: add Coolify deployment support (docker-compose.yml + guide)

[pourmirzai]

Description

Adds first-class Coolify deployment support so the bundled Kaneo image can be deployed from the repository with minimal configuration:

• docker-compose.yml (repo root): a Coolify-optimized compose stack (PostgreSQL 16 + the bundled ghcr.io/usekaneo/kaneo image) using Coolify's Docker Compose build pack. It uses Coolify magic environment variables to auto-generate AUTH_SECRET and the database password, marks KANEO_CLIENT_URL as required, and avoids host port mappings / custom networks so Coolify's proxy handles all traffic. The compose location, env-var detection, and required-var syntax follow the official Coolify docs.
• apps/docs/core/deployments/coolify.mdx: step-by-step Coolify deployment guide (registered in docs.json under "Deployment & Operations").
• README.md: short "Deploy on Coolify" section linking to the guide.

Notes learned from a real Coolify deployment attempt:

• Coolify executes the compose file from the repo with docker compose up -d; the previous compose.yml uses env_file: .env and depends_on: condition: service_healthy, which fails on first boot because PostgreSQL is still initializing. The new file passes env vars through the environment: list (detected by Coolify's UI) and relies on Kaneo's built-in database retry instead of a hard healthcheck dependency.
• KANEO_API_URL must not be set to localhost/internal addresses in the Coolify UI — the container derives it from KANEO_CLIENT_URL at startup. The guide documents this to avoid broken browser API calls.

Related Issue(s)

No related issue.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test addition or update
• Other (please describe):

How Has This Been Tested?

• Unit tests
• Integration tests
• Manual testing — deployed the compose stack via Coolify's Docker Compose build pack (PostgreSQL boots, database migrates, /api/health passes, login page loads); verified YAML validity with PyYAML and docs.json with a JSON parser
• Other (please describe):

Screenshots (if applicable)

N/A

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Additional Notes

The deployment flow verified on a real Coolify instance:

1. New resource → Public Repository → https://github.com/usekaneo/kaneo
2. Build Pack: Docker Compose | Base Directory: / | Compose Location: docker-compose.yml
3. Assign domain to the kaneo service as https://<domain>:5173 (port routes to the container; visitors use the normal HTTPS URL)
4. Set KANEO_CLIENT_URL; leave KANEO_API_URL unset

AUTH_SECRET and the PostgreSQL password are auto-generated via Coolify magic variables and editable in the Coolify UI.

Summary by CodeRabbit

• New Features
  • Added a Coolify deployment option using a ready-to-use Docker Compose setup.
  • Added PostgreSQL support with persistent storage, health checks, automatic restarts, and generated credentials.
  • Added configurable domains, environment variables, optional integrations, and automatic API URL configuration.
• Documentation
  • Added setup, account configuration, email, SSO, upgrades, and troubleshooting guidance.
  • Added Coolify to the Deployment & Operations documentation section.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6abc626c-01a6-4ae8-b285-ab69b34b3ee5

📥 Commits

Reviewing files that changed from the base of the PR and between 0c470e4 and fe92bd6.

📒 Files selected for processing (2)

• apps/docs/core/deployments/coolify.mdx
• docker-compose.yml

🚧 Files skipped from review as they are similar to previous changes (2)

• apps/docs/core/deployments/coolify.mdx
• docker-compose.yml

---

📝 Walkthrough

Walkthrough

Adds a Coolify deployment guide, a Docker Compose stack with PostgreSQL and Kaneo services, persistent storage, health checks, environment configuration, and documentation navigation.

Changes

Coolify deployment

Layer / File(s)	Summary
Coolify Docker Compose stack docker-compose.yml	Defines environment variables, a persistent PostgreSQL service, a health-checked Kaneo service, database dependency handling, and optional integrations.
Coolify deployment documentation apps/docs/core/deployments/coolify.mdx, apps/docs/docs.json	Documents Coolify setup, domain and environment configuration, post-deployment steps, troubleshooting, and navigation placement.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to fe92b

This PR adds Coolify deployment configuration and documentation without any supplied concrete merge-blocking risk; it is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Coolify
  participant PostgreSQL
  participant Kaneo
  Coolify->>PostgreSQL: Start database service
  PostgreSQL-->>Coolify: Report healthy
  Coolify->>Kaneo: Start application service
  Kaneo->>PostgreSQL: Connect using configured database variables
  Kaneo-->>Coolify: Report HTTP health

Loading

Possibly related PRs

• usekaneo/kaneo#1210: Introduces the consolidated Kaneo image, derived environment variables, and health-check deployment model used by this Compose stack.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: adding Coolify deployment support through Docker Compose and documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Add Coolify deployment support (root docker-compose + docs guide)

📝 Documentation ⚙️ Configuration changes ✨ Enhancement 🕐 10-20 Minutes

AI Description

• Add Coolify-optimized docker-compose stack for Kaneo + PostgreSQL with required env vars.
• Publish step-by-step Coolify deployment guide and register it in docs navigation.
• Update README with a short “Deploy on Coolify” section linking to the guide.

Diagram

graph TD
  U{{"Operator"}} --> C{{"Coolify"}} --> F["docker-compose.yml"] --> K["Kaneo container"] --> P[("PostgreSQL")]
  P --> V[("postgres_data volume")]
  D["Coolify guide"] -.-> U

  subgraph Legend
    direction LR
    _ext{{"External/Platform"}} ~~~ _svc["Service/Container"] ~~~ _db[("State/Storage")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Ship a separate Coolify compose file (e.g., deploy/docker-compose.coolify.yml)

• ➕ Avoids ambiguity with any existing compose files used for local dev
• ➕ Makes it explicit that the file is Coolify-specific and may have different constraints
• ➖ Coolify setup becomes slightly less “copy/paste” (compose location differs from defaults)
• ➖ README/docs need to explain which compose file to pick in each scenario

2. Use a .env-based compose and rely on Coolify env-file support

• ➕ Keeps environment configuration in a familiar .env workflow
• ➕ Potentially reuses existing local-compose conventions
• ➖ Coolify’s UI env-var detection is worse with env_file
• ➖ Higher risk of first-boot issues if ordering/health dependencies are reintroduced

Recommendation: The PR’s approach (root-level, Coolify-optimized docker-compose plus explicit docs) is the best fit for Coolify’s Docker Compose build pack and its env-var UI detection. Keeping KANEO_CLIENT_URL required and documenting that KANEO_API_URL should be unset directly prevents a common misconfiguration. The main tradeoff is potential confusion with other compose setups; if the repo also has a separate dev compose, consider adding a short note in docs clarifying the intended use of each compose file.

Files changed (4) +107 / -1

Documentation (2) +47 / -0

README.mdAdd “Deploy on Coolify” quickstart section +4/-0

Add “Deploy on Coolify” quickstart section

• Adds a short Coolify deployment blurb pointing to the root docker-compose stack and the full docs guide. Highlights required KANEO_CLIENT_URL, auto-generated secrets, and advises leaving KANEO_API_URL unset.

README.md

coolify.mdxNew Coolify deployment guide +43/-0

New Coolify deployment guide

• Introduces step-by-step instructions for deploying Kaneo on Coolify using the bundled compose file. Documents required env vars, domain/port routing expectations, and why KANEO_API_URL should not be set to localhost/internal values.

apps/docs/core/deployments/coolify.mdx

Other (2) +60 / -1

docs.jsonRegister Coolify page under Deployment & Operations +5/-1

Register Coolify page under Deployment & Operations

• Adds the new Coolify deployment guide to the docs navigation under the existing deployment section so it appears in the rendered docs sidebar.

apps/docs/docs.json

docker-compose.ymlAdd Coolify-optimized compose stack for Kaneo + Postgres +55/-0

Add Coolify-optimized compose stack for Kaneo + Postgres

• Adds a root docker-compose.yml tailored for Coolify’s Docker Compose build pack, using Coolify magic variables for secrets and marking KANEO_CLIENT_URL as required. Defines postgres + kaneo services with health checks and avoids host port mappings/custom networks so Coolify’s proxy handles ingress.

docker-compose.yml

[coderabbitai]

🧹 Nitpick comments (1)

docker-compose.yml (1)

31-31: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Pin the Kaneo image to a tested build.

ghcr.io/usekaneo/kaneo:latest is mutable, and redeploys retain postgres_data. Use a tested digest or publish and use an immutable release tag. Define upgrades as intentional version changes.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docker-compose.yml` at line 31, Update the Kaneo service image reference from
the mutable latest tag to a tested immutable release tag or image digest. Keep
future upgrades limited to intentional changes of that pinned version.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docker-compose.yml`:
- Line 31: Update the Kaneo service image reference from the mutable latest tag
to a tested immutable release tag or image digest. Keep future upgrades limited
to intentional changes of that pinned version.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6460d7dd-47be-4c4b-b91b-cbcd170b74ae

📥 Commits

Reviewing files that changed from the base of the PR and between a458d87 and d82cf3d.

⛔ Files ignored due to path filters (1)

• README.md is excluded by !**/*.md

📒 Files selected for processing (3)

• apps/docs/core/deployments/coolify.mdx
• apps/docs/docs.json
• docker-compose.yml

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Unpinned Kaneo image ✓ Resolved 🐞 Bug ☼ Reliability

Description

The new Coolify docker-compose.yml deploys ghcr.io/usekaneo/kaneo:latest, so a redeploy can pull
a different Kaneo build without any config/code change. Since the API runs DB migrations during
startup, an unintentional upgrade can also run new migrations and potentially break rollbacks or
cause startup failures.

Code

docker-compose.yml[31]

+    image: ghcr.io/usekaneo/kaneo:latest

Evidence

The compose file explicitly uses the mutable :latest tag, and the API startup path runs database
migrations and exits on migration failure, making unintended upgrades riskier than a typical
stateless redeploy.

docker-compose.yml[30-41]
apps/api/src/index.ts[760-806]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docker-compose.yml` uses `ghcr.io/usekaneo/kaneo:latest`, which makes deployments non-deterministic and can unintentionally upgrade the application.
## Issue Context
The API performs database migrations as part of startup tasks, so pulling a newer image can also run newer migrations unexpectedly.
## Fix Focus Areas
- docker-compose.yml[31-41]
- apps/api/src/index.ts[760-806]
## Suggested fix
- Replace `ghcr.io/usekaneo/kaneo:latest` with a pinned, immutable reference:
- Prefer an image digest (`ghcr.io/usekaneo/kaneo@sha256:...`), or
- A specific version tag (e.g., `ghcr.io/usekaneo/kaneo:vX.Y.Z`).
- Optionally allow a controlled override via an explicit env var (e.g., `image: ghcr.io/usekaneo/kaneo:${KANEO_IMAGE_TAG:?}`), so Coolify users can upgrade intentionally.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can turn on the rule miner and Qodo learns your standards from review history

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[randoneering]

@pourmirzai thank you for the contribution! We love seeing new ways to deploy kaneo! I agree with qodo's review on pinning the version of kaneo.

[pourmirzai]

@randoneering Thanks! Done. I've pinned the image to v2.18.0 (with an optional KANEO_IMAGE_TAG override).