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 using VitePress and deployed at https://coolify.io/docs.

The source code of Coolify itself can be found at https://github.com/coollabsio/coolify for reference and testing purposes.

Branch Strategy

main: Production branch (deployed to https://coolify.io/docs/)
next: Development branch (deployed to https://next.coolify.io/docs/)
IMPORTANT: All pull requests MUST target the
```
next
```
branch, NEVER
```
main
```
Weekly release cycle merges
```
next
```
→
```
main
```

Technology Stack

VitePress 1.6.3 - Static site generator
Vue 3.5.13 - Component framework
Tailwind CSS 3.2.4 - Utility-first CSS
TypeScript - Type safety
Plausible - Privacy-focused analytics

Common Development Commands

Package Management

Preferred:
```
bun
```
(as per README)
Configured:
```
[email protected]
```
(as per package.json)
If using a different package manager, do NOT commit its lock files

Local Development

# Install dependencies
bun install

# Run development server (http://localhost:5173/docs/)
bun run dev

# Build for production
bun run build

# Preview production build
bun run preview

# Convert OpenAPI YAML to JSON (run after updating API spec)
bun run transform-openapi

Alternative: Task Runner

# Install Task: https://taskfile.dev/docs/installation
task --list          # List all available tasks
task dev             # Run dev server on port 2222 (all network interfaces)
task docker-build    # Build Docker container
task docker-deploy   # Run Docker container

Directory Structure

docs/
├── .vitepress/
│   ├── config.mts           # Main VitePress config
│   ├── plugins/             # Custom Vite plugins
│   └── theme/               # Custom theme & components
│       └── components/      # Vue components (including Services/List.vue)
├── public/                  # Static assets (images, openapi.yml)
│   └── images/              # Organized by section
├── get-started/             # Getting started guides
├── applications/            # Application deployment docs
├── services/                # One-click services docs
├── databases/               # Database docs
├── knowledge-base/          # How-tos and concepts
├── api-reference/           # Auto-generated API docs
└── troubleshoot/            # Troubleshooting guides

nginx/
└── redirects.conf           # URL redirect rules

Architecture

VitePress Configuration

Main config: docs/.vitepress/config.mts
Custom theme: docs/.vitepress/theme/index.ts
Theme extends VitePress default theme with custom components and layouts

Custom VitePress Plugins

vitepress-openapi: Auto-generates API documentation from OpenAPI spec
- Dynamically fetches from GitHub:
```
https://raw.githubusercontent.com/coollabsio/coolify/v4.x/openapi.json
```
- Falls back to local file: docs/.vitepress/theme/openapi.json
vitepress-plugin-coolbot: Custom plugin that converts markdown to plain text for AI/RAG systems
- Generates
```
llms-text.json
```
  file map during build
- Configured in docs/.vitepress/plugins/vitepress-plugin-coolbot.ts
vitepress-plugin-llms: Generates llms.txt for LLM consumption
vitepress-plugin-tabs: Enables tabbed content blocks
vitepress-plugin-group-icons: Adds icons to code group labels

Custom Vue Components

Located in docs/.vitepress/theme/components/:

ZoomableImage: MUST be used for all documentation images

<ZoomableImage src="/docs/images/path/to/image.webp" alt="Description" />

Callout: Important notes and warnings (types:
```
tip
```
,
```
warning
```
,
```
danger
```
,
```
info
```
,
```
success
```
)
TabBlock: Tabbed content sections
Card/CardGroup: Landing page card layouts
KorrektlySearch: Integrated search component

Content Guidelines

Images

Format: All images MUST be
```
.webp
```
format
Location: Store in
```
docs/public/images/[section]/
```
Paths: Always use absolute paths:
```
/docs/images/...
```
Usage: Always use the
```
ZoomableImage
```
component

Writing Style

Use clear, simple language (consider non-native English speakers)
Break instructions into small, numbered steps
Include screenshots for complex processes using
```
<ZoomableImage>
```
Structure with clear headings and bullet points

Markdown Features

Standard markdown + VitePress extensions
Frontmatter for page metadata (title and description required)

Custom containers:

:::success

:::warning

:::danger

:::info

:::tip

Tabs via
```
vitepress-plugin-tabs
```
Code groups with icons via
```
vitepress-plugin-group-icons
```

Service Documentation

Source of Truth

The authoritative source for service names is:

https://raw.githubusercontent.com/coollabsio/coolify/refs/heads/v4.x/templates/service-templates-latest.json

File Naming Rules

Service documentation files in

docs/services/

must follow these conventions:

Use kebab-case lowercase for all filenames
Match the base service name from
```
service-templates-latest.json
```
Do not use camelCase even if the JSON template uses it (e.g.,
```
denoKV
```
→
```
denokv.md
```
)
Include version numbers when specified (e.g.,
```
mautic5.md
```
not
```
mautic.md
```
)
Use compound names when specified (e.g.,
```
ente-photos.md
```
not
```
ente.md
```
)

Files to Update When Managing Services

When adding, renaming, or disabling services, update these locations:

File	Purpose
`docs/services/{name}.md`	The documentation file
`docs/.vitepress/theme/components/Services/List.vue`	Service listing (slug must match filename)
`nginx/redirects.conf`	URL redirects (when renaming/removing)
`docs/public/images/services/`	Service logo

Disabling Services

For deprecated or unavailable services:

Add
```
disabled: true
```
to the entry in
```
List.vue
```
Add a warning callout in the markdown:
```
::: warning SERVICE NOT AVAILABLE
```
Keep the file for SEO (users may find via search)

Environment Variables

Configuration via

.env

file (see .env.example):

VITE_SITE_URL=https://coolify.io/docs/       # Base URL for sitemap and meta
VITE_ANALYTICS_DOMAIN=coolify.io/docs        # Plausible analytics domain
VITE_KORREKTLY_BASE_URL=https://korrektly.com
VITE_KORREKTLY_API_TOKEN=kly_pub_...
VITE_KORREKTLY_DATASET_ID=uuid

Build & Deployment

Docker Build

Multi-stage Dockerfile:

Builder stage: Uses
```
oven/bun:1.1.44-alpine
```
to build VitePress site

Final stage: Uses

nginxinc/nginx-unprivileged:1.27.3-alpine-slim

to serve static files

Custom nginx config in nginx/nginx.conf and nginx/redirects.conf

CI/CD Workflows

Located in

.github/workflows/

staging-build.yml: Builds and deploys
```
next
```
branch to staging
production-build.yml: Builds and deploys
```
main
```
branch to production
update-korrektly.yml: Updates search index
enforce-pr-standards.yml: PR validation

Styling

Color Scheme

Primary Brand: Purple (
```
#7937f3
```
,
```
#7442d1
```
,
```
#B392F0
```
)
Tips: Brand purple
Warnings: Yellow
Danger/Errors: Red (
```
#ff4444
```
)
Success: Green (
```
#36d399
```
)
Info: Blue (
```
#42b8e7
```
)

Theme

Dark/light mode support (user-switchable, dark by default)
Custom styles in theme/style.css and theme/custom.css
Mobile-first responsive design

Troubleshooting

Issue	Solution
Images not displaying	Check path is absolute ( `/docs/images/...` )
Links broken after rename	Update all 3 locations (file, List.vue, redirects.conf)
Build fails	Check frontmatter YAML syntax
Service not showing	Verify slug in List.vue matches filename

Important Notes

The documentation may occasionally be outdated; refer to the Coolify source code for accuracy
OpenAPI spec is fetched from GitHub's v4.x branch at build time
Search is powered by local provider + Korrektly integration
VitePress plugins generate additional outputs: llms.txt, llms-text.json for AI consumption

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 using VitePress and deployed at https://coolify.io/docs.

The source code of Coolify itself can be found at https://github.com/coollabsio/coolify for reference and testing purposes.

Branch Strategy

main: Production branch (deployed to https://coolify.io/docs/)
next: Development branch (deployed to https://next.coolify.io/docs/)
IMPORTANT: All pull requests MUST target the
```
next
```
branch, NEVER
```
main
```
Weekly release cycle merges
```
next
```
→
```
main
```

Technology Stack

VitePress 1.6.3 - Static site generator
Vue 3.5.13 - Component framework
Tailwind CSS 3.2.4 - Utility-first CSS
TypeScript - Type safety
Plausible - Privacy-focused analytics

Common Development Commands

Package Management

Preferred:
```
bun
```
(as per README)
Configured:
```
[email protected]
```
(as per package.json)
If using a different package manager, do NOT commit its lock files

Local Development

# Install dependencies
bun install

# Run development server (http://localhost:5173/docs/)
bun run dev

# Build for production
bun run build

# Preview production build
bun run preview

# Convert OpenAPI YAML to JSON (run after updating API spec)
bun run transform-openapi

Alternative: Task Runner

# Install Task: https://taskfile.dev/docs/installation
task --list          # List all available tasks
task dev             # Run dev server on port 2222 (all network interfaces)
task docker-build    # Build Docker container
task docker-deploy   # Run Docker container

Directory Structure

docs/
├── .vitepress/
│   ├── config.mts           # Main VitePress config
│   ├── plugins/             # Custom Vite plugins
│   └── theme/               # Custom theme & components
│       └── components/      # Vue components (including Services/List.vue)
├── public/                  # Static assets (images, openapi.yml)
│   └── images/              # Organized by section
├── get-started/             # Getting started guides
├── applications/            # Application deployment docs
├── services/                # One-click services docs
├── databases/               # Database docs
├── knowledge-base/          # How-tos and concepts
├── api-reference/           # Auto-generated API docs
└── troubleshoot/            # Troubleshooting guides

nginx/
└── redirects.conf           # URL redirect rules

Architecture

VitePress Configuration

Main config: docs/.vitepress/config.mts
Custom theme: docs/.vitepress/theme/index.ts
Theme extends VitePress default theme with custom components and layouts

Custom VitePress Plugins

vitepress-openapi: Auto-generates API documentation from OpenAPI spec
- Dynamically fetches from GitHub:
```
https://raw.githubusercontent.com/coollabsio/coolify/v4.x/openapi.json
```
- Falls back to local file: docs/.vitepress/theme/openapi.json
vitepress-plugin-coolbot: Custom plugin that converts markdown to plain text for AI/RAG systems
- Generates
```
llms-text.json
```
  file map during build
- Configured in docs/.vitepress/plugins/vitepress-plugin-coolbot.ts
vitepress-plugin-llms: Generates llms.txt for LLM consumption
vitepress-plugin-tabs: Enables tabbed content blocks
vitepress-plugin-group-icons: Adds icons to code group labels

Custom Vue Components

Located in docs/.vitepress/theme/components/:

ZoomableImage: MUST be used for all documentation images

<ZoomableImage src="/docs/images/path/to/image.webp" alt="Description" />

Callout: Important notes and warnings (types:
```
tip
```
,
```
warning
```
,
```
danger
```
,
```
info
```
,
```
success
```
)
TabBlock: Tabbed content sections
Card/CardGroup: Landing page card layouts
KorrektlySearch: Integrated search component

Content Guidelines

Images

Format: All images MUST be
```
.webp
```
format
Location: Store in
```
docs/public/images/[section]/
```
Paths: Always use absolute paths:
```
/docs/images/...
```
Usage: Always use the
```
ZoomableImage
```
component

Writing Style

Use clear, simple language (consider non-native English speakers)
Break instructions into small, numbered steps
Include screenshots for complex processes using
```
<ZoomableImage>
```
Structure with clear headings and bullet points

Markdown Features

Standard markdown + VitePress extensions
Frontmatter for page metadata (title and description required)

Custom containers:

:::success

:::warning

:::danger

:::info

:::tip

Tabs via
```
vitepress-plugin-tabs
```
Code groups with icons via
```
vitepress-plugin-group-icons
```

Service Documentation

Source of Truth

The authoritative source for service names is:

https://raw.githubusercontent.com/coollabsio/coolify/refs/heads/v4.x/templates/service-templates-latest.json

File Naming Rules

Service documentation files in

docs/services/

must follow these conventions:

Use kebab-case lowercase for all filenames
Match the base service name from
```
service-templates-latest.json
```
Do not use camelCase even if the JSON template uses it (e.g.,
```
denoKV
```
→
```
denokv.md
```
)
Include version numbers when specified (e.g.,
```
mautic5.md
```
not
```
mautic.md
```
)
Use compound names when specified (e.g.,
```
ente-photos.md
```
not
```
ente.md
```
)

Files to Update When Managing Services

When adding, renaming, or disabling services, update these locations:

File	Purpose
`docs/services/{name}.md`	The documentation file
`docs/.vitepress/theme/components/Services/List.vue`	Service listing (slug must match filename)
`nginx/redirects.conf`	URL redirects (when renaming/removing)
`docs/public/images/services/`	Service logo

Disabling Services

For deprecated or unavailable services:

Add
```
disabled: true
```
to the entry in
```
List.vue
```
Add a warning callout in the markdown:
```
::: warning SERVICE NOT AVAILABLE
```
Keep the file for SEO (users may find via search)

Environment Variables

Configuration via

.env

file (see .env.example):

VITE_SITE_URL=https://coolify.io/docs/       # Base URL for sitemap and meta
VITE_ANALYTICS_DOMAIN=coolify.io/docs        # Plausible analytics domain
VITE_KORREKTLY_BASE_URL=https://korrektly.com
VITE_KORREKTLY_API_TOKEN=kly_pub_...
VITE_KORREKTLY_DATASET_ID=uuid

Build & Deployment

Docker Build

Multi-stage Dockerfile:

Builder stage: Uses
```
oven/bun:1.1.44-alpine
```
to build VitePress site

Final stage: Uses

nginxinc/nginx-unprivileged:1.27.3-alpine-slim

to serve static files

Custom nginx config in nginx/nginx.conf and nginx/redirects.conf

CI/CD Workflows

Located in

.github/workflows/

staging-build.yml: Builds and deploys
```
next
```
branch to staging
production-build.yml: Builds and deploys
```
main
```
branch to production
update-korrektly.yml: Updates search index
enforce-pr-standards.yml: PR validation

Styling

Color Scheme

Primary Brand: Purple (
```
#7937f3
```
,
```
#7442d1
```
,
```
#B392F0
```
)
Tips: Brand purple
Warnings: Yellow
Danger/Errors: Red (
```
#ff4444
```
)
Success: Green (
```
#36d399
```
)
Info: Blue (
```
#42b8e7
```
)

Theme

Dark/light mode support (user-switchable, dark by default)
Custom styles in theme/style.css and theme/custom.css
Mobile-first responsive design

Troubleshooting

Issue	Solution
Images not displaying	Check path is absolute ( `/docs/images/...` )
Links broken after rename	Update all 3 locations (file, List.vue, redirects.conf)
Build fails	Check frontmatter YAML syntax
Service not showing	Verify slug in List.vue matches filename

Important Notes

The documentation may occasionally be outdated; refer to the Coolify source code for accuracy
OpenAPI spec is fetched from GitHub's v4.x branch at build time
Search is powered by local provider + Korrektly integration
VitePress plugins generate additional outputs: llms.txt, llms-text.json for AI consumption

CLAUDE.md

Related Skills

Markdown Converter

Nano Banana Pro

1password