mirror of
https://github.com/coollabsio/coolify-docs.git
synced 2026-06-19 07:35:55 +00:00
Andras Bacsai
a64450ae9d
Replace VitePress/Vue stack with Fumadocs MDX, TanStack Start, React 19, and Vite. Migrate all documentation content to MDX under content/docs/. Add full src/ app with React components, routing, search, and API page. Remove Korrektly integration from CI/CD workflows, Dockerfile, and env vars. Update build pipeline to output to .output/public instead of docs/.vitepress/dist.
137 lines
5.1 KiB
Markdown
137 lines
5.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
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](nginx/nginx.conf) and redirect rules live in [nginx/redirects.conf](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.
|