coolify-docs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

This is the official documentation repository for Coolify, an open-source self-hosting platform. The documentation is built with Fumadocs MDX, TanStack Start, React, Vite, and Bun, and is deployed at https://coolify.io/docs.

The Coolify application source can be found at https://github.com/coollabsio/coolify for reference and testing.

Branch Strategy

• main: Production branch, deployed to https://coolify.io/docs/
• next: Development branch, deployed to https://next.coolify.io/docs/
• Pull requests must target next, not main.
• Weekly release cycle merges next into main.

Technology Stack

• Fumadocs MDX/UI/Core - Documentation content, layout, search, and MDX pipeline
• TanStack Start / React 19 - Application runtime and prerendering
• Vite - Development server and production build
• Tailwind CSS 4 - Styling
• TypeScript - Type checking
• Bun - Package manager and script runner
• Plausible - Analytics

Common Commands

# Install dependencies
bun install

# Generate services and Fumadocs content
bun run generate:services
bun run generate:content

# Run development server
bun run dev

# Build static production output
bun run build

# Type-check the generated Fumadocs source and app
bun run types:check

# Preview production build
bun run preview

bun run dev, bun run build, and bun run types:check generate service data and Fumadocs content before starting their primary work.

Directory Structure

docs/                       # Author-edited source markdown and images
content/docs/               # Generated Fumadocs MDX content
src/                        # React/TanStack Start application
src/components/             # Shared MDX and UI components
src/generated/services.json # Generated service directory data
config/site.shared.ts       # Shared site metadata and docs base path
scripts/                    # Content, services, and postbuild scripts
public/                     # Public assets copied into the /docs base path
nginx/                      # Nginx config and redirects

docs/ remains the source of truth for documentation authoring. scripts/generate-fumadocs-content.mjs converts that content into content/docs/ for Fumadocs.

Content Guidelines

Images

• Store images in docs/public/images/[section]/.
• Use /docs/images/... paths in rendered output.
• Prefer the ZoomableImage MDX component for documentation screenshots.
• Keep meaningful alt text for screenshots and diagrams.

Markdown and MDX

• Frontmatter should include title and usually description.
• Existing VitePress containers are converted into Fumadocs callouts during content generation.
• Internal links should point to stable docs paths, for example /applications or /services/postgresql; generated output rewrites these under /docs.
• Avoid raw HTML unless it is already supported by the conversion script and MDX runtime.

Service Documentation

Service files live in docs/services/. The services directory data is generated by scripts/generate-service-list.mjs into src/generated/services.json.

When adding, renaming, or disabling services, update:

File	Purpose
docs/services/{name}.md	Service documentation
docs/public/images/services/	Service logo
nginx/redirects.conf	Redirects for renamed or removed paths

Service filenames should use kebab-case lowercase and match the service slug.

Environment Variables

VITE_SITE_URL=https://coolify.io/docs/
VITE_ANALYTICS_DOMAIN=coolify.io/docs
VITE_PLAUSIBLE_SCRIPT_URL=https://analytics.coollabs.io/js/script.tagged-events.js

Build and Deployment

The Dockerfile builds the Fumadocs/TanStack app with Bun and copies .output/public into the Nginx image. Nginx serves the static site from /usr/share/nginx/html, preserving /docs/... URLs.

Postbuild output includes:

• .output/public/docs-manifest.json
• .output/public/sitemap.xml
• .output/public/robots.txt
• .output/public/llms.txt
• .output/public/llms-full.txt
• .output/public/docs/images/
• .output/public/docs/brand/

Custom Nginx config lives in nginx/nginx.conf and redirect rules live in nginx/redirects.conf.

Troubleshooting

Issue	Solution
Build fails in MDX	Run bun run generate:content and inspect the generated file named in the error
Service not listed	Run bun run generate:services and verify the file exists in docs/services/
Image missing	Check source asset in docs/public/images/ and rendered /docs/images/... path
Broken renamed page	Update nginx/redirects.conf and any source markdown links

Important Notes

• The documentation can lag behind Coolify releases; check the Coolify source for behavior-sensitive claims.
• Generated folders are part of the build workflow. Regenerate them after changing source docs or service files.
• Keep redirects stable because existing docs URLs are indexed and linked externally.