mirror/coolify-docs
1
0
Fork 0
mirror of https://github.com/coollabsio/coolify-docs.git synced 2026-06-19 07:35:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(platform): migrate docs from VitePress to Fumadocs + TanStack Start

Browse Source 
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.
This commit is contained in:
Andras Bacsai
2026-05-06 12:08:05 +02:00
parent 19d1f9d034
commit a64450ae9d
1419 changed files with 39091 additions and 796 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/production-build.yml
-6
View File
@@ -10,9 +10,6 @@ env:
IMAGE_NAME: coollabsio/coolify-docs
VITE_ANALYTICS_DOMAIN: coolify.io/docs
VITE_SITE_URL: https://coolify.io/docs/
VITE_KORREKTLY_API_TOKEN: ${{ secrets.VITE_KORREKTLY_API_TOKEN }}
VITE_KORREKTLY_BASE_URL: ${{ secrets.VITE_KORREKTLY_BASE_URL }}
VITE_KORREKTLY_DATASET_ID: ${{ secrets.VITE_KORREKTLY_DATASET_ID }}
jobs:
build-push:
@@ -53,9 +50,6 @@ jobs:
build-args: |
VITE_ANALYTICS_DOMAIN=${{ env.VITE_ANALYTICS_DOMAIN }}
VITE_SITE_URL=${{ env.VITE_SITE_URL }}
VITE_KORREKTLY_API_TOKEN=${{ env.VITE_KORREKTLY_API_TOKEN }}
VITE_KORREKTLY_BASE_URL=${{ env.VITE_KORREKTLY_BASE_URL }}
VITE_KORREKTLY_DATASET_ID=${{ env.VITE_KORREKTLY_DATASET_ID }}
push: true
tags: |
${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_NAME }}:latest-${{ matrix.arch }}
.github/workflows/staging-build.yml
-6
View File
@@ -10,9 +10,6 @@ env:
IMAGE_NAME: coollabsio/coolify-docs
VITE_ANALYTICS_DOMAIN: next.coolify.io/docs
VITE_SITE_URL: https://next.coolify.io/docs/
VITE_KORREKTLY_API_TOKEN: ${{ secrets.VITE_KORREKTLY_API_TOKEN }}
VITE_KORREKTLY_BASE_URL: ${{ secrets.VITE_KORREKTLY_BASE_URL }}
VITE_KORREKTLY_DATASET_ID: ${{ secrets.VITE_KORREKTLY_DATASET_ID }}
jobs:
build-push:
@@ -53,9 +50,6 @@ jobs:
build-args: |
VITE_ANALYTICS_DOMAIN=${{ env.VITE_ANALYTICS_DOMAIN }}
VITE_SITE_URL=${{ env.VITE_SITE_URL }}
VITE_KORREKTLY_API_TOKEN=${{ env.VITE_KORREKTLY_API_TOKEN }}
VITE_KORREKTLY_BASE_URL=${{ env.VITE_KORREKTLY_BASE_URL }}
VITE_KORREKTLY_DATASET_ID=${{ env.VITE_KORREKTLY_DATASET_ID }}
push: true
tags: |
${{ env.GITHUB_REGISTRY }}/${{ env.IMAGE_NAME }}:next-${{ matrix.arch }}
.github/workflows/update-korrektly.yml
-30
View File
@@ -1,30 +0,0 @@
name: Update Korrektly
concurrency:
group: ${{ github.workflow }}-${{ github.head_ref }}
cancel-in-progress: true
on:
push:
branches:
- v4.x
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v5
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: latest
- name: Update Korrektly Chunks
env:
KORREKTLY_BASE_URL: ${{ secrets.KORREKTLY_BASE_URL }}
KORREKTLY_API_TOKEN: ${{ secrets.KORREKTLY_API_TOKEN }}
KORREKTLY_DATASET_ID: ${{ secrets.KORREKTLY_DATASET_ID }}
NODE_OPTIONS: --max-old-space-size=8192
run: bunx @korrektly/vitepress --path . -r https://coolify.io -a docs/api-reference/api/operations
.gitignore
+4 -1
View File
@@ -9,6 +9,9 @@
.vite_opt_cache
.vscode
dist
.output
.source
.tanstack
cache
temp
examples-temp
@@ -21,4 +24,4 @@ TODOs.md
package-lock.json
ui-sample
ui-sample
CLAUDE.md
+70 -185
View File
@@ -4,248 +4,133 @@ 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.
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 source code of Coolify itself can be found at https://github.com/coollabsio/coolify for reference and testing purposes.
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/)
- **IMPORTANT**: All pull requests MUST target the `next` branch, NEVER `main`
- Weekly release cycle merges `next` → `main`
- **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
- **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
- **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 Development Commands
### Package Management
- **Preferred**: `bun` (as per README)
- **Configured**: `pnpm@10.6.3` (as per package.json)
- If using a different package manager, do NOT commit its lock files
### Local Development
## Common Commands
```bash
# Install dependencies
bun install
# Run development server (http://localhost:5173/docs/)
# Generate services and Fumadocs content
bun run generate:services
bun run generate:content
# Run development server
bun run dev
# Build for production
# 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
# Convert OpenAPI YAML to JSON (run after updating API spec)
bun run transform-openapi
```
### Alternative: Task Runner
```bash
# 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
```
`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/
├── .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
```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
```
## Architecture
### VitePress Configuration
- Main config: [docs/.vitepress/config.mts](docs/.vitepress/config.mts)
- Custom theme: [docs/.vitepress/theme/index.ts](docs/.vitepress/theme/index.ts)
- Theme extends VitePress default theme with custom components and layouts
### Custom VitePress Plugins
1. **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](docs/.vitepress/theme/openapi.json)
2. **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](docs/.vitepress/plugins/vitepress-plugin-coolbot.ts)
3. **vitepress-plugin-llms**: Generates llms.txt for LLM consumption
4. **vitepress-plugin-tabs**: Enables tabbed content blocks
5. **vitepress-plugin-group-icons**: Adds icons to code group labels
### Custom Vue Components
Located in [docs/.vitepress/theme/components/](docs/.vitepress/theme/components/):
- **ZoomableImage**: MUST be used for all documentation images
```vue
<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
`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
- **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
- 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.
### Writing Style
### Markdown and MDX
- 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`
### Links
- **Internal**: Use absolute paths `/services/wordpress`
- **External**: Full URLs with UTM parameter `?utm_source=coolify.io`
- Always include descriptive anchor text (not bare URLs)
- 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
### Source of Truth
Service files live in `docs/services/`. The services directory data is generated by `scripts/generate-service-list.mjs` into `src/generated/services.json`.
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:
1. **Use kebab-case lowercase** for all filenames
2. **Match the base service name** from `service-templates-latest.json`
3. **Do not use camelCase** even if the JSON template uses it (e.g., `denoKV` → `denokv.md`)
4. **Include version numbers** when specified (e.g., `mautic5.md` not `mautic.md`)
5. **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:
When adding, renaming, or disabling services, update:
| 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/services/{name}.md` | Service documentation |
| `docs/public/images/services/` | Service logo |
| `nginx/redirects.conf` | Redirects for renamed or removed paths |
### Disabling Services
For deprecated or unavailable services:
1. Add `disabled: true` to the entry in `List.vue`
2. Add a warning callout in the markdown: `::: warning SERVICE NOT AVAILABLE`
3. Keep the file for SEO (users may find via search)
Service filenames should use kebab-case lowercase and match the service slug.
## Environment Variables
Configuration via `.env` file (see [.env.example](.env.example)):
```bash
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
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 & Deployment
## Build and Deployment
### Docker Build
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.
Multi-stage Dockerfile:
1. **Builder stage**: Uses `oven/bun:1.1.44-alpine` to build VitePress site
2. **Final stage**: Uses `nginxinc/nginx-unprivileged:1.27.3-alpine-slim` to serve static files
Postbuild output includes:
Custom nginx config in [nginx/nginx.conf](nginx/nginx.conf) and [nginx/redirects.conf](nginx/redirects.conf)
- `.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/`
### 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](docs/.vitepress/theme/style.css) and [theme/custom.css](docs/.vitepress/theme/custom.css)
- Mobile-first responsive design
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 |
|-------|----------|
| 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 |
| 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 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
- 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.
Dockerfile
+7 -9
View File
@@ -3,14 +3,8 @@ FROM oven/bun:1.3.6-alpine AS builder
ARG VITE_ANALYTICS_DOMAIN=coolify.io/docs
ARG VITE_SITE_URL=https://coolify.io/docs/
ARG VITE_KORREKTLY_API_TOKEN
ARG VITE_KORREKTLY_BASE_URL
ARG VITE_KORREKTLY_DATASET_ID
ENV VITE_ANALYTICS_DOMAIN=${VITE_ANALYTICS_DOMAIN}
ENV VITE_SITE_URL=${VITE_SITE_URL}
ENV VITE_KORREKTLY_API_TOKEN=${VITE_KORREKTLY_API_TOKEN}
ENV VITE_KORREKTLY_BASE_URL=${VITE_KORREKTLY_BASE_URL}
ENV VITE_KORREKTLY_DATASET_ID=${VITE_KORREKTLY_DATASET_ID}
RUN apk add --no-cache nodejs npm
# Set working directory and copy necessary files
@@ -29,11 +23,16 @@ RUN --mount=type=cache,target=/root/.bun \
bun install
# Copy only necessary files for build
COPY config/ ./config/
COPY public/ ./public/
COPY src/ ./src/
COPY docs/ ./docs/
COPY nginx/ ./nginx/
COPY scripts/ ./scripts/
COPY env.d.ts .
COPY source.config.ts .
COPY tsconfig*.json ./
COPY vite.config.ts .
# Copy git history for lastUpdated timestamps
COPY .git/ ./.git/
@@ -41,8 +40,7 @@ COPY .git/ ./.git/
# Build with cache
RUN --mount=type=cache,target=/root/.bun \
--mount=type=cache,target=/root/.cache/bun \
--mount=type=cache,target=/app/docs/.vitepress/.cache \
--mount=type=cache,target=/app/docs/.vitepress/cache \
--mount=type=cache,target=/app/.source \
bun run build
# Stage 2: NGINX Unprivileged Setup (1.29.3-alpine-slim, ARM64)
@@ -50,7 +48,7 @@ FROM nginxinc/nginx-unprivileged:1.29.3-alpine-slim AS final
# Set working directory for NGINX and copy built files from the build stage
WORKDIR /usr/share/nginx/html
COPY --from=builder /app/docs/.vitepress/dist /usr/share/nginx/html/docs
COPY --from=builder /app/.output/public /usr/share/nginx/html
# Copy custom NGINX configuration
COPY nginx/nginx.conf /etc/nginx/nginx.conf
bun.lock
+631 -480
View File
File diff suppressed because it is too large Load Diff
config/site.shared.ts
+19
View File
@@ -0,0 +1,19 @@
export const siteDefinition = {
name: 'Coolify',
title: 'Coolify Docs',
description: 'Self hosting with superpowers: an open-source and self-hostable Heroku, Netlify, and Vercel alternative.',
docsBasePath: '/docs',
locale: 'en',
themeColor: '#000000',
keywords: ['Coolify', 'self hosting', 'documentation', 'deployment', 'Docker', 'PaaS'],
og: {
width: 1200,
height: 630,
background: '#000000',
card: '#101418',
accent: '#9333ea',
accentSoft: '#c084fc',
text: '#f8fafc',
muted: '#d8def0',
},
} as const;
content/docs/api-reference/authorization.mdx
+69
View File
@@ -0,0 +1,69 @@
---
title: Authorization
layout: doc
description: "Learn how to authorize API requests in Coolify with Bearer tokens, scoped permissions, and secure access control."
---
# Authorization
API request requires a `Bearer` token in `Authorization` header, which could be generated from the UI.
## Access
The API can be accessed through `http://<ip>:8000/api`.
With the exception of `/health` and `/feedback`, all routes are additionally prefixed with `/v1` resulting in the base route `http://<ip>:8000/api/v1`.
## Generate
1. Go to `Keys & Tokens` / `API tokens`.
2. Define a name for your token and click `Create New Token`.
<Callout type="success" title="Tip">
You will see the token once, so make sure to copy it and store it in a safe place.
</Callout>
## Scope
The token will only be able to access resources that are owned by the team that the token is scoped to.
```php
# Sample token
3|WaobqX9tJQshKPuQFHsyApxuOOggg4wOfvGc9xa233c376d7
```
## Permissions
<Callout type="warn" title="HEADS UP!">
Some API data won't get returned if the API token doesn't have correct permissions
</Callout>
Currently there are three types of permissions:
- read-only `(default)`
- read:sensitive
- view:sensitive
- `*` (all permissions)
### `read-only`
With this permission, you can only read data from the API, but you can't create, update, or delete any resources. Also you can't see sensitive data.
### `read:sensitive`
With this permission, you can only read data from the API and see sensitive information that is normally redacted. You cannot create, update, or delete any resources.
### `view:sensitive`
Without this permission, passwords, api keys, and other sensitive data will be redacted from the API response.
### `*`
Full access to all resources and sensitive data.
content/docs/api-reference/meta.json
+7
View File
@@ -0,0 +1,7 @@
{
"title": "API Reference",
"pages": [
"authorization",
"api"
]
}
content/docs/applications/build-packs/docker-compose.mdx
+244
View File
@@ -0,0 +1,244 @@
---
title: Docker Compose Build Packs
description: Deploy multi-container applications with Docker Compose using custom domains, magic environment variables, storage volumes, and service networking.
---
<ZoomImage src="/docs/images/builds/packs/compose/banner.webp" alt="Coolify banner" />
<br />
Docker Compose lets you deploy multiple Docker containers and configure them easily.
With the Docker Compose build pack, you can use your own Docker Compose file (i.e. `docker-compose.y[a]ml`) as the single source of truth, giving you full control over how your application is built and deployed on Coolify.
## How to use Docker Compose?
### 1. Create a New Resource in Coolify
On the Coolify dashboard, open your project and click the **Create New Resource** button.
<ZoomImage src="/docs/images/builds/packs/compose/1.webp" alt="Coolify dashboard screenshot" />
### 2. Choose Your Deployment Option
<ZoomImage src="/docs/images/builds/packs/compose/2.webp" alt="Coolify dashboard screenshot" />
**A.** If your Git repository is public, choose the **Public Repository** option.
**B.** If your repository is private, you can select **Github App** or **Deploy Key**. (These methods require extra configuration. You can check the guides on setting up a [Github App](/applications/ci-cd/github/setup-app) or [Deploy Key](/applications/ci-cd/github/deploy-key) if needed.)
### 3. Select Your Git Repository
If you are using a public repository, paste the URL of your GitHub repository when prompted. The steps are very similar for all other options.
<ZoomImage src="/docs/images/builds/packs/compose/3.webp" alt="Coolify dashboard screenshot" />
### 4. Choose the Build Pack
Coolify defaults to using Nixpacks. Click the Nixpacks option and select **Docker Compose** as your build pack from the dropdown menu.
<ZoomImage src="/docs/images/builds/packs/compose/4.webp" alt="Coolify dashboard screenshot" />
### 5. Configure the Build Pack
<ZoomImage src="/docs/images/builds/packs/compose/5.webp" alt="Coolify dashboard screenshot" />
- **Branch:** Coolify will automatically detect the branch in your repository.
- **Base Directory:** Enter the directory that Coolify should use as the root. Use `/` if your files are at the root or specify a subfolder (like `/backend` for a monorepo).
- **Docker Compose Location:** Enter the path to your Docker Compose file, this path is combined with the Base Directory. Make sure the file extension matches exactly, if it doesn’t then Coolify won’t be able to load it.
Click on **Continue** button once you have set all the above settings to correct details.
## Making services available to the outside world
Read more about [Exposing Services to the Internet](/knowledge-base/docker/compose#exposing-services-to-the-internet) in the Knowledge Base.
## Advanced Configuration
### Using Environment and Shared Variables
Within Coolify you can configure these easily following the details found in the [Knowledge Base for Docker Compose](/knowledge-base/docker/compose#defining-environment-and-shared-variables).
### Storage
You can set up storage in your compose file, with some extra options for Coolify.
#### Create an Empty Directory
Define directories with host binding and inform Coolify to create them:
```yaml
services:
filebrowser:
image: filebrowser/filebrowser:latest
volumes:
- type: bind
source: ./srv
target: /srv
is_directory: true # Instructs Coolify to create the directory.
```
#### Create a File with Content
Specify a file with predefined content and even include a dynamic value from an environment variable:
```yaml
services:
filebrowser:
image: filebrowser/filebrowser:latest
environment:
- POSTGRES_PASSWORD=password
volumes:
- type: bind
source: ./srv/99-roles.sql
target: /docker-entrypoint-initdb.d/init-scripts/99-roles.sql
content: |
-- NOTE: Change these passwords for production!
\set pgpass `echo "$POSTGRES_PASSWORD"`
ALTER USER authenticator WITH PASSWORD :'pgpass';
ALTER USER pgbouncer WITH PASSWORD :'pgpass';
```
### Exclude from Healthchecks
If a service should not be part of the overall healthchecks (for example, a one-time migration service), set the `exclude_from_hc` option to `true`:
```yaml
services:
some-service:
exclude_from_hc: true
...
```
### Networking
When you deploy a Docker Compose stack, Coolify automatically creates an isolated bridge network (named after your resource UUID, e.g. `ewc08w0`) for all services in your stack. All services can communicate with each other using their service names as hostnames (e.g. `http://backend:8080`).
Coolify also connects its reverse proxy (Traefik) to this network so it can route external traffic to your services.
#### Do Not Define Custom Networks
<Callout type="error" title="WARNING">
If your `docker-compose.yml` defines custom networks, **remove them**. Defining custom networks causes intermittent outages where your app becomes unreachable over HTTPS.
</Callout>
For example, do **not** do this:
```yaml
services:
frontend:
networks:
- my-network
backend:
networks:
- my-network
networks:
my-network:
driver: bridge
```
When you define a custom network, your containers end up on **two networks** simultaneously — the Coolify-managed one and your custom one. Traefik is only on the Coolify-managed network, but non-deterministically picks which network IP to route to. If it picks the custom network IP, it cannot reach your container and requests will **hang indefinitely** or return **504 Gateway Timeout**.
This behavior is intermittent — it may work after one deploy and break after the next, depending on which IP Traefik selects. See [#4483](https://github.com/coollabsio/coolify/issues/4483), [#6215](https://github.com/coollabsio/coolify/issues/6215), [#6153](https://github.com/coollabsio/coolify/issues/6153).
**Instead**, simply remove the `networks:` sections entirely:
```yaml
services:
frontend:
...
backend:
...
```
Coolify's auto-created network already provides inter-service communication.
#### Connect to Predefined Networks
By default, each compose stack is deployed to a separate network named after your resource UUID. This setup allows each service in the stack to communicate with one another.
If you want to connect services across different stacks (for example, linking an application to a separate database), enable the **Connect to Predefined Network** option on your Service Stack page.
<ZoomImage src="/docs/images/builds/packs/compose/6.webp" />
Note that you must use the full name (like `postgres-<uuid>`) when referencing a service in another stack.
### Raw Docker Compose Deployment
For advanced users, Coolify offers a "Raw Compose Deployment" mode. This option lets you deploy your Docker Compose file directly without many of Coolify's additional configurations.
<ZoomImage src="/docs/images/builds/packs/compose/7.webp" />
<Callout type="error" title="CAUTION">
This mode is intended for advanced users familiar with Docker Compose.
</Callout>
### Labels
Coolify automatically adds these labels to your application (if not already set):
```yaml
labels:
- coolify.managed=true
- coolify.applicationId=5
- coolify.type=application
```
To enable Coolify's Proxy (Traefik), also include these labels:
```yaml
labels:
- traefik.enable=true
- "traefik.http.routers.<unique_router_name>.rule=Host(`shadowarcanist.com`) && PathPrefix(`/`)"
- traefik.http.routers.<unique_router_name>.entryPoints=http
```
### Build Arguments
When building images with Docker Compose, Coolify can inject build arguments into your build process. You can configure these settings in the **Advanced** menu of your application.
#### Inject Build Args to Dockerfile
Controls whether Coolify automatically injects build arguments during the build. Disable this in the Advanced menu if you want full control over build arguments in your Dockerfile.
- **Enabled (default):** Coolify automatically injects build arguments
- **Disabled:** You manage `ARG` statements yourself in the Dockerfile
#### Include Source Commit in Build
Controls whether the `SOURCE_COMMIT` variable (Git commit hash) is included in builds. Disabled by default to preserve Docker's build cache between commits. You can enable this in the Advanced menu if your build process requires the commit hash.
- **Disabled (default):** `SOURCE_COMMIT` is not included, improving cache utilization
- **Enabled:** `SOURCE_COMMIT` is included as a build argument
<Callout type="warn" title="Build Cache Optimization">
If build cache is not being preserved between deployments, ensure "Include Source Commit in Build" is disabled. The `SOURCE_COMMIT` value changes with every commit and will invalidate the cache.
</Callout>
## Known Issues and Solutions
<details>
<summary>1. Visiting the Application Domain Shows "No Available Server"</summary>
If you see a "No Available Server" error when visiting your website, it is likely due to the health check for your container.
Run `docker ps` on your server terminal to check if your container is unhealthy or still starting.
To resolve this, fix the issue causing the container to be unhealthy or remove the health checks.
</details>
content/docs/applications/build-packs/dockerfile.mdx
+136
View File
@@ -0,0 +1,136 @@
---
title: Dockerfile Build Pack
description: Build Docker images from your custom Dockerfile with Coolify supporting Git repositories, environment variables, and pre/post-deployment commands.
---
<ZoomImage src="/docs/images/builds/packs/dockerfile/banner.webp" alt="Coolify banner" />
<br />
Dockerfile includes step-by-step instructions to build a Docker image that Coolify uses to deploy your application or website.
The Dockerfile build pack allows you to use your own Dockerfile to deploy your application, you have complete control over how your application is built and deployed on Coolify.
## How to use Dockerfile?
### 1. Create a New Resource in Coolify
On the Coolify dashboard, open your project and click the **Create New Resource** button.
<ZoomImage src="/docs/images/builds/packs/dockerfile/1.webp" alt="Coolify dashboard screenshot" />
### 2. Choose Your Deployment Option
<ZoomImage src="/docs/images/builds/packs/dockerfile/2.webp" alt="Coolify dashboard screenshot" />
**A.** If your Git repository is public, choose the **Public Repository** option.
**B.** If your repository is private, you can select **Github App** or **Deploy Key**. (These methods require extra configuration. You can check the guides on setting up a [Github App](/applications/ci-cd/github/setup-app) or [Deploy Key](/applications/ci-cd/github/deploy-key) if needed.)
### 3. Select Your Git Repository
If you are using a public repository, paste the URL of your GitHub repository when prompted. The steps are very similar for all other options.
<ZoomImage src="/docs/images/builds/packs/dockerfile/3.webp" alt="Coolify dashboard screenshot" />
### 4. Choose the Build Pack
Coolify defaults to using Nixpacks. Click the Nixpacks option and select **Dockerfile** as your build pack from the dropdown menu.
<ZoomImage src="/docs/images/builds/packs/dockerfile/4.webp" alt="Coolify dashboard screenshot" />
### 5. Configure the Build Pack
<ZoomImage src="/docs/images/builds/packs/dockerfile/5.webp" alt="Coolify dashboard screenshot" />
- **Branch:** Coolify will automatically detect the branch in your repository.
- **Base Directory:** Enter the directory that Coolify should use as the root. Use `/` if your files are at the root or specify a subfolder (like `/backend` for a monorepo).
Click on **Continue** button once you have set all the above settings to correct details.
### 6. Configure Network Settings
After clicking **Continue**, update settings like your domain and environment variables (if needed).
The important option is the port where your application runs.
Coolify sets the default port to 3000, so if your application listens on a different port, update the port number on the network section.
<ZoomImage src="/docs/images/builds/packs/dockerfile/6.webp" alt="Coolify dashboard screenshot" />
## Advanced Configuration
### Environment Variables
You can manage your environment variables from the Coolify UI.
Click on the **Environment Variables** tab to add or update them.
<ZoomImage src="/docs/images/builds/packs/dockerfile/7.webp" alt="Coolify dashboard screenshot" />
### Pre/Post Deployment Commands
<ZoomImage src="/docs/images/builds/packs/dockerfile/8.webp" alt="Coolify dashboard screenshot" />
- **Pre-deployment:** Optionally, specify a script or command to execute in the existing container before deployment begins. This command is run with `sh -c`, so you do not need to add it manually.
- **Post-deployment:** Optionally, specify a script or command to execute in the newly built container after deployment completes. This command is also executed with `sh -c`.
### Build Arguments
Coolify automatically injects build arguments into your Dockerfile during the build process. These include environment variables you've configured and predefined system values like `SOURCE_COMMIT`.
You can configure these settings in the **Advanced** menu of your application.
#### Inject Build Args to Dockerfile
By default, Coolify injects Docker build arguments (`ARG` statements) into your Dockerfile. If you prefer to manage build arguments manually in your Dockerfile, you can disable this behavior in the Advanced menu.
- **Enabled (default):** Coolify automatically injects build arguments
- **Disabled:** You manage `ARG` statements yourself in the Dockerfile
#### Include Source Commit in Build
The `SOURCE_COMMIT` variable contains the Git commit hash of your source code. By default, this is excluded from the build to preserve Docker's build cache. You can enable this in the Advanced menu if needed.
- **Disabled (default):** `SOURCE_COMMIT` is not included, improving cache utilization
- **Enabled:** `SOURCE_COMMIT` is included as a build argument
<Callout type="warn" title="Build Cache Optimization">
Enabling "Include Source Commit in Build" will cause Docker's build cache to be invalidated on every commit, since the commit hash changes each time. Only enable this if your build process requires the commit hash.
</Callout>
### Node.js Multi-Core Scaling
A plain Node.js process only uses one CPU core. To make a Node.js (or Bun) app use every core on the host from a single Dockerfile build, see the [Node.js Multi-Core Scaling](/knowledge-base/nodejs-multi-core-scaling) guide.
## Known Issues and Solutions
<details>
<summary>1. Visiting the Application Domain Shows "No Available Server"</summary>
If you see a "No Available Server" error when visiting your website, it is likely due to the health check for your container.
Run `docker ps` on your server terminal to check if your container is unhealthy or still starting.
To resolve this, fix the issue causing the container to be unhealthy or remove the health checks.
</details>
<details>
<summary>2. App only works inside the Container</summary>
If your app works when you check it with a `curl localhost` inside the container but you receive a 404 or "No Available Server" error when accessing your domain, verify the port settings.
Make sure that the port in the network settings matches the port where your application is listening. Also, check the startup log to ensure the application is not only listening on localhost.
<ZoomImage src="/docs/images/builds/packs/dockerfile/9.webp" alt="Coolify dashboard screenshot" />
If needed, change it to listen on all interfaces (for example, `0.0.0.0`).
</details>
content/docs/applications/build-packs/index.mdx
+54
View File
@@ -0,0 +1,54 @@
---
title: Build Packs
description: Choose from Nixpacks, Static, Dockerfile, or Docker Compose build packs to create optimized Docker images for your application deployments.
---
<ZoomImage src="/docs/images/builds/packs/packs-banner.webp" alt="Coolify packs banner" />
<br />
Coolify deploys every application as a Docker container. This means your application runs in its own isolated container.
To run a container, you need a Docker image built from your source code.
Build packs helps to create this Docker image and manage the build and deployment process.
## Why Use Build Packs?
- **Simplifies the Build Process:** Some Build packs automatically create the Docker image needed for deployment, so you don’t have to spend time on learning how to write Dockerfiles on your own.
- **Flexibility for Different Projects:** Since every application is different, you can choose a build pack that suits your specific needs, whether you prefer an automated solution or a custom configuration.
## How Build Packs Work
Each build pack offers a different approach to building your Docker image:
- **Automated Dockerfile Creation:** Build packs like Nixpacks & Static Build Pack automatically generate a Dockerfile based on your codebase and builds the docker image.
- This allows you to deploy your application quickly without having to write the Dockerfile yourself.
- **Custom Dockerfile or Docker Compose:** Build packs like Dockerfile & Docker Compose let you use a Dockerfile or Docker Compose file that you have already have on your codebase.
- This gives you full control over how your Docker image is built and how multiple services work together.
## Choose the Right Build Pack
Coolify have four build packs to meet different requirements:
- **Nixpacks:** Good for quick and automated Docker image creation with minimal configuration.
- **Static Build Pack:** Perfect for static sites and simple applications that don’t need server-side processing.
- **Dockerfile:** Use your own Dockerfile, if you want full control over the docker image build process.
- **Docker Compose:** Perfect to Deploy complex, multi-service applications using your custom Docker Compose file.
## How to use a Build Pack
Each build pack has its own step-by-step guide to help you use them in Coolify. Click the links below to learn more about each build pack.
- [Static Build Pack](/applications/build-packs/static)
- [Nixpack](/applications/build-packs/nixpacks)
- [Dockerfile](/applications/build-packs/dockerfile)
- [Docker Compose](/applications/build-packs/docker-compose)
content/docs/applications/build-packs/meta.json
+9
View File
@@ -0,0 +1,9 @@
{
"title": "Build Packs",
"pages": [
"static",
"nixpacks",
"dockerfile",
"docker-compose"
]
}
content/docs/applications/build-packs/nixpacks/index.mdx
+171
View File
@@ -0,0 +1,171 @@
---
title: Nixpacks Build Pack
description: Build applications with Nixpacks automatic buildpack detecting your codebase, generating Dockerfiles, and deploying static sites or dynamic apps.
---
<ZoomImage src="/docs/images/builds/packs/nixpacks/banner.webp" alt="Coolify banner" />
<br />
Nixpacks is a open source build pack created by [Railway](https://railway.com?utm_source=coolify.io) and the source is available on [Github](https://github.com/railwayapp/nixpacks?utm_source=coolify.io). Coolify uses Nixpacks as one of the build pack.
Nixpacks checks your git repository (also called as "**source directory**" in nixpacks) and generates a Dockerfile, then it will build a docker image based on the Dockerfile it generated.
Nixpacks can deploy both fully static websites and non-static applications. Once your repository is set up, you can use Coolify to deploy your project with ease.
## How to use Nixpacks?
On Coolify you can only use Nixpacks on git-based deployments.
### 1. Create a New Resource in Coolify
On Coolify dashboard open your project and click the **Create New Resource** button.
<ZoomImage src="/docs/images/builds/packs/nixpacks/1.webp" alt="Coolify dashboard screenshot" />
### 2. Choose Your Deployment Option
<ZoomImage src="/docs/images/builds/packs/nixpacks/2.webp" alt="Coolify dashboard screenshot" />
**A.** If your Git repository is public, choose the **Public Repository** option.
**B.** If your repository is private, you can select **Github App** or **Deploy Key**. (These methods require extra configuration. You can check the guides on setting up a [Github App](/applications/ci-cd/github/setup-app) or [Deploy Key](/applications/ci-cd/github/deploy-key) if needed.)
### 3. Select Your Git Repository
If you are using a public repository, paste the URL of your GitHub repository when prompted. The steps are very similar for all other options.
<ZoomImage src="/docs/images/builds/packs/nixpacks/3.webp" alt="Coolify dashboard screenshot" />
### 4. Choose the Build Pack
Coolify will default to using Nixpacks. If it doesn’t, click to select Nixpacks as your build pack.
<ZoomImage src="/docs/images/builds/packs/nixpacks/4.webp" alt="Coolify dashboard screenshot" />
### 5. Configure Build Pack
We have different options like Base Directory, Publish Directory, and Ports that slightly change based on the application you deploy (static websites/applications). So, below we have two sections for the deployments possible with Nixpacks.
- [How to deploy Fully Static Websites](#how-to-deploy-fully-static-website)
- [How to deploy Non-Static Website/Applications](#how-to-deploy-non-static-website-applications)
## How to deploy Fully Static Website?
First, follow the previous section in this documentation: [How to use Nixpacks](#how-to-use-nixpacks). After that, proceed with the steps below.
<ZoomImage src="/docs/images/builds/packs/nixpacks/5.webp" alt="Coolify dashboard screenshot" />
1. **Branch:** Coolify will automatically detect the branch from your Repository.
2. **Base Directory:** Enter the directory Nixpacks should use as the root (for example, `/` if your files are at the root, or a subfolder if applicable).
- If you have a monorepo then you can enter the path of the directory you want to use as base directory (`/backend` for example)
3. **Is it a static Site?:** Click on this option to enable static mode.
4. **Port:** Once you enabled `Is it a static Site` the port will be automatically set to `80` and cannot be changed. (This is intentional)
5. **Publish Directory:** Once you enabled `Is it a static Site` this publish directory option will visible on the UI. You have to enter the output directory where your static files are generated (commonly `/dist`).
6. Click on **Continue** button once you have set all the above settings to correct details.
7. Choose a web server for your static website
<ZoomImage src="/docs/images/builds/packs/nixpacks/6.webp" alt="Coolify dashboard screenshot" />
- As of Coolify **v4.0.0-beta.404**, the only web server option available is [Nginx](https://nginx.org/en/?utm_source=coolify.io). So **Nginx** will be selected by default.
8. Click the **Deploy** button. The deployment process is usually quick (often less than a minute, depending on your server).
9. Customize Your Web Server Configuration `Optional`
<ZoomImage src="/docs/images/builds/packs/nixpacks/7.webp" alt="Coolify dashboard screenshot" />
- Coolify provides a default web server configuration that works for most cases.
- If you want to change it then click the **Generate** button to load the default settings and make any changes you need.
<Callout type="warn" title="HEADS UP!">
You have to click on the **Restart** button for the new configuration to take effect.
</Callout>
### How this works?
Nixpacks will build the website using your codebase and create a Docker image with a web server to serve them. This means your final Docker image has a web server ready to serve your HTML, CSS, and JavaScript files.
## How to deploy Non-Static Website/Applications?
First, follow the previous section in this documentation: [How to use Nixpacks](#how-to-use-nixpacks). After that, proceed with the steps below.
<ZoomImage src="/docs/images/builds/packs/nixpacks/8.webp" alt="Coolify dashboard screenshot" />
1. **Branch:** Coolify will automatically detect the branch from your Repository.
2. **Base Directory:** Enter the directory Nixpacks should use as the root (for example, `/` if your files are at the root, or a subfolder if applicable).
- If you have a monorepo then you can enter the path of the directory you want to use as base directory (`/backend` for example)
3. **Port:** Enter the port where your application listens for incoming requests.
4. **Is it a static Site?:** Leave this unchecked since you’re deploying a non-static application.
5. Click on **Continue** button once you have configured all the above options.
6. After clicking the **Continue** button, you can adjust settings like your domain and environment variables, then click the **Deploy** button to launch your application.
### How this works?
Nixpacks analyzes your codebase, builds a Docker image, and then starts a container using that image.
## Advanced Configuration
### Environment Variables
You can customize Nixpacks' behavior using environment variables. There are many variables available for different application frameworks, and you can find detailed information in their documentation: [Nixpacks Environment Variables](https://nixpacks.com/docs/configuration/environment?utm_source=coolify.io).
To add or modify environment variables in Coolify, simply click on the **Environment Variables** tab, where you can manage them easily.
<ZoomImage src="/docs/images/builds/packs/nixpacks/9.webp" alt="Coolify dashboard screenshot" />
---
### Commands
If needed, you can override the default install, build, and start commands. Simply scroll down to the build section on Coolify and input your custom commands.
<ZoomImage src="/docs/images/builds/packs/nixpacks/10.webp" alt="Coolify dashboard screenshot" />
<Callout type="warn" title="Note:">
You may need to include a `nixpacks.toml` file in your repository for these changes to take effect.
</Callout>
---
### Configuration file
Nixpacks supports specifying build configurations in a nixpacks.toml or nixpacks.json file. If one of these files is present in the root of your repository, it will be automatically used. For more details, refer to the [Nixpacks documentation](https://nixpacks.com/docs/configuration/file?utm_source=coolify.io).
---
### Node.js Multi-Core Scaling
A plain Node.js process only uses one CPU core. To make a Node.js (or Bun) app use every core on the host from a single Nixpacks build, see the [Node.js Multi-Core Scaling](/knowledge-base/nodejs-multi-core-scaling) guide.
## Known Issues
### Outdated Packages/Dependencies
Sometimes, Nixpacks may use older package versions than you need. This is especially common with Node.js, where you might need a specific minor or patch version.
For Node.js version pinning, see the dedicated [Node.js Versioning](/applications/build-packs/nixpacks/node-versioning) guide.
For other packages, you can update the `nixpkgs` archive version in your `nixpacks.toml` file. Learn more in the Nixpacks docs on [nixpkgs archive](https://nixpacks.com/docs/configuration/file#nixpkgs-archive?utm_source=coolify.io).
content/docs/applications/build-packs/nixpacks/meta.json
+5
View File
@@ -0,0 +1,5 @@
{
"pages": [
"node-versioning"
]
}
content/docs/applications/build-packs/nixpacks/node-versioning.mdx
+167
View File
@@ -0,0 +1,167 @@
---
title: Node.js Versioning
description: How to pin specific Node.js minor and patch versions in Nixpacks using nixpkgs archive overrides.
---
# Node.js Versioning in Nixpacks
Nixpacks only supports **major version** specification for Node.js. This page explains the limitation and provides a workaround for pinning specific minor or patch versions.
## Understanding the Limitation
According to the [Nixpacks Node provider documentation](https://nixpacks.com/docs/providers/node?utm_source=coolify.io):
> "Only a major version can be specified. For example, `18.x` or `20`."
When you specify a Node.js version via:
- `NIXPACKS_NODE_VERSION` environment variable
- `engines.node` in `package.json`
- `.nvmrc` or `.node-version` files
You can only control the **major version** (e.g., `20`, `22`). The specific minor and patch version (e.g., `22.13.1` vs `22.14.0`) is determined by the nixpkgs archive that Nixpacks uses internally.
## The Problem
You set `"node": ">=22"` in your `package.json` or `NIXPACKS_NODE_VERSION=22`, but your application needs Node 22.14.0 specifically. Nixpacks may instead provide 22.12.0 or another patch version from its default nixpkgs archive—causing runtime issues if your code depends on features from a newer patch.
## Workaround
To pin a specific minor/patch version, you can override the nixpkgs archive in your `nixpacks.toml` file. Create this file in your repository root:
```toml
[phases.setup]
nixpkgsArchive = '51ad838b03a05b1de6f9f2a0fffecee64a9788ee'
```
The `nixpkgsArchive` value is a commit SHA from the [NixOS/nixpkgs repository](https://github.com/NixOS/nixpkgs?utm_source=coolify.io). Each commit contains specific package versions, so by pinning a commit, you control the exact versions available.
## Finding the Right Archive Commit
To find a nixpkgs commit containing your required Node.js version:
1. Browse the [NixOS/nixpkgs repository](https://github.com/NixOS/nixpkgs?utm_source=coolify.io)
2. Search for files like `v20.nix`, `v22.nix`, or `v24.nix` (the Node.js version definition files)
3. Check the commit history for when your desired version was added
4. Copy the full commit SHA
**Some verified commits for Node.js:**
- `51ad838b03a05b1de6f9f2a0fffecee64a9788ee` → Node 22.13.1
- `bf744fe90419885eefced41b3e5ae442d732712d` → Node 22.x versions
- `ffeebf0acf3ae8b29f8c7049cd911b9636efd7e7` → Node 22.14.0 (unstable branch)
Learn more in the Nixpacks docs on [nixpkgs archive](https://nixpacks.com/docs/configuration/file#nixpkgs-archive?utm_source=coolify.io).
## Node.js Version Reference (SHA256 Hashes)
The following tables list Node.js versions and their SHA256 hashes from the nixpkgs history. These can help you verify you're getting the expected version when working with nixpkgs archives.
<Callout type="warn" title="USE AT YOUR OWN RISK">
These hashes are provided for reference only. They have not been verified for accuracy nor stability. Test thoroughly before using in production.
</Callout>
### Node.js 20.x
| Version | SHA256 |
| ------- | :------------------------------------------------------------------ |
| 20.0.0 | `sha256-dFDnV5Vo99HLOYGFz85HLaKDeyqjbFliCyLOS5d7XLU=` |
| 20.1.0 | `sha256-YA+eEYYJlYFLkSKxrFMY9q1WQnR4Te7ZjYqSBmSUNrU=` |
| 20.2.0 | `sha256-IlI98jFsNVaXFP8fabBTwuKGztRgiYQX3uRpRe/N+Yk=` |
| 20.3.0 | `sha256-G6jUlCPtOnVykGa7PqJkk+6ct9ZWjvlIWX/J70VPdDU=` |
| 20.3.1 | `sha256-EqgtswZpeVm0OJs1Gl+XhImGsTE/mQGw4LPYz08/mZE=` |
| 20.4.0 | `sha256-Cb0Lc8UmtjwCnV3f2IXRCWLnrYfJdblFg8H4zpDuU0g=` |
| 20.5.0 | `sha256-yzJ1aVje8cBOBpp5txtSymHtFZDBfyz6HuOvZB9y4Fg=` |
| 20.5.1 | `sha256-Q5xxqi84woYWV7+lOOmRkaVxJYBmy/1FSFhgScgTQZA=` |
| 20.6.0 | `sha256-nvtcunqPSxjTiw19N6mzDe1zOQyE44DPTeianTCn1vo=` |
| 20.6.1 | `sha256-Ouxeco2qOIAMNDsSkiHTSIBkolKaObtUZ7xVviJsais=` |
| 20.7.0 | `sha256-P8/c0FxGFRdIBZZZZnTfhbNc/OWX3QrjP1QW/E3xK+o=` |
| 20.8.0 | `sha256-QSvoR65t9hAQup2jzD5r5bZ6oALjVOkZ9Z7INgNxcEw=` |
| 20.8.1 | `sha256-95nGb2pjhruKwsdaN490DEVel/H+lkOT3TnJ+fbvvHA=` |
| 20.9.0 | `sha256-oj2WgQq/BFVCazSdR85TEPMwlbe8BXG5zFEPSBw6RRk=` |
| 20.10.0 | `sha256-MuslbuvYys1VdOZjHlS0K+fsjr4lrUeoymhUA7rRVTU=` |
| 20.11.0 | `sha256-MYB+vu6wScU/F2XkqVrtaUdqS2lt0QDLU5q2aNeVC0A=` |
| 20.11.1 | `sha256-d4E+2/P38W0tNdM1NEPe5OYdXuhNnjE4x1OKPAylIJ4=` |
| 20.12.0 | `sha256-duU0bOv9WBUo9pn3ZPTRpuh8uBi2lnCPI13ctiWg940=` |
| 20.12.1 | `sha256-aEDUkLpNHVFlXg++EgmVahXbQFUQ1+oWa62YqMnTek4=` |
| 20.12.2 | `sha256-18vMX7+zHpAB8/AVC77aWavl3XE3qqYnOVjNWc41ztc=` |
| 20.14.0 | `sha256-CGVQKPDYQ26IFj+RhgRNY10/Nqhe5Sjza9BbbF5Gwbs=` |
| 20.15.0 | `sha256-D0p6BRw12V65BejLKqQ8XUArExIDkI/mM+s8+gUO+Qc=` |
| 20.15.1 | `sha256-/dU6VynZNmkaKhFRBG+0iXchy4sPyir5V4I6m0D+DDQ=` |
| 20.16.0 | `cd6c8fc3ff2606aadbc7155db6f7e77247d2d0065ac18e2f7f049095584b8b46` |
| 20.17.0 | `9abf03ac23362c60387ebb633a516303637145cb3c177be3348b16880fd8b28c` |
| 20.18.0 | `7d9433e91fd88d82ba8de86e711ec41907638e227993d22e95126b02f6cd714a` |
| 20.18.1 | `91df43f8ab6c3f7be81522d73313dbdd5634bbca228ef0e6d9369fe0ab8cccd0` |
| 20.18.2 | `69bf81b70f3a95ae0763459f02860c282d7e3a47567c8afaf126cc778176a882` |
| 20.18.3 | `0674f16f3bc284c11724cd3f7c2a43f7c2c13d2eb7a872dd0db198f3d588c5f2` |
| 20.19.0 | `5ac2516fc905b6a0bc1a33e7302937eac664a820b887cc86bd48c035fba392d7` |
| 20.19.1 | `5587b23e907d0c7af2ea8a8deb33ec50010453b46dbb3df5987c5678eee5ed51` |
| 20.19.2 | `4a7ff611d5180f4e420204fa6f22f9f9deb2ac5e98619dd9a4de87edf5b03b6e` |
| 20.19.3 | `99be7b9d268d48b93be568a23240398ceacb0782dc7055b9972305c000b0e292` |
| 20.19.4 | `b87fd7106013d3906706913ffc63a4403715fbb272c4f83ff4338527353eec0f` |
| 20.19.5 | `230c899f4e2489c4b8d2232edd6cc02f384fb2397c2a246a22e415837ee5da51` |
| 20.19.6 | `2026f9ff52c286d7c7d99932b21be313d1736aea524c5aff1748d41ab0bd9a20` |
### Node.js 22.x
| Version | SHA256 |
| ------- | :------------------------------------------------------------------ |
| 22.0.0 | `sha256-IuKPv/MfaQc7gCTLQnReUQX4QEHzR1smC5fVoUEDnRo=` |
| 22.1.0 | `sha256-nX1fQNnb1iYMmbXklLX5vHVejw/6xw4SGtzl+0QvI8s=` |
| 22.2.0 | `sha256-iJkIqIKNFISRDX5lm2qlet6NUo/w45Dpp372WadihHQ=` |
| 22.3.0 | `0k0h4s9s2y0ms3g6xhynsqsrkl9hz001dmj6j0gpc5x5vk8mpf5z` |
| 22.4.0 | `sha256-KStDAITy8ykT3H2k6y+8iWklJ3Kp0b/ormxLSpjKOtM=` |
| 22.4.1 | `sha256-ZfyFf1qoJWqvyQCzRMARXJrq4loCVB/Vzg29Tf0cX7k=` |
| 22.5.1 | `924f381a32cf26b6bedbe95feedde348450f4fd321283d3bf3f7965aa45ce831` |
| 22.6.0 | `37259d618d5565ca55acc2585045c7e1c5b9965a3d4eb44c0a237fdae84b9d44` |
| 22.7.0 | `1e0b6f2f2ca4fb0b4644a11363169daf4b7c42f00e5a53d2c65a9fdc463e7d88` |
| 22.8.0 | `f130e82176d1ee0702d99afc1995d0061bf8ed357c38834a32a08c9ef74f1ac7` |
| 22.9.0 | `a55aeb368dee93432f610127cf94ce682aac07b93dcbbaadd856df122c9239df` |
| 22.10.0 | `3180710d3130ad9df01466abf010e408d41b374be54301d1480d10eca73558e0` |
| 22.11.0 | `bbf0297761d53aefda9d7855c57c7d2c272b83a7b5bad4fea9cb29006d8e1d35` |
| 22.12.0 | `fe1bc4be004dc12721ea2cb671b08a21de01c6976960ef8a1248798589679e16` |
| 22.13.1 | `cfce282119390f7e0c2220410924428e90dadcb2df1744c0c4a0e7baae387cc2` |
| 22.14.0 | `c609946bf793b55c7954c26582760808d54c16185d79cb2fb88065e52de21914` |
| 22.15.0 | `e7c4226d1d92f33ad854d6da4f7e519e77690b8e73f93496881f8c539174d9df` |
| 22.15.1 | `c19f0177d21c621746625e5f37590bd0d79a72043b77b53784cba5f145e7263e` |
| 22.16.0 | `720894f323e5c1ac24968eb2676660c90730d715cb7f090be71a668662a17c37` |
| 22.17.0 | `7a3ef2aedb905ea7926e5209157266e2376a5db619d9ac0cba3c967f6f5db4f9` |
| 22.17.1 | `327415fd76fcebb98133bf56e2d90e3ac048b038fac2676f03b6db91074575b9` |
| 22.18.0 | `120e0f74419097a9fafae1fd80b9de7791a587e6f1c48c22b193239ccd0f7084` |
| 22.19.0 | `0272acfce50ce9ad060288321b1092719a7f19966f81419835410c59c09daa46` |
| 22.20.0 | `ff7a6a6e8a1312af5875e40058351c4f890d28ab64c32f12b2cc199afa22002d` |
| 22.21.1 | `487d73fd4db00dc2420d659a8221b181a7937fbc5bc73f31c30b1680ad6ded6a` |
### Node.js 24.x
| Version | SHA256 |
| ----------- | :------------------------------------------------------------------ |
| 24.0.0-rc.2 | `729fca42bb7266031dd020f3935423ea8d4b4e2d119b34b608f1d079e5c1621a` |
| 24.0.0-rc.3 | `9bbca08fba05f075a20f734ea80b195a4a39218476b60b32db79e1d393fda20b` |
| 24.0.0 | `914f3f1b03f84a0994d7357f190ff13c038800c693b6c06da2290eb588c82761` |
| 24.0.1 | `70271026971808409a7ed6444360d5fe3ef4146c1ca53f2ca290c60d214be84e` |
| 24.0.2 | `1597075afc06e5c6145d0bfbd77e2072c2ec0ab71ac4950cf008b2641374cd71` |
| 24.1.0 | `c8171b2aeccb28c8c5347f273a25adae172fb2a65bc8c975bc22ec58949d0eaf` |
| 24.2.0 | `40143d43efbdeeb9537995f532126c494d63a31da332acb5022f76f00afc62ab` |
| 24.3.0 | `eb688ef8a63fda9ebc0b5f907609a46e26db6d9aceefc0832009a98371e992ed` |
| 24.4.0 | `42fa8079da25a926013cd89b9d3467d09110e4fbb0c439342ebe4dd6ecc26bbb` |
| 24.4.1 | `adb79ca0987486ed66136213da19ff17ef6724dcb340c320e010c9442101652f` |
| 24.5.0 | `f1ba96204724bd1c6de7758e08b3718ba0b45d87fb3bebd7e30097874ccc8130` |
| 24.6.0 | `8ad5c387b5d55d8f3b783b0f1b21bae03a3b3b10ac89a25d266cffa7b795e842` |
| 24.7.0 | `cf74a77753b629ffebd2e38fb153a21001b2b7a3c365c0ec7332b120b98c7251` |
| 24.8.0 | `1c03b362ebf4740d4758b9a3d3087e3de989f54823650ec80b47090ef414b2e0` |
| 24.9.0 | `f17bc4cb01f59098c34a288c1bb109a778867c14eeb0ebbd608d0617b1193bbf` |
| 24.10.0 | `f17e36cb2cc8c34a9215ba57b55ce791b102e293432ed47ad63cbaf15f78678f` |
| 24.11.0 | `cf9c906d46446471f955b1f2c6ace8a461501d82d27e1ae8595dcb3b0e2c312a` |
| 24.11.1 | `ea4da35f1c9ca376ec6837e1e30cee30d491847fe152a3f0378dc1156d954bbd` |
| 24.12.0 | `6d3e891a016b90f6c6a19ea5cbc9c90c57eef9198670ba93f04fa82af02574ae` |
### Node.js 25.x
| Version | SHA256 |
| ------- | :------------------------------------------------------------------ |
| 25.2.1 | `aa7c4ac1076dc299a8949b8d834263659b2408ec0e5bba484673a8ce0766c8b9` |
content/docs/applications/build-packs/static.mdx
+97
View File
@@ -0,0 +1,97 @@
---
title: Static Build Packs
description: Deploy static websites with Nginx web server using pre-built files from Git repositories, supporting Astro, Webstudio, and other static generators.
---
<ZoomImage src="/docs/images/builds/packs/static/banner.webp" alt="Coolify banner" />
<br />
Static Build Packs take the files from your project and create a Docker image with a web server to serve them. This means your final Docker image has a web server ready to display your HTML, CSS, and JavaScript files.
Static Build Packs only work if your project is already built (for example, with a static site generator like [Astro](https://astro.build/?utm_source=coolify.io) or [Webstudio](https://webstudio.is/?utm_source=coolify.io)). Once you have the built files, you can upload them to a Git repository and use Coolify to deploy your site.
## How to Use Static Build Pack
### 1. Prepare Your Static Files
First, build your site with your favorite static site generator. This process creates a folder with all the files your site needs (HTML, CSS, JavaScript, etc.).
Next, upload these static files to a Git repository. You can use [GitHub](https://github.com/?utm_source=coolify.io), [GitLab](https://about.gitlab.com/?utm_source=coolify.io), or any other Git service. For this guide, we will use [GitHub](https://github.com/?utm_source=coolify.io) as an example.
### 2. Create a New Resource in Coolify
On Coolify dashboard open your project and click the **Create New Resource** button.
<ZoomImage src="/docs/images/builds/packs/static/1.webp" alt="Coolify dashboard screenshot" />
### 3. Choose Your Deployment Option
<ZoomImage src="/docs/images/builds/packs/static/2.webp" alt="Coolify dashboard screenshot" />
**A.** If your Git repository is public, choose the **Public Repository** option.
**B.** If your repository is private, you can select **Github App** or **Deploy Key**. (These methods require extra configuration. You can check the guides on setting up a [Github App](/applications/ci-cd/github/setup-app) or [Deploy Key](/applications/ci-cd/github/deploy-key) if needed.)
### 4. Select Your Git Repository
If you are using a public repository, paste the URL of your GitHub repository when prompted. The steps are very similar for all options.
<ZoomImage src="/docs/images/builds/packs/static/3.webp" alt="Coolify dashboard screenshot" />
### 5. Choose the Build Pack
Coolify will default to using Nixpacks. Click on the Nixpack option, and then select **Static** from the dropdown menu.
<ZoomImage src="/docs/images/builds/packs/static/4.webp" alt="Coolify dashboard screenshot" />
This tells Coolify to build your image with a static web server.
### 6. Set the Base Directory
Enter the path where your static files are located:
<ZoomImage src="/docs/images/builds/packs/static/5.webp" alt="Coolify dashboard screenshot" />
- If your files are in the root of your repository, just type `/`.
- If they are in a subfolder, type the path to that folder (for example, `/out`).
After setting the base directory, click the **Continue** button.
### 7. Choose a Web Server
As of Coolify **v4.0.0-beta.402**, the only web server option available is [Nginx](https://nginx.org/en/?utm_source=coolify.io). So **Nginx** will be selected by default.
<ZoomImage src="/docs/images/builds/packs/static/6.webp" alt="Coolify dashboard screenshot" />
### 8. Enter Your Domain
Type the domain name where you want your site to be available.
<ZoomImage src="/docs/images/builds/packs/static/7.webp" alt="Coolify dashboard screenshot" />
If you have multiple domains, separate them with commas.
### 9. Deploy Your Site
Click the **Deploy** button. The deployment process is usually quick (often less than a minute, depending on your server).
<ZoomImage src="/docs/images/builds/packs/static/8.webp" alt="Coolify dashboard screenshot" />
Once the deployment is finished, visit your domain in a browser to see your live site.
### 10. Customize Your Web Server Configuration `Optional`
Coolify provides a default web server configuration that works for most cases.
If you want to change it then click the **Generate** button to load the default settings and make any changes you need.
<ZoomImage src="/docs/images/builds/packs/static/9.webp" alt="Coolify dashboard screenshot" />
<Callout type="warn" title="HEADS UP!">
You have to click on the **Restart** button for the new configuration to take effect.
</Callout>
content/docs/applications/ci-cd/bitbucket/integration.mdx
+96
View File
@@ -0,0 +1,96 @@
---
title: "Integration"
description: "Deploy Bitbucket repositories with Coolify using deploy keys, SSH authentication, and automated webhooks for commits and pull requests."
---
# Bitbucket Integration
This guide will show you how to use Bitbucket based repositories with Coolify.
## Public Repositories
You can use public repositories without any additional setup.
1. Select the `Public repository` option in the Coolify when you create a new resource.
2. Add your repository URL to the input field, for example: `https://bitbucket.com/coolify-test2/coolify-examples`
<Callout type="warn" title="Caution">
You can only use the https URL.
</Callout>
1. That's it! Coolify will automatically pull the latest version of your repository and deploy it.
## Private Repositories
Private repositories require a few more steps to setup.
1. Add a private key (aka `Deploy Keys`) to Coolify and to your Bitbucket repository in the `Repository Settings` / `Access Keys` menu.
<Callout type="warn" title="Caution">
- You can generate a new key pair with the following command:
```bash
ssh-keygen -t rsa -b 4096 -C "deploy_key"
```
- Or you can also use Coolify to generate a new key for you in the `Keys & Tokens` menu.
</Callout>
2. Create a new resource and select the `Private Repository (with deploy key)`
3. Add your repository URL to the input field, for example: `git@bitbucket.org:coolify-test2/coolify-examples.git`
<Callout type="warn" title="Caution">
You need to use the SSH URL, so the one that starts with `git@`.
</Callout>
4. That's it! Coolify will automatically pull the latest version of your repository and deploy it.
## Automatic commit deployments with webhooks (Optional)
You can add a custom webhook URL to your Bitbucket repository to trigger a new deployment when you push to your repository.
<Callout type="warn" title="Caution">
This can be set on either public or private repositories.
</Callout>
In your resource, there is a `Webhooks` menu. In the `Manual Git Webhooks` section, you can find the URL what you need to set in your Bitbucket repository.
1. Set a secret key in the `Bitbucket Webhook Secret` input field.
2. Go to your repository in Bitbucket and open the `Repository Settings` / `Webhooks` menu as `Repository hooks`.
3. Add the URL from Coolify to the `URL` input field and the secret token.
4. Select the `Push` option.
5. That's it! Now when you push to your repository, Bitbucket will send a webhook request to Coolify and it will trigger a new deployment.
## Merge request deployments with webhooks (Optional)
You can add a custom webhook URL to your Bitbucket repository to trigger a new deployment when you create a new merge request.
<Callout type="warn" title="Caution">
This can be set on either public or private repositories.
</Callout>
The process is the same as the previous one. In the `Repository Settings` / `Webhooks` menu, you need to select the following events in the `Pull Request` option:
- `Created`
- `Updated`
- `Merged`
- `Declined`
content/docs/applications/ci-cd/gitea/integration.mdx
+97
View File
@@ -0,0 +1,97 @@
---
title: "Integration"
description: "Deploy Gitea repositories with Coolify using deploy keys, SSH authentication, and automated webhooks for commits and pull requests."
---
# Gitea Integration
This guide will show you how to use Gitea based repositories with Coolify.
## Public Repositories
You can use public repositories without any additional setup.
1. Select the `Public repository` option in the Coolify when you create a new resource.
2. Add your repository URL to the input field, for example: `https://gitea.com/heyandras/coolify-examples`
<Callout type="warn" title="Caution">
You can only use the https URL.
</Callout>
1. That's it! Coolify will automatically pull the latest version of your repository and deploy it.
## Private Repositories
Private repositories require a few more steps to setup.
1. Add a private key (aka `Deploy Keys`) to Coolify and to your Gitea repository in the `Repository Settings` / `Access Keys` menu.
<Callout type="warn" title="Caution">
- You can generate a new key pair with the following command:
```bash
ssh-keygen -t rsa -b 4096 -C "deploy_key"
```
- Or you can also use Coolify to generate a new key for you in the `Keys & Tokens` menu.
</Callout>
2. Create a new resource and select the `Private Repository (with deploy key)`
3. Add your repository URL to the input field, for example: `git@gitea.com:heyandras/coolify-examples.git`
<Callout type="warn" title="Caution">
You need to use the SSH URL, so the one that starts with `git@`.
</Callout>
4. That's it! Coolify will automatically pull the latest version of your repository and deploy it.
## Automatic commit deployments with webhooks (Optional)
You can add a custom webhook URL to your Gitea repository to trigger a new deployment when you push to your repository.
<Callout type="warn" title="Caution">
This can be set on either public or private repositories.
</Callout>
In your resource, there is a `Webhooks` menu. In the `Manual Git Webhooks` section, you can find the URL what you need to set in your Gitea repository.
1. Set a secret key in the `Gitea Webhook Secret` input field.
2. Go to your repository in Gitea and open the `Repository Settings` / `Webhooks` menu as `Repository hooks`.
3. Add the URL from Coolify to the `URL` input field and the secret token.
4. Select the `Push` option.
5. That's it! Now when you push to your repository, Gitea will send a webhook request to Coolify and it will trigger a new deployment.
## Merge request deployments with webhooks (Optional)
You can add a custom webhook URL to your Gitea repository to trigger a new deployment when you create a new merge request.
<Callout type="warn" title="Caution">
This can be set on either public or private repositories.
</Callout>
The process is the same as the previous one. In the `Repository Settings` / `Webhooks` menu, you need to select the following events in the `Pull Request` option:
- `Created`
- `Updated`
- `Merged`
- `Declined`
content/docs/applications/ci-cd/github/actions.mdx
+161
View File
@@ -0,0 +1,161 @@
---
title: GitHub Actions
description: Deploy applications using GitHub Actions to build Docker images and trigger redeployments in Coolify.
---
# GitHub Actions
GitHub Actions allow you to build your application as a Docker image and deploy it to Coolify automatically.
GitHub Actions provide greater flexibility for deploying your app, as you can trigger the workflow on events like commits to specific branches or releases on GitHub. You can also integrate checks and tests into your CI/CD pipeline, ensuring that new versions are deployed to Coolify only after all validations pass.
## Process Overview
Set up GitHub Actions to build and publish a Docker image of your app to a container registry (e.g., GHCR or Docker Hub), then make an API call to Coolify to redeploy your app using the latest image pushed to the registry.
For reference, check out this [example repository](https://github.com/andrasbacsai/github-actions-with-coolify) and its [workflow file](https://github.com/andrasbacsai/github-actions-with-coolify/blob/main/.github/workflows/build.yaml).
<Callout type="info" title="Example Data">
The following data is used as an example in this guide. Please replace it with your actual data when following the steps:
- **Docker Image:** `shadowarcanist/tasklytics:latest`
- **Registry:** `ghcr.io`
- **Branch:** `main`
</Callout>
## 1. Choose the Right Deployment Type
<ZoomImage src="/docs/images/applications/ci-cd/github/actions/1.webp" />
With GitHub Actions, build your application as a Docker image on GitHub runners and push it to a container registry. Select a deployment type that supports prebuilt Docker images.
For Git-based applications, use Docker Compose as your build pack. In your compose file, pull the prebuilt image instead of building it:
```yaml
services:
web:
# OLD:
# build:
# context: .
# dockerfile: Dockerfile
# NEW:
image: ghcr.io/shadowarcanist/tasklytics:latest
ports:
- "8080:8080"
```
For Docker-based applications, use the image name like `ghcr.io/shadowarcanist/tasklytics:latest` so Docker pulls the prebuilt image.
## 2. Enable Coolify API
<ZoomImage src="/docs/images/applications/ci-cd/github/actions/2.webp" />
1. Go to the "Settings" page in Coolify.
2. Click on the "Configuration" tab.
3. Click on "Advanced".
4. Check the "API Access" option.
## 3. Create Coolify API Token
<ZoomImage src="/docs/images/applications/ci-cd/github/actions/3.webp" />
1. Go to the "Keys & Tokens" page in Coolify.
2. Click on the "API Tokens" tab.
3. Check the "Deploy" option under Token permissions.
4. Give your API token a name.
5. Click "Create" button.
6. Copy and save the generated API token somewhere safe (you'll need it later).
## 4. Get Coolify Webhook URL
<ZoomImage src="/docs/images/applications/ci-cd/github/actions/4.webp" />
1. Open your application's configuration page.
2. Go to the "Webhook" page.
3. Copy and save the "Deploy webhook" URL somewhere safe (you'll need it later).
## 5. Set Up Repository Secrets
<ZoomImage src="/docs/images/applications/ci-cd/github/actions/5.webp" />
1. Go to your GitHub repository settings.
2. Click "Actions" in the sidebar (under "Secrets and variables").
3. Click "New repository secret".
<ZoomImage src="/docs/images/applications/ci-cd/github/actions/6.webp" />
4. Enter `COOLIFY_WEBHOOK` as the name.
5. Enter the Coolify deploy webhook URL as the secret (from [step 4](#_4-get-coolify-webhook-url)).
6. Click "Add secret" button.
<ZoomImage src="/docs/images/applications/ci-cd/github/actions/7.webp" />
7. Click "New repository secret".
<ZoomImage src="/docs/images/applications/ci-cd/github/actions/8.webp" />
8. Enter `COOLIFY_TOKEN` as the name.
9. Enter the Coolify API token as the secret (from step 3).
10. Click "Add secret" button.
## 6. Set Up GitHub Workflow
1. Create a new workflow file in the `.github/workflows` directory of your repository (name it with a `.yml` or `.yaml` extension).
2. Use the following workflow content as a starting point:
```yaml
name: Build and Deploy
on:
push:
branches: ["main"] # Trigger on pushes to main branch
env:
REGISTRY: ghcr.io
IMAGE_NAME: "andrasbacsai/github-actions-with-coolify"
jobs:
build-and-deploy:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v3
- name: Login to registry
uses: docker/login-action@v2
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push image
uses: docker/build-push-action@v4
with:
context: .
file: Dockerfile
platforms: linux/amd64
push: true
tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
- name: Deploy to Coolify
run: |
curl --request GET '${{ secrets.COOLIFY_WEBHOOK }}' --header 'Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}'
```
This workflow builds the Docker image, pushes it to `ghcr.io` with the tag `latest`, and triggers a redeployment in Coolify via API.
<Callout type="warn" title="IMPORTANT">
The above workflow is just an example to show how the process works. Adjust it to fit your own CI/CD needs.
Make sure the **Deploy to Coolify** step comes after all checks and tests so it only runs when everything before it passes.
</Callout>
## 7. Authenticate with Container Registry
If pushing to a private registry, authenticate it on your server so it can pull the image.
Run one of these commands on your server's terminal (based on the registry):
- **Docker Hub**: `docker login`
- **GitHub Container Registry (GHCR)**: `docker login ghcr.io -u USERNAME --password-stdin`
For other registries, refer to their documentation.
That's it!
content/docs/applications/ci-cd/github/auto-deploy.mdx
+71
View File
@@ -0,0 +1,71 @@
---
title: GitHub Auto Deploy
description: Automatically deploy applications from GitHub repositories in Coolify using GitHub Apps, Actions, or webhooks.
---
# GitHub Auto Deploy
Coolify can automatically deploy new versions of your application whenever you push changes to your GitHub repository.
There are three methods to set up automatic deployments on Coolify:
- [GitHub App](#github-app)
- [GitHub Actions](#github-actions)
- [Webhooks](#webhooks)
## GitHub App
We have a dedicated guide for setting up a GitHub App, which you can follow here: [/github/setup-app](/applications/ci-cd/github/setup-app).
Coolify automatically enables "Auto Deploy" after you set up your GitHub App. If it doesn't, enable it on your application by following these steps:
<ZoomImage src="/docs/images/applications/ci-cd/github/auto-deploy/github-app/1.webp" />
1. Open your application configuration page.
2. Go to the "Advanced" page.
3. Enable "Auto Deploy" under the general section.
## GitHub Actions
We have a dedicated guide for setting up GitHub Actions, which you can follow here: [/github/actions](/applications/ci-cd/github/actions).
## Webhooks
### 1. Enable Auto Deploy
<ZoomImage src="/docs/images/applications/ci-cd/github/auto-deploy/webhooks/1.webp" />
1. Open your application configuration page.
2. Go to the "Advanced" page.
3. Enable "Auto Deploy" under the general section.
### 2. Set Up GitHub Webhook Secret
<ZoomImage src="/docs/images/applications/ci-cd/github/auto-deploy/webhooks/2.webp" />
1. Enter a GitHub webhook secret (this must be a random string; you can use tools like [Random String Generator](https://getrandomgenerator.com/string)).
2. Save the webhook URL somewhere safe, we'll need it later.
<Callout type="warn" title="IMPORTANT">
A webhook secret acts like a password. Coolify only accepts the webhook if the secret matches.
</Callout>
### 3. Set Up Webhook on GitHub
<ZoomImage src="/docs/images/applications/ci-cd/github/auto-deploy/webhooks/3.webp" />
1. Go to your repository settings page.
2. Click on "Webhooks" from the sidebar.
3. Click the "Add webhook" button.
<ZoomImage src="/docs/images/applications/ci-cd/github/auto-deploy/webhooks/4.webp" />
4. Enter the previously copied webhook URL from Coolify in the "Payload URL" field.
5. Enter the webhook secret from Coolify in the "Secret" field.
6. Enable "Enable SSL verification".
7. Select "Just the `push` event".
8. Enable "Active".
9. Click the "Add webhook" button.
After clicking "Add webhook", you'll see a page like the one shown below:
<ZoomImage src="/docs/images/applications/ci-cd/github/auto-deploy/webhooks/5.webp" />
That's it! Coolify will automatically redeploy your application whenever you push changes to your repository.
content/docs/applications/ci-cd/github/deploy-key.mdx
+144
View File
@@ -0,0 +1,144 @@
---
title: GitHub Deploy Key
description: Deploy applications from private GitHub repositories using deploy keys in Coolify.
---
# GitHub Deploy Key
Deploy keys allow you to grant read-only access to a single private GitHub repository without using a personal access token or SSH key tied to your account.
When using deploy keys, Coolify can clone and deploy from private repositories securely, ensuring that only the specified repository is accessible.
### Why Use Deploy Keys with Coolify?
1. **Secure Access**: Grant read-only access to a single repository without sharing to many repositories.
2. **Repository-Specific**: Deploy keys are scoped to one repository.
3. **No Account Exposure**: Prevents potential security risks if the key is compromised.
4. **Cannot Install Github App**: Deploy keys can be used when you cannot install a GitHub App to your organization.
### When Not to Use Deploy Keys
1. **Multiple Repositories**: If you need access to multiple private repositories, consider using a GitHub App.
---
<Callout type="info" title="Example Data">
The following data is used as an example in this guide. Please replace it with your actual data when following the steps:
- **Repository Owner:** `ShadowArcanist`
- **Repository Name:** `coolify-dev`
- **Deploy Key Name:** `Deploy Key Tutorial`
- **SSH URL:** `git@github.com:ShadowArcanist/coolify-dev.git`
</Callout>
## 1. Create a Private Key on Coolify
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/1.webp" />
1. In your Coolify dashboard, click on **Keys & Tokens** from the sidebar.
2. Click on **Private keys** tab.
3. Click the **+ Add** button to create a new private key.
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/2.webp" />
4. Click **Generate new RSA SSH Key** or **Generate new ED25519 SSH Key** to generate a key pair.
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/3.webp" />
5. Copy the public key.
6. Click **Continue** to save the keys.
<Callout type="success" title="TIP">
You can also generate a key externally using the `ssh-keygen` command and paste the private key into Coolify:
```bash
ssh-keygen -t rsa -b 4096 -C "coolify-deploy-key"
```
Then, copy the contents of the generated `.pub` file for the next step.
</Callout>
## 2. Add Deploy Key on GitHub
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/4.webp" />
1. Go to your GitHub repository settings.
2. Navigate to **Deploy keys** in the left sidebar.
3. Click **Add deploy key** button.
<Callout type="info" title="TIP">
You can also access the deploy keys page directly at `https://github.com/YOUR_USERNAME/YOUR_REPO_NAME/settings/keys`
</Callout>
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/5.webp" />
4. Enter a title for your deploy key (e.g., `Coolify Deploy Key`).
5. Paste the public key you copied from Coolify.
6. Make sure **Allow write access** is unchecked (deploy keys should be read-only).
7. Click **Add key** to save.
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/6.webp" />
## 3. Copy Repository SSH URL
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/7.webp" />
1. Go to your GitHub repository.
2. Click the **Code** button.
3. Select the **Local** tab.
4. Click the **SSH** tab.
5. Copy the SSH URL (e.g., `git@github.com:ShadowArcanist/coolify-dev.git`).
## 4. Create a New Resource on Coolify
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/8.webp" />
1. Select your project from the Coolify dashboard.
2. Click the **+ New** button to create a new resource.
## 5. Select Private Repository (with Deploy Key) as Resource Type
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/9.webp" />
Select **Private Repository (with Deploy Key)** from the available resource types.
## 6. Choose Your Server
<Callout type="warn" title="HEADS UP!">
Coolify automatically selects the `localhost` server if you don't have any remote servers connected. In such cases, skip to the next step.
</Callout>
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/10.webp" />
Choose the server where you want to deploy the application.
## 7. Choose Your Deploy Key
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/11.webp" />
Select the private key you created in Coolify from the list of available private keys.
## 8. Configure the Application and Deploy
<ZoomImage src="/docs/images/applications/ci-cd/github/deploy-key/12.webp" />
1. Paste the SSH URL you copied from GitHub (e.g., `git@github.com:ShadowArcanist/coolify-dev.git`).
2. After entering the repository link, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on [applications](/applications) for more details.)
Once configured, deploy your application.
That's it!
content/docs/applications/ci-cd/github/meta.json
+13
View File
@@ -0,0 +1,13 @@
{
"title": "Github",
"pages": [
"overview",
"actions",
"auto-deploy",
"preview-deploy",
"public-repository",
"deploy-key",
"setup-app",
"switch-apps"
]
}
content/docs/applications/ci-cd/github/overview.mdx
+23
View File
@@ -0,0 +1,23 @@
---
title: "Overview"
description: "Integrate GitHub with Coolify to deploy applications from repositories, enable automatic deployments, and manage pull requests seamlessly."
---
# GitHub Integration
Coolify simplifies deploying applications from your GitHub repositories or Docker images hosted on GitHub Container Registry.
GitHub integration with Coolify supports deploying from both private and public repositories, automatic deployments on new commits, and pull request deployments.
## Ways to Use GitHub with Coolify
You can integrate GitHub with Coolify in several ways, depending on your needs. Below are the available options, each linked to a detailed guide for easy setup:
| Method | Description |
|--------|-------------|
| [Public Repository](/applications/ci-cd/github/public-repository) | Deploy applications directly using the URL of a public repository. |
| [Private Repository using GitHub App](/applications/ci-cd/github/setup-app) | Install the GitHub App on your personal account or organization to deploy both private and public repositories. |
| [Private Repository using Deploy Key](/applications/ci-cd/github/deploy-key) | Deploy applications from private repositories using a deploy key. |
| [Automatic Deployments](/applications/ci-cd/github/auto-deploy) | Automatically deploy new versions of your application when commits are pushed to a specific branch in your GitHub repository. |
| [Build and Deploy Using GitHub Actions](/applications/ci-cd/github/actions) | Build your application on GitHub using GitHub Actions as part of your CI/CD pipeline, push it to any Docker registry (such as GHCR or Docker Hub), and automatically deploy on Coolify. |
| [Preview Deployments](/applications/ci-cd/github/preview-deploy) | Automatically deploy new versions of your application based on pull requests. |
content/docs/applications/ci-cd/github/preview-deploy.mdx
+159
View File
@@ -0,0 +1,159 @@
---
title: GitHub Preview Deploy
description: Automatically deploy preview versions of your application for each GitHub pull request using Coolify.
---
# GitHub Preview Deploy
Preview deployments allow Coolify to automatically deploy new versions of your application whenever someone opens a pull request (PR) on your GitHub repository.
These preview deployments are automatically deleted once the associated pull request is merged or closed, ensuring a clean environment.
## Features
- **[Scoped Deployments](#scoped-deployments)**: Control who can trigger PR preview deployments.
- **[Scoped Secrets](#scoped-secrets)**: Keep production and preview environment variables separate.
- **[Automated Comments](#automated-comments)**: Post deployment status updates directly on pull requests.
## Preview Deployments Options
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/4.webp" />
- **Preview URL Template:** Each preview deployment gets its own unique URL based on this template.
- Use <code v-pre>&#123;&#123;random&#125;&#125;</code> to generate a random subdomain each time a PR is deployed.
- Use <code v-pre>&#123;&#123;pr_id&#125;&#125;</code> to use the pull request ID as the subdomain.
<Callout type="warn" title="IMPORTANT">
You need to set up a **wildcard** `A` record for the subdomain you want to use for preview deployments, pointing to your server's IP address. For example, to use `https://123.preview.shadowarcanist.com`, create an A record for `*.preview.shadowarcanist.com` pointing to your server's IP address.
</Callout>
- **Load Pull Requests:** Allows you to manually fetch all open pull requests on your repository. This is useful if you already had open PRs before setting up preview deployments.
<Callout type="info" title="INFO">
Coolify does not automatically deploy preview deployments for pull requests that were opened before preview deployments were enabled. You need to manually deploy these by clicking the 'Deploy' button on the pull request list in the Preview Deployments page.
</Callout>
## Scoped Deployments
If anyone can trigger a new preview deployment by creating a pull request, they could run arbitrary code directly on your environment, potentially gaining access to your environment or secrets.
Coolify allows you to configure who can trigger new preview deployments to prevent this:
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/1.webp" />
- **Preview Deployments**: Enables the Preview Deployments feature, and only repository members, collaborators, and contributors can trigger PR deployments.
- **Allow Public PR Deployments**: Anyone can trigger PR deployments.
## Scoped Secrets
Coolify separates environment variables for production and preview deployments, keeping your secrets safe.
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/2.webp" />
- **Production Environment Variables:** These variables are used only in your main deployment. They remain fully isolated and are never exposed to preview deployments triggered from pull requests.
- **Preview Deployment Environment Variables:** A separate set of variables used only for PR-based preview deployments. These variables can safely contain non-sensitive or limited-scope values, ensuring contributors' pull requests cannot access production secrets.
## Automated Comments
Coolify posts comments on pull requests with the deployment status and automatically updates them if the status changes.
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/3.webp" />
<Callout type="warn" title="IMPORTANT">
Automated comments only work if you are using the GitHub App for preview deployments.
</Callout>
## Setup Methods
There are two methods to set up preview deployments on Coolify:
- [Using GitHub App](#setup-using-github-app)
- [Using Webhooks](#setup-using-webhooks)
### Setup Using GitHub App
We have a dedicated guide for setting up the GitHub App, so please follow it first: [/applications/ci-cd/github/setup-app](/applications/ci-cd/github/setup-app).
As part of the setup, ensure Preview Deployments is configured correctly. The steps differ depending on whether you use Automated or Manual setup, as shown below.
<Callout type="info">
== Automated Setup
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/github-app/1.webp" />
Before you click "Register now", enable the "Preview Deployments" option. That's it!
== Manual Setup
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/github-app/2.webp" />
While setting up permissions for the GitHub App, do the following:
1. Under the "**Permissions**" section, click on "**Repository permissions**".
2. Set access to `Read and write` for `Pull Requests`.
3. Scroll down to the "**Subscribe to events**" section.
4. Enable the `Pull requests` option.
That's it!
</Callout>
---
If you have already set up the GitHub App without enabling the "Preview Deployments" feature, follow these steps:
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/github-app/3.webp" />
1. In your Coolify dashboard, click on **Sources** from the sidebar, then select your GitHub App.
2. Click the **Update** button in the "Permissions" section (this will redirect you to GitHub).
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/github-app/4.webp" />
3. Under the "**Permissions**" section, click on "**Repository permissions**".
4. Set access to `Read and write` for `Pull Requests`.
5. Scroll down to the "**Subscribe to events**" section.
6. Enable the `Pull requests` option.
---
### Setup Using Webhooks
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/webhook/1.webp" />
1. Enter a GitHub webhook secret (this must be a random string; you can use tools like [Random String Generator](https://getrandomgenerator.com/string)).
2. Save the webhook URL somewhere safe—we'll need it later.
<Callout type="warn" title="IMPORTANT">
A webhook secret acts like a password. Coolify only accepts the webhook if the secret matches.
</Callout>
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/webhook/2.webp" />
3. Go to your repository settings page.
4. Click on **Webhooks** from the sidebar.
5. Click the **Add webhook** button.
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/webhook/3.webp" />
6. Enter the previously copied webhook URL from Coolify in the "Payload URL" field.
7. Enter the webhook secret from Coolify in the "Secret" field.
8. Enable "Enable SSL verification".
9. Select "Let me select individual events".
10. Select "Pull Requests".
11. Enable "Active".
12. Click the **Add webhook** button.
After clicking "Add webhook", you'll see a page like the one shown below:
<ZoomImage src="/docs/images/applications/ci-cd/github/preview-deploy/webhook/4.webp" />
That's it! Coolify will automatically deploy preview deployments when a new pull request is created.
content/docs/applications/ci-cd/github/public-repository.mdx
+61
View File
@@ -0,0 +1,61 @@
---
title: "Deploy Public Repository"
description: "Learn how to deploy applications from public GitHub repositories directly using the repository URL in Coolify."
---
# Deploy Public Repository
You can deploy applications from any public GitHub repository by simply providing the repository URL.
## 1. Create a New Resource on Coolify
<ZoomImage src="/docs/images/applications/ci-cd/github/public-repository/1.webp" />
1. Select your project from the Coolify dashboard.
2. Click the **+ New** button to create a new resource.
## 2. Select Public Repository as Resource Type
<ZoomImage src="/docs/images/applications/ci-cd/github/public-repository/2.webp" />
Choose **Public Repository** from the available resource types.
## 3. Choose Your Server
<Callout type="warn" title="HEADS UP!">
Coolify automatically selects the `localhost` server if you don't have any remote servers connected. In such cases, skip to the next step.
</Callout>
<ZoomImage src="/docs/images/applications/ci-cd/github/public-repository/3.webp" />
Select the server where you want to deploy the application.
## 4. Enter Your Repository Link
<ZoomImage src="/docs/images/applications/ci-cd/github/public-repository/4.webp" />
Paste the URL of your public GitHub repository.
<Callout type="success" title="Tip">
The branch will be **automatically selected** based on the provided URL.
* https://github.com/coollabsio/coolify-examples → **main** branch will be selected.
* https://github.com/coollabsio/coolify-examples/tree/nodejs-fastify → **nodejs-fastify** branch will be selected
</Callout>
## 5. Configure the Application and Deploy
<ZoomImage src="/docs/images/applications/ci-cd/github/public-repository/5.webp" />
After entering the repository link, click **Check Repository**. Then, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on [builds](/applications/build-packs) for more details.)
Once configured, deploy your application.
That's it!
content/docs/applications/ci-cd/github/setup-app.mdx
+340
View File
@@ -0,0 +1,340 @@
---
title: "Setup GitHub App"
description: "Set up a GitHub App in Coolify to access and deploy from private GitHub repositories using automated or manual installation methods."
---
# GitHub App
Github app allows you to grant access to a single or multiple private repositories from your either personal github account or your organization on github.
### Why use github app with Coolify?
Scoped Access: The GitHub app lets you grant Coolify access to a specific repository, a selected group of repositories, or even all of your repositories. This gives you flexibility and better control over what Coolify can access.
### When Not to Use github app with Coolify?
Lack of Permission: If you don't have the necessary permissions to install the GitHub app, or if you prefer not to install it, then it’s best not to use it with Coolify.
## Installation Methods
There are two ways to install Github App on Coolify:
- [Automated Installation](/applications/ci-cd/github/setup-app#automated-installation) (Recommended)
- [Manual Installation](/applications/ci-cd/github/setup-app#manual-installation)
We highly recommend the Automated Installation method as it automates the process and reduces the chance of errors.
<Callout type="info" title="Example Data">
The following data is used as an example in this guide. Please replace it with your actual data when following the steps:
- **GitHub App Name on Coolify:** `Github App Tutorial`
- **GitHub App Name on Github:** `coolify-github-app-tutorial`
- **Webhook Endpoint:** `https://coolboxy.shadowarcanist.internal`
</Callout>
## Automated Installation
### 1. Create a Github App on Coolify
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/1.webp" />
1. In your Coolify dashboard, click on Sources from the sidebar.
2. Click the + Add button to create a new github app.
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/2.webp" />
3. Enter a Name for your App
4. Enter your github organization name (if you are adding the github app to your github account then leave this field empty) and click continue
<Callout type="info">
1. If you are using Selfhost or Enterprise version of Github then you can enter your github details on the Selhost/Enterprise github section.
2. The "System wide" option allows all teams you have on your coolify instance to use this specific github app, if you only want the current team to use the github app then leave this option unchecked.
<Callout type="warn">
Coolify cloud users won't see the option "System wide" because this option will enable your github app to all Cloud users so this option is disabled on Coolify Cloud
</Callout>
### 2. Set Webhook Endpoint
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/3.webp" />
1. Select the endpoint for github to send Webhook when a event (commit, pr) happens on github. If this endpoint is not reachable then automatic deployments won't work so if you decide to close port 8000 on your server you have to set the webhook endpoint as your Coolify dashboard domain
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/4.webp" />
2. Preview deployments are enabled by default and you can disable them if you dont want them
3. Click on Register now button (this will take you to github)
### 3. Create Github App on Github
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/5.webp" />
1. Give your github app a name (this will be shown on your github app list and you can always change it later)
2. Click on Create app button (this will take you back to your coolify dashboard)
### 4. Allow Github app access to repositories
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/6.webp" />
1. Click on "Install repositories on Github" button
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/7.webp" />
2. Select the repositories that you want this app to have access to (you can give access to all repositories or specific repositories)
3. Click on "Install" button (this will take you back to your Coolify dashboard)
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/8.webp" />
### 5. Create a New Resource on Coolify
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/9.webp" />
1. Select your project from the Coolify dashboard.
2. Click the **+ New** button to create a new resource.
### 6. Select Private Repository (with Github App) as Resource Type
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/10.webp" />
Select **Private Repository (with Github App)** from the available resource types.
### 6. Choose Your Server
<Callout type="warn" title="HEADS UP!">
Coolify automatically selects the `localhost` server if you don't have any remote servers connected. In such cases, skip to the next step.
</Callout>
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/11.webp" />
Choose the server where you want to deploy the application.
### 7. Choose Your Github App
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/12.webp" />
Select the Github App you created in Coolify from the list of available Apps.
### 8. Configure the Application and Deploy
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/13.webp" />
1. Choose Repository and click on "Load Repository" button.
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/14.webp" />
2. After selecting the repository, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on [builds](/applications/build-packs) for more details.)
Once configured, deploy your application.
That's it!
---
<Callout type="error" title="HEADS UP!">
**The Automated installation guide ends here. If you’ve followed the steps above, you can start using Github Apps now. The guide below is for those who want to manually install and set up Github App.**
</Callout>
## Manual Installation
### 1. Create a Github App on Coolify
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/15.webp" />
1. In your Coolify dashboard, click on Sources from the sidebar.
2. Click the + Add button to create a new github app.
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/16.webp" />
3. Enter a Name for your App
4. Enter your github organization name (if you are adding the github app to your github account then leave this field empty) and click continue
<Callout type="info">
1. If you are using Selfhost or Enterprise version of Github then you can enter your github details on the Selhost/Enterprise github section.
2. The "System wide" option allows all teams you have on your coolify instance to use this specific github app, if you only want the current team to use the github app then leave this option unchecked.
<Callout type="warn">
Coolify cloud users won't see the option "System wide" because this option will enable your github app to all Cloud users so this option is disabled on Coolify Cloud
</Callout>
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/17.webp" />
5. Click on Continue button
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/18.webp" />
6. Save the Source ID of github app somewhere safe (source id is the UUID you see on your url bar after `/github/`)
We will need the following data to setup the github app:
- App ID
- Installation ID
- Client ID
- Client Secret
- Webhook Secret
- SSH Key
We will get these data in the next few steps.
### 2. Create a App on Github
Creating apps on github slightly varies for personal accounts and organizations so choose the correct one from the below section
<Callout type="info">
== Personal Account
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/19.webp" />
1. Go to your github account settings
2. On the sidebar scroll down till you see "developer settings" and click on it
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/20.webp" />
3. Click the "New github app" button
== Organization
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/21.webp" />
1. Go to your github Organization settings
2. On the sidebar scroll down till you see "**developer settings**" and click on it
3. Click on "Github Apps"
4. Click the "New github app" button
</Callout>
### 3. Setup the Github App on Github
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/22.webp" />
1. Give your app a name
2. Enter homepage url for your app (this can be anything)
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/23.webp" />
3. Scrol down till you see the "**Post Installation**" section
4. Enter Setup URL: `https://coolboxy.shadowarcanist.internal/webhooks/source/github/install?source=a8000cg0g0ogcc0ggkk8ow4k`
5. Enable the option `Redirect on Update`
6. Enter Webhook URL: `https://coolboxy.shadowarcanist.internal/webhooks/source/github/events`
<Callout type="info">
You have to replace `https://coolboxy.shadowarcanist.internal` with your Coolify dashboard url and replace `a8000cg0g0ogcc0ggkk8ow4k` with the Source ID [Step 1](#_1-create-a-github-app-on-coolify-1)
</Callout>
7. Enter Webhook Secret (this has to be a random string, you can use tools like [Random String Generator](https://getrandomgenerator.com/string))
8. Enable the option `Enable SSL verification`
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/24.webp" />
9. Scrol down till you see the "**Permissions**" section
10. Set Access to `Read-only` for `Contents`
11. Set Access to `Read and write` for `Pull Requests` (Only needed if you plan to use Preview deployments feature)
12. Set Access to `Read-only` for `Email addresses`
<Callout type="warn" title="HEADS Up!">
On the screenshot above for permissions section we have hidden lot of Permission and only shown the Permission needed to setup Github app for Coolify.
</Callout>
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/25.webp" />
13. Scrol down till you see the "**Subscribe to events**" section
14. Enable the option `Push`
15. Enable the option `Pull requests` (Only needed if you plan to use Preview deployments feature)
16. Select the option `Only on this account` (Prevents others from installing our Github app to their github accounts)
17. Click the button "**Create Github App**"
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/26.webp" />
18. Save the `App ID` and `Client ID` somewhere safe (we have to enter this on Coolify later)
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/27.webp" />
19. Click the `Generate a new client secret` button
20. Save the `client secret` somewhere safe (we have to enter this on Coolify later)
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/28.webp" />
21. Scrol down till you see the "**Private keys**" section
22. Click the `Generate a private key` button (this will automatically download the private key as a `.pem` file)
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/29.webp" />
23. Click "Install App" from the sidebar
24. Click the "**Install**" button
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/30.webp" />
25. Select the repositories you want the app to have access to.
26. Click the "**Install**" button
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/31.webp" />
27. Click the Settings icon (this will take you to your account or organization applications page)
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/32.webp" />
28. Save the `Installation ID` somewhere safe (Installation ID is the number you see on your url bar after `/installations/`)
### 4. Add Private keys on Coolify
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/33.webp" />
1. In your Coolify dashboard, click on **Keys & Tokens** from the sidebar.
2. Click on **Private keys** tab.
3. Click the **+ Add** button to add a new private key.
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/34.webp" />
4. Give your Private key a name
5. Paste the content of the `.pem` file which github automatically downloaded to your machine when you setup the Github App on Github
6. Click on "**Continue**" button
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/35.webp" />
7. In your Coolify dashboard, click on **Sources** from the sidebar and select your Github app from the list
8. Enter the details (App ID, Installation ID etc..) you saved on previous steps
9. On "Private key" select the key you just added to Coolify
10. Click on "**Sync Name**" button, if you see a success message then you have done everything correctly and you can start using the Github app!
### 5. Create a New Resource on Coolify
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/36.webp" />
1. Select your project from the Coolify dashboard.
2. Click the **+ New** button to create a new resource.
### 6. Select Private Repository (with Github App) as Resource Type
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/37.webp" />
Select **Private Repository (with Github App)** from the available resource types.
### 6. Choose Your Server
<Callout type="warn" title="HEADS UP!">
Coolify automatically selects the `localhost` server if you don't have any remote servers connected. In such cases, skip to the next step.
</Callout>
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/38.webp" />
Choose the server where you want to deploy the application.
### 7. Choose Your Github App
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/39.webp" />
Select the Github App you created in Coolify from the list of available Apps.
### 8. Configure the Application and Deploy
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/40.webp" />
1. Choose Repository and click on "Load Repository" button.
<ZoomImage src="/docs/images/applications/ci-cd/github/setup-app/41.webp" />
2. After selecting the repository, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on [builds](/applications/build-packs) for more details.)
Once configured, deploy your application.
That's it!
</Callout>
</Callout>
content/docs/applications/ci-cd/github/switch-apps.mdx
+56
View File
@@ -0,0 +1,56 @@
---
title: Switch GitHub Apps
description: Learn how to switch your application from one GitHub App to another in Coolify, such as when moving repositories to a new organization.
---
# Switch GitHub Apps
Switching GitHub Apps allows you to change the GitHub App associated with your deployed applications, for example, when moving repositories to a new organization or account.
### Why Switch GitHub Apps?
1. **Organization Changes**: You've moved repositories to a new GitHub organization that requires a different GitHub App.
2. **Access Management**: You want to use a GitHub App with different permissions or repository access.
<Callout type="warn" title="IMPORTANT">
This feature is introduced in **Coolify v4.0.0-beta.408**. To follow this guide, you **must** be using Coolify v4.0.0-beta.408 or a higher version.
</Callout>
## 1. Move Repositories (Optional)
If your goal is to move a repository to a different account or organization, go ahead and transfer it on GitHub.
If you just want to use a different GitHub App without changing repositories, you can skip this step.
## 2. Add New GitHub App to Coolify
We have a dedicated guide for setting up a GitHub App, which you can follow here: [/applications/ci-cd/github/setup-app](/applications/ci-cd/github/setup-app). Follow that guide and come back here.
## 3. Set Up Repository Access
After adding the new GitHub App, verify that it has access to the correct repositories by following these steps:
<ZoomImage src="/docs/images/applications/ci-cd/github/switch-apps/1.webp" />
1. In your Coolify dashboard, click on **Sources** from the sidebar, then select your new GitHub App.
2. Click the **Update Repositories** button (this will redirect you to GitHub).
<ZoomImage src="/docs/images/applications/ci-cd/github/switch-apps/2.webp" />
3. Under the Repository access section, check if you can see the repositories that you want to use.
## 4. Switch Git Source on Coolify
<ZoomImage src="/docs/images/applications/ci-cd/github/switch-apps/3.webp" />
1. Open your application configuration page.
2. Go to the "Git Source" page.
3. Select your new GitHub App.
## 5. Update Repository Name (If Applicable)
<ZoomImage src="/docs/images/applications/ci-cd/github/switch-apps/4.webp" />
If you have moved your repository to a new organization or account, update the repository name accordingly (e.g., from `shadowarcanist/switch-apps-guide` to `airoflare/switch-apps-guide`).
You can skip this step if you didn't move your repository.
## 6. Redeploy the Application
To apply the new GitHub App to your application, redeploy it by clicking the **Redeploy** button.
That's it!
content/docs/applications/ci-cd/gitlab/integration.mdx
+116
View File
@@ -0,0 +1,116 @@
---
title: "Integration"
description: "Connect GitLab repositories to Coolify with deploy keys, Gitlab container registry with deploy token, automatic webhooks, and merge request deployments for CI/CD automation"
---
# GitLab Integration
## Public Repositories
You can use public repositories without any additional setup.
1. Select the `Public repository` option in the Coolify when you create a new resource.
2. Add your repository URL to the input field, for example: `https://gitlab.com/andrasbacsai/coolify-examples`
<Callout type="warn" title="Caution">
You can only use the https URL.
</Callout>
3. That's it! Coolify will automatically pull the latest version of your repository and deploy it.
## Private Repositories
Private repositories require a few more steps to setup.
1. Add a private key (aka `Deploy Keys`) to Coolify and to your GitLab repository in the `Settings` / `Repository` / `Deploy Keys` menu.
<Callout type="warn" title="Caution">
- You can generate a new key pair with the following command:
```bash
ssh-keygen -t rsa -b 4096 -C "deploy_key"
```
- Or you can also use Coolify to generate a new key for you in the `Keys & Tokens` menu.
</Callout>
2. Create a new resource and select the `Private Repository (with deploy key)`
3. Add your repository URL to the input field, for example: `git@gitlab.com:andrasbacsai/coolify-examples.git`
<Callout type="warn" title="Caution">
You need to use the SSH URL, so the one that starts with `git@`.
</Callout>
4. That's it! Coolify will automatically pull the latest version of your repository and deploy it.
## Public Container Registry
You can use public container registry without any additional setup.
1. Select the `Docker Image` option in the Coolify when you create a new resource.
2. Add your public container registry URL and also the tag to the input field, for example: `registry.gitlab.com/username/repository:latest`.
3. Press the `Deploy` button.
4. That's it! Coolify will automatically pull the latest version of your container registry and deploy it.
## Private Container Registry
Private container registry require a few more steps to setup.
1. Add a `Deploy Token` in your GitLab repository in the `Settings` / `Repository` / `Deploy Token` with scope `read_registry`. This step will generate credentials `username` and `token`
2. login docker with that credentials in your coolify server
```
echo "token-xxx" | docker login registry.privategitlab.com -u gitlab+deploy-token-xxx --password-stdin
```
3. Select the `Docker Image` option in the Coolify when you create a new resource.
4. Add your private container registry URL and also the tag to the input field, for example: `registry.privategitlab.com/username/repository:latest`.
5. Press the `Deploy` button.
6. That's it! Coolify will automatically pull the latest version of your container registry and deploy it.
## Automatic commit deployments with webhooks (Optional)
You can add a custom webhook URL to your GitLab repository to trigger a new deployment when you push to your repository.
<Callout type="warn" title="Caution">
This can be set on either public or private repositories.
</Callout>
In your resource, there is a `Webhooks` menu. In the `Manual Git Webhooks` section, you can find the URL what you need to set in your GitLab repository.
1. Set a secret key in the `GitLab Webhook Secret` input field.
2. Go to your repository in GitLab and open the `Settings` / `Webhooks` menu.
3. Add the URL from Coolify to the `URL` input field and the secret token.
4. Select the `Push events` option.
5. That's it! Now when you push to your repository, GitLab will send a webhook request to Coolify and it will trigger a new deployment.
## Merge request deployments with webhooks (Optional)
You can add a custom webhook URL to your GitLab repository to trigger a new deployment when you create a new merge request.
<Callout type="warn" title="Caution">
This can be set on either public or private repositories.
</Callout>
The process is the same as the previous one, but you need to select the `Merge request events` option in the `Settings` / `Webhooks` menu.
content/docs/applications/ci-cd/index.mdx
+108
View File
@@ -0,0 +1,108 @@
---
title: "CI/CD with Git Providers"
description: "Learn how Coolify applications integrate with Git providers for continuous deployment. Understand the difference between Git-based applications and Docker Compose services."
---
# CI/CD with Git Providers
Applications in Coolify are designed to be deployed directly from **Git repositories**, enabling continuous integration and continuous deployment (CI/CD) workflows. This means your applications automatically update when you push code changes to your repository.
## How Git Integration Works
When you deploy an application in Coolify, you connect it to a Git repository from **any Git provider**. Coolify works with all Git platforms, including:
- **[GitHub](/applications/ci-cd/github/overview)** - Full GitHub App integration or deploy keys
- **[GitLab](/applications/ci-cd/gitlab/integration)** - GitLab integration with webhooks
- **[Bitbucket](/applications/ci-cd/bitbucket/integration)** - Bitbucket integration with webhooks
- **[Gitea](/applications/ci-cd/gitea/integration)** - Self-hosted Git platform
- **Any other Git provider** - Works with any Git-compatible platform with publicly accessible repositories or using deploy keys
Once connected, Coolify:
1. **Pulls your source code** from the repository
2. **Builds a Docker image** using your chosen [build pack](/applications/build-packs)
3. **Deploys the container** to your server
4. **Watches for changes** and automatically redeploys when you push new commits (if auto-deploy is enabled)
## Key Benefits of Git-Based Deployments
### Automatic Deployments
Push code to your repository and Coolify automatically builds and deploys your application. No manual intervention needed.
### Preview Deployments
Test pull requests in isolated environments before merging to production. Each PR gets its own unique URL.
### Version Control Integration
- Track deployment history alongside your code commits
- Roll back to previous versions easily
- See exactly what code is running in production
### CI/CD Workflows
- Integrate with GitHub Actions, GitLab CI, and other CI tools
- Run tests before deployment
- Automate complex deployment pipelines
<Callout type="info" title="Alternative: Deploy Without Git">
If you want to deploy your own application **without connecting to a Git provider**, you can deploy it as a [Service](/services/introduction) instead. Services allow you to:
- Upload a Docker Compose file directly to Coolify
- Deploy from Docker images without source code
- Manage the application manually without Git integration
This is useful for scenarios where you build your Docker images elsewhere or prefer manual control over deployments.
</Callout>
## Repository Access Methods
Coolify supports multiple ways to access your Git repositories:
### Public Repositories
Simply provide the HTTPS URL of your public repository. No authentication needed. Works with any Git provider.
### Private Repositories
Choose from authentication methods based on your Git provider:
1. **Git Provider App Integration (Recommended for supported providers)**
- Available for GitHub
- Full integration with automatic webhooks
- Pull request deployments
- Commit status updates
- No SSH key management
2. **Deploy Keys (Works with any Git provider)**
- SSH-based authentication
- Universal support - works with any Git platform
- More manual webhook setup required
- Better for air-gapped or restricted environments
- Ideal for custom or self-hosted Git servers
## Supported Git Providers
While we provide detailed integration guides for popular platforms, **Coolify works with any Git provider** that supports standard Git protocols:
- **Public Repositories**: Any Git provider (no authentication required)
- **With App Integration**: GitHub
- **With Deploy Keys**: Any Git provider (GitHub, GitLab, Bitbucket, Gitea, Gogs, Forgejo, self-hosted solutions, and more)
## Next Steps
Ready to connect your Git provider? Choose your platform for detailed setup guides:
- **[GitHub Integration](/applications/ci-cd/github/overview)** - Connect GitHub repositories
- **[GitLab Integration](/applications/ci-cd/gitlab/integration)** - Connect GitLab repositories
- **[Bitbucket Integration](/applications/ci-cd/bitbucket/integration)** - Connect Bitbucket repositories
- **[Gitea Integration](/applications/ci-cd/gitea/integration)** - Connect self-hosted Gitea
- **[Other Git Providers](/applications/ci-cd/other-providers)** - Connect Gogs, Forgejo, or any custom Git server
Or learn about [Build Packs](/applications/build-packs) to understand how Coolify transforms your code into running containers.
content/docs/applications/ci-cd/meta.json
+10
View File
@@ -0,0 +1,10 @@
{
"title": "CI/CD",
"pages": [
"github",
"gitlab/integration",
"bitbucket/integration",
"gitea/integration",
"other-providers"
]
}
content/docs/applications/ci-cd/other-providers.mdx
+134
View File
@@ -0,0 +1,134 @@
---
title: "Other Git Providers"
description: "Connect any Git provider to Coolify using deploy keys and webhooks for automatic deployments. Works with Gogs, Forgejo, and custom Git servers."
---
# Other Git Providers
This guide will show you how to use other Git provider with Coolify, such as Gogs, Forgejo, and any other Git-compatible platform.
## Public Repositories
You can use public repositories from any Git provider without any additional setup.
1. Select the `Public repository` option in Coolify when you create a new resource.
2. Add your repository URL to the input field, for example: `https://git.example.com/username/repository`
<Callout type="warn" title="Caution">
You can only use the HTTPS URL.
</Callout>
3. That's it! Coolify will automatically pull the latest version of your repository and deploy it.
## Private Repositories
Private repositories require deploy keys for authentication.
### With Deploy Keys
1. Add a private key (aka `Deploy Keys`) to Coolify and to your Git repository in the repository settings (usually under `Settings` / `Deploy Keys` or `SSH Keys`).
<Callout type="warn" title="Caution">
- You can generate a new key pair with the following command:
```bash
ssh-keygen -t ed25519 -C "coolify_deploy_key"
```
- Or you can also use Coolify to generate a new key for you in the `Keys & Tokens` menu.
</Callout>
2. Create a new resource and select the `Private Repository (with deploy key)`
3. Add your repository URL to the input field, for example: `git@git.example.com:username/repository.git`
<Callout type="warn" title="Caution">
You need to use the SSH URL, so the one that starts with `git@`.
</Callout>
4. That's it! Coolify will automatically pull the latest version of your repository and deploy it.
## Automatic commit deployments (Optional)
For Git providers without direct integration, automatic deployments require triggering the deployment via the Deploy Webhook endpoint.
<Callout type="warn" title="Caution">
This requires your Git provider to support workflow automation or webhook actions (similar to GitHub Actions).
If your provider doesn't support this, you'll need to trigger deployments manually through the Coolify dashboard.
</Callout>
### Prerequisites
1. Create a [Coolify API Token](/api-reference/authorization) in your Coolify dashboard
2. Get the Deploy Webhook URL from your resource (Your resource → `Webhooks` menu → `Deploy Webhook`)
### Setup with Workflow/CI System
If your Git provider supports workflow automation (like GitHub Actions, GitLab CI, Forgejo Actions, etc.), you can trigger deployments automatically:
1. Add your Coolify API token to your repository secrets (e.g., `COOLIFY_TOKEN`)
2. Add the Deploy Webhook URL to your repository secrets (e.g., `COOLIFY_WEBHOOK`)
3. Create a workflow file that triggers on push events:
```yaml
# Example workflow (syntax varies by provider)
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Trigger Coolify Deployment
run: |
curl --request GET "${{ secrets.COOLIFY_WEBHOOK }}" \
--header "Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}"
```
4. That's it! Now when you push to your repository, the workflow will trigger and send a request to Coolify to start a new deployment.
<Callout type="info" title="Alternative: Direct Webhooks">
Some Git providers allow webhooks to send custom headers. If supported, you can configure a webhook to send a GET request with the `Authorization: Bearer YOUR_TOKEN` header directly to the Deploy Webhook URL, without needing a workflow file.
</Callout>
## Supported Git Providers
This method works with any Git provider that supports standard Git protocols, including:
- Gogs
- Forgejo
- Self-hosted GitLab CE/EE instances
- Custom Git servers (gitolite, etc.)
- Any Git-over-SSH compatible platform
## Comparison with App Integration
| Feature | Other Providers | GitHub, GitLab, Bitbucket, Gitea |
| --------------------- | -------------------------- | -------------------------------- |
| Repository access | ✅ Yes | ✅ Yes |
| Manual deployments | ✅ Yes | ✅ Yes |
| Auto-deploy | ⚠️ Requires workflow setup | ✅ Automatic |
| Pull request previews | ❌ No | ✅ Yes |
content/docs/applications/django.mdx
+19
View File
@@ -0,0 +1,19 @@
---
title: Django
description: Deploy Django applications on Coolify with gunicorn, automatic builds, environment variables, and Python package management.
---
# Django
Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.
## Requirements
1. Set the base directory where your `requirements.txt` and `manage.py` files are located.
> In the example repository, it is `/coolify`.
2. Add `gunicorn` to the `requirements.txt` file, [official docs](https://docs.gunicorn.org/en/stable/install.html).
3. Add `localhost` and your `domain` to `ALLOWED_HOSTS` in `settings.py` file, [ official docs](https://docs.djangoproject.com/en/4.2/ref/settings/#allowed-hosts).
> `Localhost` is required for health checks to work properly.
content/docs/applications/index.mdx
+235
View File
@@ -0,0 +1,235 @@
---
title: Applications
description: Deploy web applications on Coolify with Nixpacks, Docker, static sites, build packs, environment variables, and automated deployments.
---
# Applications
Application could be any type of web application. It could be a static site, a NodeJS application, a PHP application, etc.
For complex applications, you can use Docker Compose based deployments or the one-click services.
## How Deployments Work
Coolify deploys all applications as Docker containers. This means your app runs inside an isolated container on your server.
**Key Concepts:**
- **Docker Image:** A packaged version of your application with all dependencies included
- **Container:** A running instance of your Docker image
- **Build Process:** Transforms your source code into a Docker image ready for deployment
You have two options for deploying applications:
1. **Build on Coolify:** Use [build packs](/applications/build-packs) to automatically create Docker images from your source code
2. **Use Pre-built Images:** Deploy existing images from registries like [Docker Hub](https://hub.docker.com/?utm_source=coolify.io) or [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry?utm_source=coolify.io)
<Callout type="info" title="Resource Management">
Building Docker images can be resource-intensive. You can use a dedicated [build server](/knowledge-base/server/build-server) to handle builds separately from your production server.
</Callout>
## Examples
<Callout type="info">
The list is not complete.
You can host almost any application that you want, not just the ones listed here.
</Callout>
- [Vite](/applications/vite)
- [Django](/applications/django)
- [Jekyll](/applications/jekyll)
- [Vue.js](/applications/vuejs)
- [Next.js](/applications/nextjs)
- [Nuxt](/applications/nuxt)
- [Laravel](/applications/laravel)
- [Symfony](/applications/symfony)
- [Ruby on Rails](/applications/rails)
- [SvelteKit](/applications/svelte-kit)
## General Configuration
### Commands
You can overwrite the default commands by setting a custom value on the UI.
- Build
- Install
- Start
<Callout type="info">
If you leave it empty, Nixpacks will detect which commands to run. For
example, in Nodejs, it will check the lock files and run `npm ci` or `yarn
install` or `pnpm install` accordingly.
</Callout>
### Base Directory
It is useful for monorepos. You can set the base directory for all the commands that will be executed by Coolify.
### Public Directory
If you are building a static site, it is important to set the public directory, so the builder will know which directory to serve.
### Port Exposes
Port exposes are required for Docker Engine to know which ports to expose. The first port will be the default port for health checks.
Examples:
If you have a NodeJS application that listens on port 3000, you can set it like this: `3000`.
If you have a PHP-FPM application that listens on port 9000, you can set it like this: `9000`.
If you have a Nginx server that listens on port 80, you can set it like this: `80`.
### Port Mappings
<Callout type="warn">
You will lose some functionality if you map a port to the host system, like
`Rolling Updates`.
</Callout>
If you would like to map a port to the host system (server), you can do it here like this: `8080:80`.
This will map the port 8080 on the host system to the port 80 inside the container.
<Callout type="info">
If you would like to get performance boost and you do not need any domain
(websocket server with VERY high traffic), you can map its port to the host,
so the request will not go through the proxy.
</Callout>
## Advanced
### Static Site (Is it a static site?)
> This feature is only available for Nixpacks buildpacks.
If you need to serve a static site (SPA, HTML, etc), you can set this to `true`. It will be served by Nginx. `Disabled by default`.
### Force HTTPS
If you would like to force HTTPS, so no HTTP connections allowed, you can set this to `true`. `Enabled by default`.
### Auto Deploy
> This feature is only available for GitHub App based repositories.
If you would like to deploy automatically when a new commit is pushed to the repository, you can set this to `true`. `Enabled by default`.
### Preview Deployments
Preview deployments are a great way to test your application before merging it into the main branch. Imagine it like a staging environment.
#### URL Template
You can setup your preview URL with a custom template. Default is <span v-pre>`&#123;&#123;pr_id&#125;&#125;.&#123;&#123;domain&#125;&#125;`</span>.
This means that if you open a Pull Request with the ID `123`, and you resource domain is `example.com` the preview URL will be `123.example.com`.
<Callout type="success" title="TIP">
If you have several domains for your resource, the first will be used as the&#123;" "&#125;
<span v-pre>`&#123;&#123; domain &#125;&#125;`</span> part.
</Callout>
#### Automated Preview Deployments
> This feature is only available for GitHub App based repositories.
If you would like to deploy a preview version of your application (based on a Pull Requests), you can set this to `true`. `Disabled by default`.
If set to `true`, all PR's that are opened against the resource's configured branch, will be deployed to a unique URL.
#### Manually Triggered Preview Deployments
You can manually deploy a Pull Request to a unique URL by clicking on the `Deploy` button on the Pull Request page.
### Git Submodules
If you are using git submodules, you can set this to `true`. `Enabled by default`.
### Git LFS
If you are using git lfs, you can set this to `true`. `Enabled by default`.
### Environment Variables
[Read here](/knowledge-base/environment-variables)
### Persistent Storage
[Read here](/knowledge-base/persistent-storage)
### Health Checks
By default, all containers are checked for liveness.
<Callout type="warn">
Traefik Proxy won't work if the container has health check defined, but it is
`unhealthy`. If you do not know how to set up health checks, turn it off.
</Callout>
### Rollbacks
You can rollback to a previous version of your resource. At the moment, only local images are supported, so you can only rollback to a locally available docker image.
### Resource Limits
By default, the container won't have any resource limits. You can set the limits here. For more details, read the [Docker documentation](https://docs.docker.com/reference/compose-file/services).
## Deployment Types
There are several types of application deployments available.
- Public Git Repository
- Private Git Repository ([GitHub App](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps))
- Private Git Repository ([Deploy Key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys))
- Based on a Dockerfile
- Based on a Docker Compose
- Based on a Docker Image
## Build Packs
Build packs help transform your source code into Docker images. Coolify supports several build pack options to match different deployment needs:
- **[Nixpacks](/applications/build-packs/nixpacks)** - Automatic detection and building (recommended for most applications)
- **[Static](/applications/build-packs/static)** - For static sites and SPAs
- **[Dockerfile](/applications/build-packs/dockerfile)** - Use your own custom Dockerfile
- **[Docker Compose](/applications/build-packs/docker-compose)** - For multi-service applications
- **Docker Image** - Deploy pre-built images from registries
For detailed guides on each build pack, see the [Build Packs section](/applications/build-packs).
<Callout type="info" title="Quick Start">
Coolify uses [Nixpacks](https://nixpacks.com) by default, which automatically detects your application type and builds it accordingly. For most applications, you won't need to configure anything.
</Callout>
content/docs/applications/jekyll.mdx
+40
View File
@@ -0,0 +1,40 @@
---
title: Jekyll
description: Deploy Jekyll static sites on Coolify using Nixpacks or Dockerfile with Ruby, Nginx, and automated build processes.
---
# Jekyll
Jekyll is a simple, blog-aware, static site generator for personal, project, or organization sites.
## Deploy with Nixpacks
Nixpacks needs a few prerequisites in your source code to deploy your Jekyll application. More info [here](https://nixpacks.com/docs/providers/ruby).
## Deploy with Dockerfile
If you want simplicity, you can use a Dockerfile to deploy your Jekyll application.
### Prerequisites
1. Set `Ports Exposes` field to `80`.
2. Create a `Dockerfile` in the root of your project with the following content:
```dockerfile
FROM ruby:3.1.1 AS builder
RUN apt-get update -qq && apt-get install -y build-essential nodejs
WORKDIR /srv/jekyll
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .
RUN chown 1000:1000 -R /srv/jekyll
RUN bundle exec jekyll build -d /srv/jekyll/_site
FROM nginx:alpine
COPY --from=builder /srv/jekyll/_site /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```
3. Make sure you have a `Gemfile` and `Gemfile.lock` in the root of your project.
4. Set the buildpack to `Dockerfile`.
content/docs/applications/laravel.mdx
+442
View File
@@ -0,0 +1,442 @@
---
title: Laravel
description: Deploy Laravel PHP applications on Coolify with Nixpacks, queue workers, scheduler, supervisor, database, and Redis integration.
---
# Laravel
Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling.
Example repository [here](https://github.com/coollabsio/coolify-examples/tree/main/laravel).
## Deploy with Nixpacks
### Requirements
- Set `Build Pack` to `nixpacks`
- Set the required [environment variables](#environment-variables)
- Add `nixpacks.toml` with the following [configuration](#all-in-one-container)
- Set `Ports Exposes` to `80`
### Environment Variables
If your application needs a database or Redis, you can simply create them beforehand in the Coolify dashboard.
You will receive the connection strings which you can use in your application and set them as environment variables:
```bash
DB_CONNECTION=mysql
DB_HOST=<DB_HOST>
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=
REDIS_HOST=<REDIS_HOST>
REDIS_PASSWORD=null
REDIS_PORT=6379
```
### All-in-one container
If you would like to start queue worker, scheduler, etc within one container (recommended), then you can place a `nixpacks.toml` inside your repository with the following value.
```toml
[phases.setup]
nixPkgs = ["...", "python311Packages.supervisor"]
[phases.build]
cmds = [
"mkdir -p /etc/supervisor/conf.d/",
"cp /assets/worker-*.conf /etc/supervisor/conf.d/",
"cp /assets/supervisord.conf /etc/supervisord.conf",
"chmod +x /assets/start.sh",
"..."
]
[start]
cmd = '/assets/start.sh'
[staticAssets]
"start.sh" = '''
#!/bin/bash
# Transform the nginx configuration
node /assets/scripts/prestart.mjs /assets/nginx.template.conf /etc/nginx.conf
# Start supervisor
supervisord -c /etc/supervisord.conf -n
'''
"supervisord.conf" = '''
[unix_http_server]
file=/assets/supervisor.sock
[supervisord]
logfile=/var/log/supervisord.log
logfile_maxbytes=50MB
logfile_backups=10
loglevel=info
pidfile=/assets/supervisord.pid
nodaemon=false
silent=false
minfds=1024
minprocs=200
[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
[supervisorctl]
serverurl=unix:///assets/supervisor.sock
[include]
files = /etc/supervisor/conf.d/*.conf
'''
"worker-nginx.conf" = '''
[program:worker-nginx]
process_name=%(program_name)s_%(process_num)02d
command=nginx -c /etc/nginx.conf
autostart=true
autorestart=true
stdout_logfile=/var/log/worker-nginx.log
stderr_logfile=/var/log/worker-nginx.log
'''
"worker-phpfpm.conf" = '''
[program:worker-phpfpm]
process_name=%(program_name)s_%(process_num)02d
command=php-fpm -y /assets/php-fpm.conf -F
autostart=true
autorestart=true
stdout_logfile=/var/log/worker-phpfpm.log
stderr_logfile=/var/log/worker-phpfpm.log
'''
"worker-laravel.conf" = '''
[program:worker-laravel]
process_name=%(program_name)s_%(process_num)02d
command=bash -c 'exec php /app/artisan queue:work --sleep=3 --tries=3 --max-time=3600'
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
numprocs=12 # To reduce memory/CPU usage, change to 2.
startsecs=0
stopwaitsecs=3600
stdout_logfile=/var/log/worker-laravel.log
stderr_logfile=/var/log/worker-laravel.log
'''
"php-fpm.conf" = '''
[www]
listen = 127.0.0.1:9000
user = www-data
group = www-data
listen.owner = www-data
listen.group = www-data
pm = dynamic
pm.max_children = 50
pm.min_spare_servers = 4
pm.max_spare_servers = 32
pm.start_servers = 18
clear_env = no
php_admin_value[post_max_size] = 35M
php_admin_value[upload_max_filesize] = 30M
'''
"nginx.template.conf" = '''
user www-data www-data;
worker_processes 5;
daemon off;
worker_rlimit_nofile 8192;
events {
worker_connections 4096; # Default: 1024
}
http {
include $!{nginx}/conf/mime.types;
index index.html index.htm index.php;
default_type application/octet-stream;
log_format main '$remote_addr - $remote_user [$time_local] $status '
'"$request" $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
access_log /var/log/nginx-access.log;
error_log /var/log/nginx-error.log;
sendfile on;
tcp_nopush on;
server_names_hash_bucket_size 128; # this seems to be required for some vhosts
server {
listen ${PORT};
listen [::]:${PORT};
server_name localhost;
$if(NIXPACKS_PHP_ROOT_DIR) (
root ${NIXPACKS_PHP_ROOT_DIR};
) else (
root /app;
)
add_header X-Content-Type-Options "nosniff";
client_max_body_size 35M;
index index.php;
charset utf-8;
$if(NIXPACKS_PHP_FALLBACK_PATH) (
location / {
try_files $uri $uri/ ${NIXPACKS_PHP_FALLBACK_PATH}?$query_string;
}
) else (
location / {
try_files $uri $uri/ /index.php?$query_string;
}
)
location = /favicon.ico { access_log off; log_not_found off; }
location = /robots.txt { access_log off; log_not_found off; }
$if(IS_LARAVEL) (
error_page 404 /index.php;
) else ()
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include $!{nginx}/conf/fastcgi_params;
include $!{nginx}/conf/fastcgi.conf;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
}
'''
```
### With Inertia.js
When using Laravel with [Inertia.js](https://inertiajs.com/), you may need to specify some additional configuration in your `nixpacks.toml` file.
#### Increasing the NGINX buffer size for Inertia requests
Because of a [known issue](https://github.com/inertiajs/inertia-laravel/issues/529) with Inertia.js and default NGINX configuration, you may need to increase the buffer size for NGINX to handle Inertia requests.
```diff
"nginx.template.conf" = '''
# ...
http {
# ...
server {
# ...
location ~ \.php$ {
+ fastcgi_buffer_size 8k;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include $!{nginx}/conf/fastcgi_params;
include $!{nginx}/conf/fastcgi.conf;
# ...
}
}
}
```
#### Inertia SSR
If you are using Inertia.js with [server-side rendering](https://inertiajs.com/server-side-rendering), you should add another worker in your `nixpacks.toml` file to automatically start your SSR server.
```toml
"worker-inertia-ssr.conf" = '''
[program:inertia-ssr]
process_name=%(program_name)s_%(process_num)02d
command=bash -c 'exec php /app/artisan inertia:start-ssr'
autostart=true
autorestart=true
stderr_logfile=/var/log/worker-inertia-ssr.log
stdout_logfile=/var/log/worker-inertia-ssr.log
'''
```
> [!NOTE]
> By default, Nixpacks runs the command `npm run build` to build your application during the deployment. Ensure that your `build` script in `package.json` contains the necessary build commands for server-side rendering. If you use one of the official starter kits including Inertia.js, change your scripts like this:
> ```diff
> "scripts": {
>- "build": "vite build",
>+ "build": "vite build && vite build --ssr",
> "build:ssr": "vite build && vite build --ssr",
> }
> ```
> Alternatively, if you don't want to adapt your default `build` script in `package.json`, you can add the correct build command for server-side rendering directly in your `nixpacks.toml` configuration file.
>```diff
>[phases.build]
>cmds = [
>+ "npm run build:ssr",
> "mkdir -p /etc/supervisor/conf.d/",
> "cp /assets/worker-*.conf /etc/supervisor/conf.d/",
> "cp /assets/supervisord.conf /etc/supervisord.conf",
> "chmod +x /assets/start.sh",
> "..."
> ]
>```
### Persistent php.ini customizations
If you want to customize settings from your php.ini file, you can easily do so by using the `php_admin_value` directive and appending them to your `php-fpm.conf` file like this:
```toml
"php-fpm.conf" = '''
[www]
listen = 127.0.0.1:9000
user = www-data
group = www-data
listen.owner = www-data
listen.group = www-data
pm = dynamic
pm.max_children = 50
pm.min_spare_servers = 4
pm.max_spare_servers = 32
pm.start_servers = 18
clear_env = no
php_admin_value[memory_limit] = 512M
php_admin_value[max_execution_time] = 60
php_admin_value[max_input_time] = 60
php_admin_value[post_max_size] = 256M
'''
```
## Deploy with Dockerfile and Nginx Unit
### Prerequisites
1. Create a new resource from a private or public repository.
2. Set the `Ports Exposes` field to `8000`, for example.
3. Set default environment variables using `Developer view` in `Environment Variables`:
```bash
APP_DEBUG=false
APP_ENV=staging
APP_KEY= #YourAppKey
APP_MAINTENANCE_DRIVER=file
APP_NAME=Laravel
CACHE_STORE=file
DB_CONNECTION= #YourDbConnection
DB_DATABASE= #YourDb
DB_HOST= #YourDbHost
DB_PASSWORD= #YourDbPassword
DB_PORT= #YourDbPort
DB_USERNAME= #YourDbUsername
FILESYSTEM_DISK=public
MAIL_MAILER=log
SESSION_DRIVER=file
```
4. Create a `Dockerfile` in the root of your project with the following content:
```dockerfile
FROM unit:1.34.1-php8.3
RUN apt update && apt install -y \
curl unzip git libicu-dev libzip-dev libpng-dev libjpeg-dev libfreetype6-dev libssl-dev \
&& docker-php-ext-configure gd --with-freetype --with-jpeg \
&& docker-php-ext-install -j$(nproc) pcntl opcache pdo pdo_mysql intl zip gd exif ftp bcmath \
&& pecl install redis \
&& docker-php-ext-enable redis
RUN echo "opcache.enable=1" > /usr/local/etc/php/conf.d/custom.ini \
&& echo "opcache.jit=tracing" >> /usr/local/etc/php/conf.d/custom.ini \
&& echo "opcache.jit_buffer_size=256M" >> /usr/local/etc/php/conf.d/custom.ini \
&& echo "memory_limit=512M" > /usr/local/etc/php/conf.d/custom.ini \
&& echo "upload_max_filesize=64M" >> /usr/local/etc/php/conf.d/custom.ini \
&& echo "post_max_size=64M" >> /usr/local/etc/php/conf.d/custom.ini
COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer
WORKDIR /var/www/html
RUN mkdir -p /var/www/html/storage /var/www/html/bootstrap/cache
RUN chown -R unit:unit /var/www/html/storage bootstrap/cache && chmod -R 775 /var/www/html/storage
COPY . .
RUN chown -R unit:unit storage bootstrap/cache && chmod -R 775 storage bootstrap/cache
RUN composer install --prefer-dist --optimize-autoloader --no-interaction
COPY unit.json /docker-entrypoint.d/unit.json
EXPOSE 8000
CMD ["unitd", "--no-daemon"]
```
3. Create a `unit.json` file (lowercase) at the root of your project with the following content.
```json
{
"listeners": {
"*:8000": {
"pass": "routes",
"forwarded": {
"protocol": "X-Forwarded-Proto",
"source": ["<Load balancer IP, Subnet etc.>"]
}
}
},
"routes": [
{
"match": {
"uri": "!/index.php"
},
"action": {
"share": "/var/www/html/public$uri",
"fallback": {
"pass": "applications/laravel"
}
}
}
],
"applications": {
"laravel": {
"type": "php",
"root": "/var/www/html/public/",
"script": "index.php"
}
}
}
```
> [!NOTE]
> When using docker-compose for deployment, then there might be an issue with `Mixed content error` when some of the assets are requested via `http://` instead of `https://`. To avoid that, find your load balancer/proxy subnet or IP address and add it to the unit.config to explicitly tell unit to forward the correct headers to Laravel. Laravel also has to be configured trust proxies. More on that [here](https://laravel.com/docs/12.x/requests#configuring-trusted-proxies).
> ```json
> "listeners": {
> "*:8000": {
> "pass": "routes",
> "forwarded": {
> "protocol": "X-Forwarded-Proto",
> "source": ["<Load balancer IP, Subnet etc.>"]
> }
> }
> },
>```
4. Set Post-deployment to:
```bash
php artisan optimize:clear && php artisan config:clear && php artisan route:clear && php artisan view:clear && php artisan optimize
```
content/docs/applications/meta.json
+20
View File
@@ -0,0 +1,20 @@
{
"title": "Applications",
"pages": [
"---Frameworks---",
"django",
"jekyll",
"laravel",
"phoenix",
"rails",
"symfony",
"nextjs",
"vite",
"vuejs",
"nuxt",
"svelte-kit",
"vitepress",
"build-packs",
"ci-cd"
]
}
content/docs/applications/nextjs.mdx
+32
View File
@@ -0,0 +1,32 @@
---
title: NextJS
description: Deploy Next.js applications on Coolify with server-side rendering, static builds, Nixpacks, or custom Dockerfile configurations.
---
# NextJS
NextJS is a React framework that enables functionality such as server-side rendering and generating static websites.
[Example repository.](https://github.com/coollabsio/coolify-examples/tree/main/nextjs)
## Deploy with Nixpacks
### Server build (NodeJS)
- Set `Build Pack` to `nixpacks`.
### Static build (SPA)
- Set `Build Pack` to `nixpacks`.
- Enable `Is it a static site?`.
- Set `Output Directory` to `out`.
## Deploy with Dockerfile
If you are having problems with Nixpacks or want more control over the building stage, you can use a Dockerfile to deploy your NextJS application.
### Prerequisites
1. Set `Ports Exposes` field to `3000`.
2. Create a `Dockerfile` in the root of your project and copy the content from the official [NextJS Repository](https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile).
3. Set the Build Pack to `Dockerfile`.
content/docs/applications/nuxt.mdx
+31
View File
@@ -0,0 +1,31 @@
---
title: Nuxt
description: Deploy Nuxt applications on Coolify with server builds, static generation, and Nitro support using Nixpacks build configurations.
---
# Nuxt
Nuxt is an open source framework that makes web development intuitive and powerful.
Create performant and production-grade full-stack web apps and websites with confidence.
[Example repository.](https://github.com/coollabsio/coolify-examples/tree/main/nuxt)
## Server build (Nuxt, using `nuxt build`)
- Set `Build Pack` to `nixpacks`.
- Set Start Command to `node .output/server/index.mjs`
Alternatively, you can set the `start` script inside package.json to `node .output/server/index.mjs`. Then Nixpacks will automatically use it as the start command.
## Static build (Nuxt, using `nuxt generate`)
- Set `Build Pack` to `nixpacks`.
- Enable `Is it a static site?`.
- Set `Output Directory` to `dist`.
## Nitro server build (Nitro, using `nitro build`)
- Set `Build Pack` to `nixpacks`.
- Set Start Command to `node .output/server/index.mjs`
Alternatively, you can set the `start` script inside package.json to `node .output/server/index.mjs`. Then Nixpacks will automatically use it as the start command.
content/docs/applications/phoenix.mdx
+19
View File
@@ -0,0 +1,19 @@
---
title: Phoenix
description: Deploy Phoenix framework applications on Coolify with Elixir/Erlang, Nixpacks, environment variables, and database integration.
---
# Phoenix
Phoenix is a productive web framework that does not compromise speed and maintainability written in Elixir/Erlang.
## Requirements
- Set `Build Pack` to `nixpacks`
- Set `MIX_ENV` to `prod`
- It should be a `Build time` environment variable
- Set `SECRET_KEY_BASE` to a random string (https://hexdocs.pm/phoenix/deployment.html#handling-of-your-application-secrets)
- It should be a `Build time` environment variable
- Set `DATABASE_URL` to your database connection string
- It should be a `Build time` environment variable
- Set `Ports Exposes` to `4000` (default)
content/docs/applications/rails.mdx
+16
View File
@@ -0,0 +1,16 @@
---
title: Ruby on Rails
description: Deploy Ruby on Rails applications on Coolify with database migrations, MVC pattern support, and automated deployment workflows.
---
# Ruby on Rails
Ruby on Rails is a web-application framework that includes everything needed to create database-backend web applications according to the Model-View-Controller (MVC) pattern.
## Requirements
If you would like to migrate the database during the deployment with `NIXPACKS` build pack, you need to set the following `Start Command`:
```bash
bundle exec rake db:migrate && bundle exec bin/rails server -b 0.0.0.0 -p ${PORT:-3000} -e $RAILS_ENV
```
content/docs/applications/svelte-kit.mdx
+41
View File
@@ -0,0 +1,41 @@
---
title: SvelteKit
description: Deploy SvelteKit applications on Coolify with static builds using adapter-static or Node server builds with adapter-node.
---
# SvelteKit
Svelte Kit is a framework for building web applications of all sizes, with a beautiful development experience and flexible filesystem-based routing.
## Static build (`adapter-static`)
You need to use `@sveltejs/adapter-static` ([docs](https://kit.svelte.dev/docs/adapter-static)) adapter to build a static site.
1. Set your site to static `on` (under `Build Pack` section).
2. Set your `Publish Directory` to `/build`
## Node server (`adapter-node`)
You need to use `@sveltejs/adapter-node` ([docs](https://kit.svelte.dev/docs/adapter-node)) adapter to build a node server based SvelteKit app.
1. Set `Static` to `off` (under the `Build Pack` section).
2. Set your `Install Command` to `npm install`.
3. Set your `Build Command` to `npm run build`.
4. Set your `Start Command` to `node build`.
5. Click `Save`.
6. In your Environment Variables tab, check the current Node version supported by Nix. In the example screenshot below, it's `version 22`.
<ZoomImage src="/docs/images/applications/sveltekit/deploy-settings.png" />
7. Add `engines` to your `package.json` with the Node version from your environment variables. For example
```json
"engines": {
"node": ">=22"
}
```
8. Git Commit
9. Click Deploy from your Coolify Dashboard
10. Add an Environment Variable ORIGIN with your app's actual domain. For example:
<ZoomImage src="/docs/images/applications/sveltekit/env-vars.png" />
11. Optional, but recommended: Go to the Healthcheck tab and click `Enable Healthcheck`
<ZoomImage src="/docs/images/applications/sveltekit/healthcheck.png" />
content/docs/applications/symfony.mdx
+78
View File
@@ -0,0 +1,78 @@
---
title: Symfony
description: Deploy Symfony PHP applications on Coolify with Nixpacks, Doctrine migrations, database connections, and trusted proxy configuration.
---
# Symfony
Symfony is the leading PHP framework to create websites and web applications. Built on top of the Symfony Components.
## Requirements
- Set `Build Pack` to `nixpacks`
- Set `APP_ENV`
- Set `APP_SECRET`
- Set `NIXPACKS_PHP_FALLBACK_PATH` to `/index.php`
- Set `NIXPACKS_PHP_ROOT_DIR` to `/app/public`
- Set `Ports Exposes` to `80`
### Database migrations
If you use Doctrine, you can add the following `Post-deployment script` :
`php bin/console doctrine:migrations:migrate --all-or-nothing --no-interaction`
### Other components
If your application needs a database or Redis, you can simply create them beforehand in the Coolify dashboard.
You will receive the connection strings which you can use in your application and set them as environment variables:
```bash
DATABASE_URL=postgresql://app:!ChangeMe!@127.0.0.1:5432/app?serverVersion=16&charset=utf8
REDIS_HOST=<REDIS_HOST>
REDIS_PASSWORD=null
REDIS_PORT=6379
```
### Trusted proxy
You might need to configure the [trusted proxy](https://symfony.com/doc/current/deployment/proxies.html) :
- Set the environment variable `TRUSTED_PROXIES` with the IP of your server
- Add the following Symfony configuration :
```yaml
# config/packages/framework.yaml
framework:
trusted_proxies: "%env(TRUSTED_PROXIES)%"
trusted_headers: ['x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-forwarded-port', 'x-forwarded-prefix']
```
### Persistent php.ini customizations
If you want to customize settings from your php.ini file, you can easily do so by using the `php_admin_value` directive and appending them to your `php-fpm.conf` file like this:
```toml
"php-fpm.conf" = '''
[www]
listen = 127.0.0.1:9000
user = www-data
group = www-data
listen.owner = www-data
listen.group = www-data
pm = dynamic
pm.max_children = 50
pm.min_spare_servers = 4
pm.max_spare_servers = 32
pm.start_servers = 18
clear_env = no
php_admin_value[memory_limit] = 512M
php_admin_value[max_execution_time] = 60
php_admin_value[max_input_time] = 60
php_admin_value[post_max_size] = 256M
'''
```
content/docs/applications/vite.mdx
+23
View File
@@ -0,0 +1,23 @@
---
title: Vite
description: Deploy Vite applications on Coolify with TypeScript or JavaScript, Nixpacks build process, and static site generation.
---
# Vite
Vite is a build tool that aims to provide a faster and leaner development experience for modern web projects.
[Example repository.](https://github.com/coollabsio/coolify-examples/tree/main/vite)
## Vanilla TypeScript build (Static)
- Set `Build Pack` to `nixpacks`.
- Enable `Is it a static site?`.
- Set `Publish Directory` to `dist`.
## Vanilla JavaScript build (Static)
- Set `Build Pack` to `nixpacks`.
- Enable `Is it a static site?`.
- Set `Publish Directory` to `dist`.
content/docs/applications/vitepress.mdx
+17
View File
@@ -0,0 +1,17 @@
---
title: VitePress
description: Deploy VitePress documentation sites on Coolify with Vite, Vue, Nixpacks, and static site generation from Markdown files.
---
# VitePress
Vite & Vue Powered Static Site Generator Markdown to Beautiful Docs in Minutes.
[Example repository.](https://github.com/coollabsio/coolify-examples/tree/main/vitepress)
## Build (Static)
- Use `Nixpacks`.
- Turn on `Is it a static site?`.
- Set `Base Directory` to `/.vitepress/static`.
- Set `Publish Directory` to `/.vitepress/dist`.
content/docs/applications/vuejs.mdx
+27
View File
@@ -0,0 +1,27 @@
---
title: Vue
description: Deploy Vue.js applications on Coolify with server builds using Node/Express or static SPA builds with routing support.
---
# Vue
Vue.js is an approachable, performant and versatile framework for building web user interfaces.
[Example repository.](https://github.com/coollabsio/coolify-examples/tree/main/vue)
## Server build (NodeJS|Express)
- Set `Build Pack` to `nixpacks`.
- Set 'Start Command' to `node server.js`.
## Static build (SPA)
- Set `Build Pack` to `nixpacks`.
- Enable `Is it a static site?`.
- Set `Output Directory` to `dist`.
## Static build with Router (SPA)
- Set `Build Pack` to `nixpacks`.
- Enable `Is it a static site?`.
- Set `Output Directory` to `dist`.
content/docs/databases/backups.mdx
+77
View File
@@ -0,0 +1,77 @@
---
title: "Backups"
description: Configure scheduled database backups for PostgreSQL, MySQL, MariaDB, and MongoDB with cron expressions and S3 storage integration.
---
# Backups
Scheduled database backups could be configured for PostgreSQL and for Coolify itself.
This schedules are based on cron expressions, so you can configure them to run as often as you want.
You can also use simple cron expressions like:
```js
const VALID_CRON_STRINGS = [
'every_minute' => '* * * * *',
'hourly' => '0 * * * *',
'daily' => '0 0 * * *',
'weekly' => '0 0 * * 0',
'monthly' => '0 0 1 * *',
'yearly' => '0 0 1 1 *',
];
```
## PostgreSQL
Coolify creates a full backup of your PostgreSQL databases. You can specify which database to backup, with a comma separated list.
<Callout type="info" title="Tip">
Coolify's own database is also backed up using this method.
</Callout>
### Backup command
```bash
pg_dump --format=custom --no-acl --no-owner --username <username> <databaseName>
```
### Restore command
The backup has custom format, so you can restore it using the following command (or with any equivalent tool):
```bash
pg_restore --verbose --clean -h localhost -U postgres -d postgres pg-dump-postgres-1697207547.dmp
```
## MySQL
```bash
mysqldump -u root -p <password> <datatabaseName>
```
## MariaDB
```bash
mariadb-dump -u root -p <password> <datatabaseName>
```
## MongoDB
```bash
mongodump --authenticationDatabase=admin --uri=<uri> --gzip --archive=<archive>
```
Or if you exclude some collections:
```bash
mongodump --authenticationDatabase=admin --uri=<uri> --gzip --archive=<archive> --excludeCollection=<collectionName> --excludeCollection=<collectionName>
```
## S3 Backups
You can also define your own [S3 compatible](/knowledge-base/s3/introduction) storage to store your backups.
content/docs/databases/clickhouse.mdx
+94
View File
@@ -0,0 +1,94 @@
---
title: ClickHouse
description: Deploy ClickHouse on Coolify with column-oriented OLAP database, real-time analytics, S3 backups, and exceptional query performance.
---
# Clickhouse
<ZoomImage src="/docs/images/database-logos/clickhouse.webp" alt="Coolify clickhouse" />
## What is ClickHouse
ClickHouse is an open-source column-oriented database management system designed for online analytical processing (OLAP).
It's known for its exceptional query performance on large datasets, making it ideal for real-time analytics and data warehousing applications.
ClickHouse uses a column-oriented storage format and employs various optimizations like vectorized query execution to achieve high performance.
It supports SQL with extensions and can handle both batch and stream data ingestion, making it versatile for various analytical workloads.
## To connect
Map the port `8123:8123` for the HTTP interface.
In DBeaver, connect to `http://__ip_address__:8123` and use the `default` username plus the password in the UI.
If you also want the native TCP protocol (used by [clickhouse-client](https://clickhouse.com/docs/interfaces/cli) CLI), publish `9000:9000` as well.
## Backup and Restore Guide
Currently, Coolify does not support modifying ClickHouse configurations, which means certain native backup options (e.g., backing up to a local Disk or using `ALTER TABLE ... FREEZE PARTITION ...`) are not possible. Instead, the recommended approach is to use S3 for backups.
### How to Backup ClickHouse
To backup a table or an entire database, use the following SQL command:
- **Backup a Table:**
```sql
BACKUP TABLE <table_name> TO S3('<your_s3_endpoint_com>/<unique_folder_for_table_backup>', '<s3_access_key>', '<s3_secret_key>')
```
- **Backup a Database:**
Replace `TABLE` with `DATABASE` to backup the whole database:
```sql
BACKUP DATABASE <database_name> TO S3('<your_s3_endpoint_com>/<unique_folder_for_database_backup>', '<s3_access_key>', '<s3_secret_key>')
```
### How to Restore ClickHouse
To restore a table or database from an S3 backup, use the corresponding RESTORE command:
- **Restore a Table:**
```sql
RESTORE TABLE <table_name> FROM S3('<your_s3_endpoint_com>/<unique_folder_from_table_backup>', '<s3_access_key>', '<s3_secret_key>')
```
- **Restore a Database:**
Replace `TABLE` with `DATABASE` to restore the whole database:
```sql
RESTORE DATABASE <database_name> FROM S3('<your_s3_endpoint_com>/<unique_folder_from_database_backup>', '<s3_access_key>', '<s3_secret_key>')
```
### What Doesn't Work
- **Disk Backups:**
```sql
BACKUP TABLE test.table TO Disk('backups', '1.zip')
```
Does not work due to Coolify not allowing modifications to ClickHouse configurations.
- **Native Partition Freezes:**
```sql
ALTER TABLE ... FREEZE PARTITION ...
```
May not work because of limitations in the Docker/Coolify file structure.
- **clickhouse-backup Tool:**
External tools like [clickhouse-backup](https://github.com/Altinity/clickhouse-backup?utm_source=coolify.io) might not function properly within the Docker/Coolify setup due to similar configuration restrictions.
### Performance Notes
A community member shared that backing up a 145GB database took around 12 minutes, while restoring it took roughly 17 minutes.
## Links
- [The official website](https://clickhouse.com/?utm_source=coolify.io)
- [GitHub](https://github.com/ClickHouse/ClickHouse?utm_source=coolify.io)
content/docs/databases/dragonfly.mdx
+33
View File
@@ -0,0 +1,33 @@
---
title: DragonFly
description: Deploy DragonFly in-memory datastore on Coolify with Redis compatibility, multi-threaded architecture, and enhanced scalability features.
---
# DragonFly
<ZoomImage src="/docs/images/database-logos/dragonfly-dark.svg" alt="dragonfly" />
## What is DragonFly
DragonFly is a modern in-memory datastore, designed as a Redis alternative with better scalability and resource efficiency. It offers a Redis-compatible API while providing improved performance on multi-core systems. DragonFly is built to handle high-throughput scenarios and large datasets more efficiently than traditional in-memory datastores.
With its multi-threaded architecture and advanced data structures, DragonFly aims to provide enhanced scalability and performance for applications that require Redis-like functionality on modern hardware.
## Data Persistence
By default, Dragonfly DB does not save data to disk. To enable persistence, set up snapshots manually.
For example, configure the service with:
```yaml
services:
dragonfly:
command: 'dragonfly --requirepass XXXXXXXX --dir /data --dbfilename dragonfly-snapshot-{timestamp} --snapshot_cron "*/5 * * * *"'
```
You can also trigger manual saves using the SDK's `SAVE` command.
## Links
- [The official website](https://dragonflydb.io/?utm_source=coolify.io)
- [GitHub](https://github.com/dragonflydb/dragonfly?utm_source=coolify.io)
content/docs/databases/index.mdx
+69
View File
@@ -0,0 +1,69 @@
---
title: Introduction
description: Deploy databases on Coolify with one-click setup for PostgreSQL, MySQL, MariaDB, MongoDB, Redis, KeyDB, DragonFly, and ClickHouse.
---
# Databases you can host with Coolify
Coolify supports a variety of databases to suit different application needs. Even if you don't see your favorite database here, you can still host it with Coolify, using Docker.
Coolify offers one-click setup for the following databases:
- [PostgreSQL](/databases/postgresql)
- [Redis](/databases/redis)
- [DragonFly](/databases/dragonfly)
- [KeyDB](/databases/keydb)
- [Clickhouse](/databases/clickhouse)
- [MongoDB](/databases/mongodb)
- [MySQL](/databases/mysql)
- [MariaDB](/databases/mariadb)
Each database has its own strengths and use cases. Click on a database to learn more about it.
# Deploy a database
When selecting a New Resource, you can select a database from the list.
<ZoomImage src="/docs/images/screenshots/How-to-add-a-database.webp" alt="New Resource" />
You can configure a database with a simple click. Coolify supports the following databases:
- PostgreSQL
- MySQL
- MariaDB
- MongoDB
- Redis
- DragonFly
- KeyDB
- Clickhouse
## Ports Mapping vs Public Port
### Ports Mapping
Ports mapping is using the Docker [port mapping](https:/.docker.com/network/#published-ports) feature. It is used to map the container port to the host port. For example, if you set the port mapping to `8080:80`, the container port `80` will be mapped to the host port `8080`.
### Public Port
Public port is used to expose the container port to the internet, by starting an Nginx TCP proxy.
### Which one should I use?
- Port mappings makes the connection/port permanent (you need to restart your database to change it).
- The public port makes the connection/port dynamic (you can change it without restarting the database, Coolify will restart the Nginx TCP proxy for you).
## Proxy Timeout
When using a public port, Coolify starts an Nginx TCP proxy to expose your database. By default, the proxy timeout is set to **3600 seconds** (1 hour).
You can configure this in the database settings under **Proxy Timeout (seconds)**. This controls how long idle connections are kept open before Nginx closes them.
- The minimum value is **1 second**.
- Set a higher value if you have long-running queries or connections that stay idle for extended periods.
## Access database during builds
If you are using `Nixpacks` build pack, you have two ways to access your database during builds:
1. Database & your application are `in the same network`: You can reach it using the `internal URL` provided by Coolify.
2. Database & your application `are not in the same network`: You need to set your database to be `Accessible over the internet` and use the `public URL` provided by Coolify.
content/docs/databases/keydb.mdx
+20
View File
@@ -0,0 +1,20 @@
---
title: KeyDB
description: Deploy KeyDB on Coolify with high-performance multithreading, Redis compatibility, active replication, and FLASH storage support.
---
# KeyDB
## What is KeyDB
KeyDB is a high-performance fork of Redis, focusing on multithreading, memory efficiency, and high availability. It maintains API compatibility with Redis while offering improved performance, especially on multi-core systems. KeyDB introduces features like active replication, FLASH storage support, and subkey expires to enhance the capabilities of the traditional Redis model.
Designed to be a drop-in replacement for Redis, KeyDB aims to provide better resource utilization and scalability for applications requiring high-throughput in-memory data storage and processing.
## Links
- [The official website](https://keydb.dev/)
- [GitHub](https://github.com/EQ-Alpha/KeyDB)
content/docs/databases/mariadb.mdx
+20
View File
@@ -0,0 +1,20 @@
---
title: MariaDB
description: Deploy MariaDB databases on Coolify with MySQL compatibility, enhanced performance, additional storage engines, and automated backups.
---
# MariaDB
## What is MariaDB
MariaDB is an open-source fork of MySQL, designed to remain free and open-source. It aims to be a drop-in replacement for MySQL with enhanced features and performance. MariaDB maintains high compatibility with MySQL while offering additional storage engines, performance improvements, and features.
Started by core members of MySQL, MariaDB provides a robust and scalable database solution suitable for a wide range of applications.
## Links
- [The official website](https://mariadb.org/)
- [GitHub](https://github.com/MariaDB/server)
content/docs/databases/meta.json
+15
View File
@@ -0,0 +1,15 @@
{
"title": "Databases",
"pages": [
"ssl",
"backups",
"mysql",
"mariadb",
"postgresql",
"mongodb",
"redis",
"dragonfly",
"keydb",
"clickhouse"
]
}
content/docs/databases/mongodb.mdx
+19
View File
@@ -0,0 +1,19 @@
---
title: MongoDB
description: Deploy MongoDB NoSQL databases on Coolify with flexible document storage, horizontal scalability, and automated backup solutions.
---
# MongoDB
<ZoomImage src="/docs/images/database-logos/mongodb.webp" alt="MongoDB" />
## What is MongoDB
MongoDB is a popular, open-source document-oriented NoSQL database designed for scalability and flexibility. It stores data in flexible, JSON-like documents, meaning fields can vary from document to document and data structure can be changed over time.
MongoDB is known for its horizontal scalability, powerful query language, and ability to handle large volumes of unstructured or semi-structured data. It's widely used in modern web applications, content management systems, and other scenarios where flexible data models and scalability are crucial.
## Links
- [The official website](https://www.mongodb.com/)
- [GitHub](https://github.com/mongodb/mongo)
content/docs/databases/mysql.mdx
+19
View File
@@ -0,0 +1,19 @@
---
title: MySQL
description: Deploy MySQL databases on Coolify with ACID compliance, replication, partitioning, full-text indexing, and automated backup features.
---
# MySQL
<ZoomImage src="/docs/images/database-logos/mysql.webp" alt="MySQL" />
## What is MySQL
MySQL is a widely-used, open-source relational database management system (RDBMS) known for its reliability, ease of use, and performance. It's an essential component of the popular LAMP (Linux, Apache, MySQL, PHP/Python/Perl) stack used for web development.
MySQL provides a robust, ACID-compliant database solution suitable for a wide range of applications, from small websites to large-scale enterprise systems. It offers features like replication, partitioning, and full-text indexing, making it versatile for various use cases.
## Links
- [The official website](https://www.mysql.com/)
- [GitHub](https://github.com/mysql/mysql-server)
content/docs/databases/postgresql.mdx
+50
View File
@@ -0,0 +1,50 @@
---
title: PostgreSQL
description: Deploy PostgreSQL databases on Coolify with advanced features, automated backups, import/restore capabilities, and 30+ years of reliability.
---
# PostgreSQL
<ZoomImage src="/docs/images/database-logos/postgresql.webp" alt="PostgreSQL" />
## What is PostgreSQL
PostgreSQL is an advanced, open-source object-relational database system known for its reliability, feature robustness, and performance. It has more than 30 years of development and is widely used in the industry.
PostgreSQL, often simply "Postgres", uses and extends the SQL language combined with many features that safely store and scale the most complicated data workloads.
## Links
- [The official website](https://www.postgresql.org/)
- [GitHub](https://github.com/postgres/postgres)
## Import Backups
Coolify can import a database dump into a running PostgreSQL instance using the
**Import Backups** section of the Configuration for the instance.
The database dump can either be a file uploaded to the server, or dragged and
dropped into the Configuration screen directly.
The import command can be customized, but by default it expects a database dump
created using the `pg_dump` command with the `-Fc` flag passed in (custom
format).
For example, the following command connects to a PostgreSQL database running in
a local Docker container named `pg-db` as the database user `postgres` and
writes a dump of the `postgres` database to the file `example-database.sql.gz`:
```bash
docker exec pg-db pg_dump -U postgres -d postgres -Fc >example-database.sql.gz
```
### Note on upgrading PostgreSQL
The **custom** dump format is sensitive to version differences between the dump and
restore commands.
Use the plain (default) or **tar** dump formats to migrate from an older version
of PostgreSQL to a newer version. When using plain format dumps, use `psql` as
the custom import command instead of `pg_restore`.
See the PostgreSQL documentation for `pg_dump` and `pg_restore` for more information.
content/docs/databases/redis.mdx
+17
View File
@@ -0,0 +1,17 @@
---
title: Redis
description: Deploy Redis in-memory databases on Coolify with caching, vector database, document storage, streaming, and message broker capabilities.
---
# Redis
<ZoomImage src="/docs/images/database-logos/redis.svg" alt="Redis" />
## What is Redis
Redis is an in-memory data store used by millions of developers as a cache, vector database, document database, streaming engine, and message broker. Redis has built-in replication and different levels of on-disk persistence. It supports complex data types (for example, strings, hashes, lists, sets, sorted sets, and JSON), with atomic operations defined on those data types.
## Links
- [The official website](https://redis.io/)
- [GitHub](https://github.com/redis/redis)
content/docs/databases/ssl.mdx
+144
View File
@@ -0,0 +1,144 @@
---
title: Database SSL
description: Secure database connections on Coolify with SSL encryption, automatic certificate generation, and multiple SSL modes for enhanced security.
---
# Database SSL `^v4.0.0-beta.399`
Database SSL in Coolify encrypts the communication between your applications and databases, ensuring that data remains secure.
With automatic certificate binding and generation, this feature simplifies secure setup. It was first introduced in Coolify version **v4.0.0-beta.399**.
## Introduction
Database SSL adds an extra layer of security by encrypting data exchanged with your database. This guide covers:
- Enabling SSL mode for your database connections.
- Selecting the appropriate SSL mode based on your security needs.
- Managing the CA certificate that verifies database connections.
## 1. How to Enable Database SSL
To secure your database connection with SSL:
1. **Access Database Settings**
In your Coolify dashboard, access the general settings of the database you want to secure.
<ZoomImage src="/docs/images/database/ssl/1.webp" alt="Coolify dashboard screenshot" />
2. **Enable SSL Mode**
Check the **Enable SSL** option to activate SSL for the database connection.
<ZoomImage src="/docs/images/database/ssl/2.webp" alt="Coolify dashboard screenshot" />
3. **Select the SSL Mode**
Choose the SSL mode from the dropdown menu. For example, select **verify-full** for maximum security.
<ZoomImage src="/docs/images/database/ssl/3.webp" alt="Coolify dashboard screenshot" />
<Callout type="warn" title="Note">
To make use of SSL after enabling it, you need to use the new connection URL for your app, which includes the SSL configuration.
If you are not using the new URL, the database connection will not use SSL (in most cases).
</Callout>
Coolify automatically binds the generated certificates and keys to the required locations, so manual changes are only needed if you wish to use custom certificates.
## 2. SSL Modes Explained
Coolify supports several SSL modes, each providing a different level of security:
<ZoomImage src="/docs/images/database/ssl/4.webp" alt="Coolify dashboard screenshot" />
### PostgreSQL
- **allow (insecure)**
This mode permits both encrypted and unencrypted connections. It does not enforce SSL, so if SSL fails, the connection will fall back to an unencrypted state.
This option is considered insecure because it allows unencrypted traffic.
- **prefer (secure)**
With this mode, Coolify will attempt to use SSL first. If an SSL connection is available, it will be used, otherwise, it will fall back to an unencrypted connection.
While this option prefers encryption, it doesn’t guarantee that every connection will be secured.
- **require (secure)**
This mode mandates that the connection must be encrypted. However, it does not perform any checks on the server certificate.
This means the connection is encrypted, but the identity of the server is not verified.
- **verify-ca (secure)**
This option goes a step further by encrypting the connection and verifying that the server's certificate is signed by a trusted Certificate Authority (CA). It does not check if the hostname matches the certificate.
This mode offers a balance between security and ease of setup.
- **verify-full (secure)**
This is the most secure mode. It not only encrypts the connection and verifies the certificate authority but also confirms that the server’s hostname matches the certificate.
This provides full assurance that you are connecting to the correct server, similar to the security level provided by Cloudflare Origin Certificate setups.
### Other Databases
- **MySQL & MongoDB:**
Only the following modes are available: **prefer, require, verify ca, verify full**.
- **MariaDB, Redis, KeyDB, DragonFly DB:**
No SSL modes are visible in the UI.
- **Clickhouse DB:**
SSL is not supported, there is no checkbox to enable SSL nor dropdown options.
<Callout type="warn" title="Developer Note">
Modes lower than **require** are not 100% secure as they only encrypt the connection without full verification of the server’s identity.
For modes higher than **require** (i.e., **verify-ca** and **verify-full**), you must mount the Coolify CA certificate into the container that connects to the database for additional security.
Note that in most cases (for example, PostgreSQL), merely enabling SSL does nothing unless you use the new connection URL that enforces SSL.
However, for some databases, like the redis-based ones, enabling SSL in the UI does enforce the mode.
</Callout>
<Callout type="success" title="Tip">
For maximum security, **verify-full** is recommended (when available).
</Callout>
## 3. CA SSL Certificate Management
Coolify manages the CA certificate automatically, ensuring that secure database connections are validated.
In the dashboard, under **Servers > YOUR_SERVER_NAME > Proxy > Advanced**, you can see the following options:
<ZoomImage src="/docs/images/database/ssl/5.webp" alt="Coolify dashboard screenshot" />
- **CA SSL Certificate**: Displays the current CA certificate used.
- **Save Certificate**: Allows you to save a local copy of the certificate.
- **Regenerate Certificate**: Lets you generate a new CA certificate if needed.
### Recommended Configuration
For secure connections, mount the Coolify CA certificate into all containers that need to connect to your databases.
The recommended bind mount is:
```bash
/data/coolify/ssl/coolify-ca.crt:/etc/ssl/certs/coolify-ca.crt:ro
```
## 4. Using a Custom CA Certificate
If you wish to use your own CA certificate instead of the one generated by Coolify:
1. **Prepare Your CA Certificate**
Make sure your certificate is in PEM format.
2. **Upload Your Certificate**
Upload your custom CA certificate in the following location:
```bash
/data/coolify/ssl/coolify-ca.crt
```
3. **Mount the Certificate**
Make sure that the container that requires database access mounts the certificate at:
```bash
/data/coolify/ssl/coolify-ca.crt:/etc/ssl/certs/coolify-ca.crt:ro
```
content/docs/get-started/cloud.mdx
+262
View File
@@ -0,0 +1,262 @@
---
title: Coolify Cloud
description: Coolify Cloud is a fully managed PaaS service with zero maintenance, automatic scaling, daily backups, and email notifications.
---
<ZoomImage src="/docs/images/get-started/cloud-banner.webp" alt="Coolify cloud banner" />
<br />
[Coolify Cloud](https://coolify.io/pricing/) is our managed, paid service (maintained by [Andras](https://x.com/heyandras), Coolify’s Founder) that runs the Coolify on our infrastructure, so you don’t need to allocate CPU, RAM, or disk for Coolify itself.
You still bring your own servers (VPS, Raspberry Pi, EC2, etc.) and connect them via SSH, then deploy apps, databases, and services exactly as you would with a self-hosted instance.
Coolify Cloud uses the same open-source codebase, so there are no locked-behind-paywall features.
## Benefits of Coolify Cloud
| Features | Explanation |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------ |
| **Zero Maintenance Coolify** | No need to upgrade, or monitor Coolify, our team does it for you. |
| **Daily Backups** | The Coolify Cloud database is backed up every 24 hours. |
| **Preconfigured Email** | Receive build, deployment, and server status notifications via email without any setup on your end. |
| **Automatic Scaling** | As you connect more servers, our infrastructure scales CPU, RAM, and disk usage for Coolify. |
| **Staged Updates** | New updates are first rolled out to self-hosted users. Once stability is confirmed, they’re rolled out to Cloud. |
| **Founder-Tested Releases** | Andras personally tests every update before it’s deployed to the Cloud, ensuring maximum stability and reliability. |
## Getting Started with Coolify Cloud
1. **Create Your Account:**
- Visit the [Coolify Cloud Registration](https://app.coolify.io/register) page and sign up.
2. **Choose Your Plan:**
- Base fee: **$5/month** (includes up to two connected servers).
- **$3/month** per additional server.
3. **Complete Payment**
- Use any major credit/debit card to finish the subscription process.
4. **Connect Your Servers**
<details>
<summary>Detailed Server Connection Guide</summary>
1. **Add Private Key:** Login to your Coolify account (or create one if you’re new) and Add a new private key
<ZoomImage src="/docs/images/resources/screenshots/6.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/7.webp" alt="Coolify dashboard screenshot" />
***
2. **Add a Server:** Navigate to the **Servers** tab and add a new server by entering your Hetzner server’s IPv4 address.
<ZoomImage src="/docs/images/resources/screenshots/8.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/9.webp" alt="Coolify dashboard screenshot" />
***
3. **Validate Server:** Click **Validate Server & Install Docker Engine**. Coolify will automatically install all necessary components on your server.
<ZoomImage src="/docs/images/resources/screenshots/10.webp" alt="Coolify dashboard screenshot" />
***
4. **Check Status:** Once finished, you should see a green **Proxy Running** status indicating everything is set up.
<ZoomImage src="/docs/images/resources/screenshots/11.webp" alt="Coolify dashboard screenshot" />
</details>
5. **Deploy Your Applications**
## How Coolify Cloud Pricing works?
We charge a base fee of **\$5/month**, which covers up to **two servers**. Each additional server you connect is an **add-on of \$3/month**.
Charging per server allows us to scale our infrastructure responsibly, since each connected server increases resource usage (CPU, RAM, storage) on our end.
If you only need one server, you still pay the $5 base fee (with capacity for a second server if you add it later).
If you plan to connect more than two, simply multiply $3 by the extra servers.
## Why Coolify Cloud Exists
You might wonder why Coolify Cloud is a paid service when there are no exclusive, locked-down features.
The idea came to Andras (Coolify's Founder) as a way to offer a “**paid option without paywall**” — a model where the open-source project stays completely free, but those who prefer a managed experience can contribute financially.
- **Experiment Turned Success:**
- Initially launched as an experiment, Coolify Cloud quickly attracted over 2,100 active users.
* **Sustainable Funding:**
- While the revenue from Cloud is modest, it provides a steady income stream that helps keep Coolify free and under active development for everyone.
* **Community-First Approach**
- By not restricting any features, we maintain transparency and trust.
- Cloud subscribers simply pay for convenience and reliability, not to unlock core functionality.
## Frequently Asked Questions
<details>
<summary>1. Do I get any Cloud-only features?</summary>
No. Coolify Cloud and self-hosted Coolify share the same feature set.
Cloud’s value lies in automatic backups, email notifications, scaling, and update testing handled for you.
</details>
<details>
<summary>2. Does Coolify Cloud back up my application data?</summary>
No, Coolify Cloud only backs up the Coolify database (e.g., dashboard settings).
You are responsible for backing up any databases or storage volumes on your servers.
</details>
<details>
<summary>3. Can I import my self-hosted Coolify configurations to Coolify Cloud?</summary>
No.
To transfer configurations, you'll need to back up the database from your self-hosted instance and restore it to a new Coolify instance.
However, since you don’t have access to the database in Coolify Cloud, it’s not possible to migrate data or settings directly to the cloud version.
</details>
<details>
<summary>4. How often Coolify Cloud is backed up?</summary>
Every 24 hours
</details>
<details>
<summary>5. Is Coolify Cloud really based on the open-source version of Coolify?</summary>
Yes, Coolify Cloud uses the same open-source codebase as the self-hosted version. There are no paywall features, and the Cloud service is simply a managed experience for convenience.
</details>
<details>
<summary>6. What happens if I cancel my Coolify Cloud subscription?</summary>
If you cancel your subscription, you will stop being billed, and your access to Coolify Cloud will be suspended at the end of your current billing cycle.
However, your servers will remain unaffected, and all of your applications will continue running as normal.
Since your server will still be hosting your applications with a reverse proxy handling incoming requests, there will be no interruptions.
</details>
<details>
<summary>7. What happens if I forget to pay an invoice?</summary>
If a payment fails or an invoice is missed, your subscription and access to Coolify Cloud will be temporarily paused until the payment is successfully processed.
You will receive an email notification about the failed payment.
Once the payment is made, your Coolify Cloud access will be restored, and all your settings will remain intact—there’s no data loss.
Your servers will also stay up and running, and your applications will continue to function normally, as everything is still hosted on your own server with a reverse proxy.
</details>
<details>
<summary>8. Are there any IP addresses I need to whitelist for Coolify Cloud?</summary>
Yes, Coolify Cloud uses specific IP addresses.
You can find the list of IPs [here](https://coolify.io/docs/knowledge-base/faq#coolify-cloud-public-ips).
The main requirement is that Coolify Cloud needs to access your server's SSH port.
</details>
<details>
<summary>9. Do I need to bring my own servers to Coolify Cloud?</summary>
Yes, when using Coolify Cloud, you must provide your own servers (e.g., VPS, Raspberry Pi, EC2, etc.).
Coolify Cloud manages Coolify on our infrastructure, but we don’t provide the servers themselves.
This approach allows you to choose the hardware that best fits your needs.
</details>
<details>
<summary>10. Why do I have to pay for Coolify Cloud if I’m bringing my own servers?</summary>
While you bring your own servers, the subscription fee for Coolify Cloud covers the managed service aspect.
This includes infrastructure management, maintenance, support, updates, and scaling, so you don’t have to worry about technical aspects like monitoring, patching, or backups for Coolify.
We take care of the heavy lifting to ensure everything runs smoothly.
</details>
<details>
<summary>11. What happens if I exceed the number of connected servers?</summary>
You won’t be able to add extra servers to Coolify cloud unless your subscription is upgraded.
</details>
<details>
<summary>12. Is there a trial period for Coolify Cloud?</summary>
Currently, Coolify Cloud doesn’t offer a free trial. However, the subscription is affordable—just **$5 per month** for up to two connected servers.
If you want to explore all the features, you can run Coolify on a small Linux server or a VM on your PC by following the [self-hosted installation guide](https://coolify.io/docs/get-started/installation).
Since both cloud and self-hosted versions use the same codebase, you’ll be able to test all the features without any limitations.
</details>
<details>
<summary>13. Can I get any discounts?</summary>
The current **$5/month** subscription rate is already quite affordable, so discounts are not available at the moment.
</details>
<details>
<summary>14. I have to pay to use Coolify Cloud, so doesn't that mean I'm locked into a vendor?</summary>
**Not really.**
You're paying for the managed Coolify instance, but stopping the use of Coolify Cloud won't affect your applications.
You can connect your own server, so you retain full control. Everything runs as a Docker container, and Coolify will install a reverse proxy on your server to ensure everything works smoothly without needing Coolify Cloud.
In a true vendor lock-in, your apps would stop if you stop paying, but that’s not the case with Coolify Cloud.
</details>
<details>
<summary>15. Can I access the Coolify Cloud dashboard on my own domain?</summary>
No.
The Coolify Cloud dashboard is only available at https://app.coolify.io.
If you’d like to access the dashboard on your own domain, you’ll need to self-host Coolify.
</details>
content/docs/get-started/concepts.mdx
+80
View File
@@ -0,0 +1,80 @@
---
title: Coolify Concepts
description: Learn core Coolify concepts including servers, resources, environments, projects, Docker containers, reverse proxy, and team management basics.
---
<ZoomImage src="/docs/images/get-started/concepts-banner.webp" alt="Coolify concepts banner" />
<br />
Many people start their self-hosting journey after discovering Coolify. If you’re one of them, here’s a list of a few concepts that could make your experience smoother.
## Servers
A server is a computer designed to run applications or services, providing the necessary computing power for your projects.
It can be either physical such as a machine you have at home, like a Raspberry Pi, or one rented from a hosting provider like Hetzner.
## Resources
In Coolify, a resource refers to an application or service you set up on your server—like a website, database, or API.
Each resource comes with its own configuration, like domains, backups, health checks, and so on.
Coolify offers a handy list of pre-set resources, called one-click services, that you can deploy instantly. But if you prefer, you can also deploy your own application easily.
## Environments
In Coolify, a environment is a tailored setup on your server that determines how your resources operate.
For instance, you could have a development environment for testing and debugging your code, alongside a production environment where your finished application goes live.
With Coolify, you can set up multiple environments on a single server, letting you switch between them effortlessly.
## Projects
A project in Coolify is a group of environments and resources you’ve deployed on your server.
It serves as the highest-level structure in Coolify, organizing your deployment setup.
You can manage multiple projects on the same server, each with its own unique set of environments and resources.
For example, you might create one project for all your hobby-related resources and another for work-related ones.
## Containers
In Coolify, everything you deploy runs as a Docker container, making it easy to manage and isolate your application.
You can use pre-built Docker images from public registries like Docker Hub or GitHub Container Registry to deploy without building them yourself.
To deploy, you need a Docker image, either one you’ve built or one from someone else.
If you’re coding your own app, Coolify can auto-build the image from a Dockerfile or Docker Compose file, though this resource-heavy process requires a capable server.
Alternatively, you can build the image elsewhere, push it to a registry, and let Coolify deploy it as a container.
## Reverse Proxy
A reverse proxy is a server or app that sits between your application and users, forwarding requests to the right place.
Coolify includes two proxy options, Caddy and Traefik, which handle requests to your website by directing them to the container running your app.
This setup lets you run multiple applications on one server without tweaking configs or ports.
Plus, Coolify supports unlimited domains, so you could deploy 20 different apps, each with its own unique domain.
The reverse proxy also automatically manages SSL/TLS certificates for your applications. When you enter a domain with `https://`, the proxy requests and installs certificates from [Let's Encrypt](https://letsencrypt.org?utm_source=coolify.io) automatically, with no manual configuration needed. Certificates are renewed automatically before they expire, keeping your applications secure without any intervention.
## Security
Coolify doesn’t manage your server’s security or updates, that’s your responsibility to keep everything secure and up to date.
It’s built to simplify deployment management for you. While the Coolify core team plans to introduce more security features eventually, for now, securing your server is entirely up to you.
## Teams
Coolify supports multiple users and teams, allowing each team to have its own projects and environments.
You can assign roles like admin to users, simplifying project management and collaboration on a single server.
Currently, the teams feature isn’t fully polished for production use, but the Coolify core team plans to enhance it down the line.
content/docs/get-started/contribute/coolify.mdx
+282
View File
@@ -0,0 +1,282 @@
---
title: Contributing to Core Coolify
description: Contribute to Coolify open-source development with step-by-step setup guide, Docker environment, Spin commands, and pull request workflow.
---
# Contributing to Coolify
> "First, thanks for considering contributing to my project. It really means a lot!" - [@andrasbacsai](https://github.com/andrasbacsai)
You can ask for guidance anytime on our [Discord Community Server](https://coollabs.io/discord) in the `#contribute` channel.
To understand the tech stack, please refer to the [Tech Stack](https://github.com/coollabsio/coolify/blob/main/TECH_STACK.md) document.
## Table of Contents
1. [Setup Development Environment](#_1-setup-development-environment)
2. [Verify Installation](#_2-verify-installation-optional)
3. [Fork and Setup Local Repository](#_3-fork-and-setup-local-repository)
4. [Set up Environment Variables](#_4-set-up-environment-variables)
5. [Start Coolify](#_5-start-coolify)
6. [Start Development](#_6-start-development)
7. [Create a Pull Request](#_7-create-a-pull-request)
8. [Development Notes](#development-notes)
9. [Resetting Development Environment](#resetting-development-environment)
10. [Additional Contribution Guidelines](#additional-contribution-guidelines)
## 1. Setup Development Environment
Follow the steps below for your operating system:
<details>
<summary><strong>Windows</strong></summary>
1. Install `docker-ce`, Docker Desktop (or similar):
- Docker CE (recommended):
- Install Windows Subsystem for Linux v2 (WSL2) by following this guide: [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install?ref=coolify)
- After installing WSL2, install Docker CE for your Linux distribution by following this guide: [Install Docker Engine](https://docs.docker.com/engine/install/?ref=coolify)
- Make sure to choose the appropriate Linux distribution (e.g., Ubuntu) when following the Docker installation guide
- Install Docker Desktop (easier):
- Download and install [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/?ref=coolify)
- Ensure WSL2 backend is enabled in Docker Desktop settings
2. Install Spin:
- Follow the instructions to install Spin on Windows from the [Spin documentation](https://serversideup.net/open-source/spin/docs/installation/install-windows#download-and-install-spin-into-wsl2?ref=coolify)
</details>
<details>
<summary><strong>MacOS</strong></summary>
1. Install Orbstack, Docker Desktop (or similar):
- Orbstack (recommended, as it is a faster and lighter alternative to Docker Desktop):
- Download and install [Orbstack](https://docs.orbstack.dev/quick-start#installation?ref=coolify)
- Docker Desktop:
- Download and install [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/?ref=coolify)
2. Install Spin:
- Follow the instructions to install Spin on MacOS from the [Spin documentation](https://serversideup.net/open-source/spin/docs/installation/install-macos/#download-and-install-spin?ref=coolify)
</details>
<details>
<summary><strong>Linux</strong></summary>
1. Install Docker Engine, Docker Desktop (or similar):
- Docker Engine (recommended, as there is no VM overhead):
- Follow the official [Docker Engine installation guide](https://docs.docker.com/engine/install/?ref=coolify) for your Linux distribution
- Docker Desktop:
- If you want a GUI, you can use [Docker Desktop for Linux](https://docs.docker.com/desktop/install/linux-install/?ref=coolify)
2. Install Spin:
- Follow the instructions to install Spin on Linux from the [Spin documentation](https://serversideup.net/open-source/spin/docs/installation/install-linux#configure-docker-permissions?ref=coolify)
</details>
## 2. Verify Installation (Optional)
After installing Docker (or Orbstack) and Spin, verify the installation:
1. Open a terminal or command prompt
2. Run the following commands:
```bash
docker --version
spin --version
```
You should see version information for both Docker and Spin.
## 3. Fork and Setup Local Repository
1. Fork the [Coolify](https://github.com/coollabsio/coolify) repository to your GitHub account.
2. Install a code editor on your machine (choose one):
| Editor | Platform | Download Link |
|--------|----------|---------------|
| Visual Studio Code (recommended free) | Windows/macOS/Linux | [Download](https://code.visualstudio.com/download?ref=coolify) |
| Cursor (recommended but paid) | Windows/macOS/Linux | [Download](https://www.cursor.com/?ref=coolify) |
| Zed (very fast) | Windows/macOS/Linux | [Download](https://zed.dev/download?ref=coolify) |
3. Clone the Coolify Repository from your fork to your local machine
- Use `git clone` in the command line, or
- Use GitHub Desktop (recommended):
- Download and install from [https://desktop.github.com/](https://desktop.github.com/?ref=coolify)
- Open GitHub Desktop and login with your GitHub account
- Click on `File` -> `Clone Repository` select `github.com` as the repository location, then select your forked Coolify repository, choose the local path and then click `Clone`
4. Open the cloned Coolify Repository in your chosen code editor.
## 4. Set up Environment Variables
1. In the Code Editor, locate the `.env.development.example` file in the root directory of your local Coolify repository.
2. Duplicate the `.env.development.example` file and rename the copy to `.env`.
3. Open the new `.env` file and review its contents. Adjust any environment variables as needed for your development setup.
4. If you encounter errors during database migrations, update the database connection settings in your `.env` file. Use the IP address or hostname of your PostgreSQL database container. You can find this information by running `docker ps` after executing `spin up`.
5. Save the changes to your `.env` file.
## 5. Start Coolify
1. Open a terminal in the local Coolify directory.
2. Run the following command in the terminal (leave that terminal open):
```bash
spin up
```
<Callout type="warn" title="Note:">
You may see some errors, but don't worry this is expected.
</Callout>
3. If you encounter permission errors, especially on macOS, use:
```bash
sudo spin up
```
<Callout type="warn" title="Note:">
If you change environment variables afterwards or anything seems broken, press Ctrl + C to stop the process and run `spin up` again.
</Callout>
## 6. Start Development
1. Access your Coolify instance:
- URL: `http://localhost:8000`
- Login: `test@example.com`
- Password: `password`
2. Additional development tools:
| Tool | URL | Note |
|------|-----|------|
| Laravel Horizon (scheduler) | `http://localhost:8000/horizon` | Only accessible when logged in as root user |
| Mailpit (email catcher) | `http://localhost:8025` | |
| Telescope (debugging tool) | `http://localhost:8000/telescope` | Disabled by default |
<Callout type="info" title="Tip:">
To enable Telescope, add the following to your `.env` file:
```yaml
TELESCOPE_ENABLED=true
```
</Callout>
## 7. Create a Pull Request
1. After making changes or adding a new service:
- Commit your changes to your forked repository.
- Push the changes to your GitHub account.
2. Creating the Pull Request (PR):
- Navigate to the main Coolify repository on GitHub.
- Click the "Pull requests" tab.
- Click the green "New pull request" button.
- Choose your fork and branch as the compare branch.
- Click "Create pull request".
3. Filling out the PR details:
- Give your PR a descriptive title.
- Use the Pull Request Template provided and fill in the details.
<Callout type="error" title="IMPORTANT">
Always set the base branch for your PR to the `next` branch of the Coolify repository, not the `v4.x` branch.
</Callout>
4. Submit your PR:
- Review your changes one last time.
- Click "Create pull request" to submit.
<Callout type="warn" title="Note:">
Make sure your PR is out of draft mode as soon as it's ready for review. PRs that are in draft mode for a long time may be closed by maintainers.
</Callout>
After submission, maintainers will review your PR and may request changes or provide feedback.
## Development Notes
When working on Coolify, keep the following in mind:
1. **Database Migrations**: After switching branches or making changes to the database structure, always run migrations:
```bash
docker exec -it coolify php artisan migrate
```
2. **Resetting Development Setup**: To reset your development setup to a clean database with default values:
```bash
docker exec -it coolify php artisan migrate:fresh --seed
```
3. **Troubleshooting**: If you encounter unexpected behavior, ensure your database is up-to-date with the latest migrations and if possible reset the development setup to eliminate any environment-specific issues.
<Callout type="error" title="IMPORTANT:">
Forgetting to migrate the database can cause problems, so make it a habit to run migrations after pulling changes or switching branches.
</Callout>
## Resetting Development Environment
If you encounter issues or break your database or something else, follow these steps to start from a clean slate (works since `v4.0.0-beta.342`):
1. Stop all running containers `ctrl + c`.
2. Remove all Coolify containers:
```bash
docker rm coolify coolify-db coolify-redis coolify-realtime coolify-testing-host coolify-minio coolify-vite-1 coolify-mail
```
3. Remove Coolify volumes (it is possible that the volumes have no `coolify` prefix on your machine, in that case remove the prefix from the command):
```bash
docker volume rm coolify_dev_backups_data coolify_dev_postgres_data coolify_dev_redis_data coolify_dev_coolify_data coolify_dev_minio_data
```
4. Remove unused images:
```bash
docker image prune -a
```
5. Start Coolify again:
```bash
spin up
```
6. Run database migrations and seeders:
```bash
docker exec -it coolify php artisan migrate:fresh --seed
```
After completing these steps, you'll have a fresh development setup.
<Callout type="error" title="IMPORTANT">
Always run database migrations and seeders after switching branches or pulling updates to ensure your local database structure matches the current codebase and includes necessary seed data.
</Callout>
## Additional Contribution Guidelines
### Contributing a New Service
To add a new service to Coolify, please refer to our documentation: [Adding a New Service](/get-started/contribute/service)
### Contributing to Documentation
To contribute to the Coolify documentation, please refer to this guide: [Contributing to the Coolify Documentation](/get-started/contribute/documentation)
content/docs/get-started/contribute/documentation.mdx
+96
View File
@@ -0,0 +1,96 @@
---
title: "Contributing to Coolify Documentation"
description: Contribute to Coolify docs with this guide covering repository setup, local development with Bun, image guidelines, and pull request workflow.
---
# Coolify Docs Contribution Guide
This guide outlines the process for contributing updates and fixes to our docs. Please follow the steps below to ensure a smooth and efficient workflow.
## 1. Repository Workflow
- **Release Process:**
We follow a weekly production release cycle. The **main** branch represents production, while the **next** branch is used as our development branch.
- **Branching Guidelines:**
- **Do not create pull requests (PRs) to the main branch.**
- All contributions should be made to the **next** branch.
- **Clone the repository from the next branch** to your GitHub account, then start working on your changes.
## 2. Getting Started
### Step 1: Fork and Clone the Repository
- First fork the docs repository to your github account, then clone your fork to your local system using:
```bash
git clone https://github.com/your-username/your-repo-name.git
```
- Navigate to the cloned repository:
```bash
cd your-repo-name
```
### Step 2: Install Dependencies and Run the Dev Server
We use [bun](https://bun.sh/) as our preferred package manager for local development. If you choose to use a different package manager, please **do not include its configuration files** in your commit.
To set up your environment, run:
```bash
bun install && bun run dev
```
The development server will start on `localhost` at port `5173`. You can view the documentation by navigating to:
```bash
http://localhost:5173/docs/
```
## 3. Image Guidelines
- **Format:**
All images used in the documentation must be in `.webp` format.
- **Location:**
Place all image files in the `/docs/public` directory.
- **Usage:**
Use the Zoomable image component on the docs to attach your images
```text
<ZoomableImage src="path-to-the-image.webp" alt="Path To The Image" />
```
## 4. Writing and Structuring Content
### Best Practices for Documentation:
- **Clear and Simple Language:**
Use plain and easily understandable English. Remember that not all readers are native English speakers.
- **Beginner-Friendly Guides:**
Break down instructions into small, easy-to-follow steps. Include screenshots wherever possible to help visualize the process, especially for users new to self-hosting or Coolify.
- **Content Organization:**
Structure your content with clear headings, bullet points, and numbered steps where applicable. This makes it easier for readers to follow along.
## 5. Submitting Your Contribution
1. **Commit your changes to your repository**
2. **Create a Pull Request:**
- Open a pull request (PR) to merge your changes into the **next** branch on the docs repository.
- Provide a detailed description of your updates to help maintainers review your contribution effectively.
## 6. Questions and Support
If you have any questions or run into issues while contributing:
- **Create an Issue:** Open an issue on the repository detailing your issue.
- **Discord:** Reach out to us on contribute channel on the [Coolify Discord community](https://coolify.io/discord).
## 7. Important Notes
- **Documentation Updates:**
The current docs are bit outdated and missing some information. The docs maintainers are actively rewriting parts of the documentation to improve structure and clarity before new content is added.
- **PR Approval:**
Merging of your PR is subject to review by the maintainers. Please be patient as they work through the process.
We appreciate your contribution and effort in making the Coolify docs better for everyone.
content/docs/get-started/contribute/meta.json
+8
View File
@@ -0,0 +1,8 @@
{
"title": "Contribute",
"pages": [
"coolify",
"service",
"documentation"
]
}
content/docs/get-started/contribute/service.mdx
+208
View File
@@ -0,0 +1,208 @@
---
title: "Add a new service template to Coolify"
description: Add new service templates to Coolify using Docker Compose with magic environment variables, storage handling, and one-click deployment features.
---
# Adding a new service template to Coolify
Services in Coolify are templates made from normal [docker-compose](https://docs.docker.com/reference/compose-file/) files with some added Coolify magic.
<Callout type="error" title="IMPORTANT">
The service’s Git repository must have at least 1,000 stars to be added to Coolify as a one click service.
</Callout>
<Callout type="info">
See [Coolify's docker-compose specs](/knowledge-base/docker/compose#coolify-s-magic-environment-variables) to learn more about Coolify's magic and how to benefit from generated variables and storage handling. Please use this magic when submitting your PR to make the merging process smoother.
</Callout>
1. Add metadata
At the top of your `docker-compose` file, add the following metadata:
```yaml
# documentation: https://docs.example.com/
# slogan: A brief description of your service
# category: One word, broad app type
# tags: tag1,tag2,tag3
# logo: svgs/your-service.svg
# port: 1234
```
- `documentation`: Link to the service's official documentation
- `slogan`: A short description of the service
- `category`: A one word broad app type
- `tags`: Comma-separated list for better searchability
- `logo`: Path to the service's logo (see step 3)
- `port`: The main entrypoint port of the service
<Callout type="warn" title="Caution">
Always specify a port, as Caddy Proxy cannot automatically determine the service's port.
</Callout>
2. Create the docker-compose file
Below the metadata, add your docker-compose configuration. Use Coolify's environment variable magic [here](/knowledge-base/docker/compose#coolifys-magic-environment-variables).
Example:
```yaml
services:
app:
image: your-service-image:tag
environment:
- DATABASE_URL=${COOLIFY_DATABASE_URL}
volumes:
- ${COOLIFY_VOLUME_APP}:/data
```
**Using Required Environment Variables:**
When creating service templates, mark critical configuration as required to improve user experience:
```yaml
services:
app:
image: your-service:latest
environment:
# Required - critical configuration that must be set by the user
- DATABASE_URL=${DATABASE_URL:?}
- API_KEY=${API_KEY:?}
# Required with sensible defaults - improves usability
- PORT=${PORT:?8080}
- LOG_LEVEL=${LOG_LEVEL:?info}
# Optional - features that can be left empty
- DEBUG=${DEBUG:-false}
- CACHE_TTL=${CACHE_TTL:-3600}
```
This helps users understand which configuration is essential and prevents deployment failures.
3. Add a logo
- Create or obtain an SVG logo for your service (strongly preferred format)
- If SVG is unavailable, use a high-quality.webp or JPG as a last resort
- Add the logo file to the `svgs` folder in the Coolify repository
- The logo filename should match the docker-compose service name exactly
- For example, if your service name is `wordpress`, your logo should be `wordpress.svg` and the final path then is `svgs/wordpress.svg` use this path in the `logo` metadata.
4. Test your template
Use the `Docker Compose Empty` deployment option in Coolify to test your template. This process mimics the one-click service deployment.
5. Submit a Pull Request
Once your template works correctly:
- Open a [PR](https://github.com/coollabsio/coolify/compare)
- Add your new `<service>.yaml` compose file under `/templates/compose`
- Include the logo file in the `svgs` folder
<Callout type="info">
Coolify uses a [parsed version](https://github.com/coollabsio/coolify/blob/main/templates/service-templates.json) of the templates for deployment.
</Callout>
## Adding a new service template to the Coolify Documentation
Once your service template is merged into Coolify, it will be important to also add documentation for it in the Coolify docs.
In the [Coolify Docs Contribute section](/get-started/contribute/documentation) we explain how to contribute and run the documentation on your own PC.
<Callout type="info" title="HOW THE SERVICE LIST IS BUILT">
The services overview page and the [All Services](/services/all) directory are **generated automatically** from the frontmatter of each markdown file in `docs/services/`. You do **not** need to edit `List.vue` or `all.md` manually anymore. The generators run as part of `bun run dev`, `bun run build`, and `bun run preview`.
- `scripts/generate-service-list.mjs` → writes `src/generated/services.json` (consumed by the services overview component)
- `scripts/generate-services-page.mjs` → writes `docs/services/all.md`
- Both scripts share `scripts/services-data.mjs`, which parses each service's frontmatter and resolves its logo from `docs/public/images/services/`
</Callout>
As soon as you have your local setup ready, follow these steps to add your new service:
1. Add the service logo under `/docs/public/images/services/`
- Use the same base name as your service slug, e.g. `my-service.svg` or `my-service-logo.svg`. The icon resolver tries `<slug>-logo`, `<slug>_logo`, `<slug>logo`, then bare `<slug>`, then the same variants based on the title.
- Prefer SVG; otherwise WebP, then PNG. Avoid JPEG for logos.
2. Create the documentation file
Create `/docs/services/<service-slug>.md`. The slug must be lowercase and kebab-case, and must match the filename. Use this frontmatter:
```yaml
---
title: "Service Name"
description: "Short description that appears on the service card and search results."
og:
description: "SEO/social-card description (optional, longer than `description`)."
category: "Analytics"
icon: "/docs/images/services/service-name-logo.svg"
---
```
| Field | Required | Notes |
|---|---|---|
| `title` | yes | Display name shown on the card |
| `description` | yes | Used as the card description and in `all.md` |
| `category` | yes | Determines the heading the service appears under in `all.md` and the filter in the overview |
| `icon` | optional | Only set if auto-resolution can't find your logo |
| `og.description` | optional | Longer description used for social/SEO meta tags |
| `disabled` | optional | Set to `true` to hide the service from the listing while keeping the page reachable by direct URL |
3. Write the documentation
Start writing your documentation under the frontmatter. Use the following template as a starting point:
```text
# Service Name
![Service Name](/docs/images/services/service-name-logo.svg)
## What is Service Name?
Brief description and use cases.
## Links
- [Official website](https://example.com?utm_source=coolify.io)
- [GitHub](https://github.com/example/repo?utm_source=coolify.io)
```
Use `<ZoomImage>` only for screenshots that benefit from a zoomable view, not for the logo.
4. Regenerate the listings (optional — happens automatically on `dev`/`build`)
```bash
bun run generate:services
```
This refreshes `src/generated/services.json` and `docs/services/all.md`. Commit both regenerated files alongside your new service page.
5. Submit a Pull Request
- Target the `next` branch
- Verify the service renders correctly with `bun run dev`, including the listing card, the filter category, and the entry in `/services/all`
# Request a new service
If there's a service template you'd like to see in Coolify:
1. Search [GitHub discussions](https://github.com/coollabsio/coolify/discussions/categories/service-template-requests) for existing requests.
2. If the service has been requested, upvote it. If not, create a new request.
content/docs/get-started/dev.mdx
+51
View File
@@ -0,0 +1,51 @@
---
title: Coolify Concepts
description: Learn core Coolify concepts including servers, resources, environments, projects, Docker containers, reverse proxy, and team management basics.
---
<Callout type="info" title="Title here">
This draws attention to important information
</Callout>
<Callout type="warn" title="Title here">
This draws attention to important information
</Callout>
<Callout type="error" title="Title here">
This draws attention to important information
</Callout>
<Callout type="success" title="Title here">
This draws attention to important information
</Callout>
<Callout type="info" title="Title here">
This draws attention to important information
</Callout>
<Callout type="info" title="Title here">
This draws attention to important information
</Callout>
content/docs/get-started/downgrade.mdx
+89
View File
@@ -0,0 +1,89 @@
---
title: Downgrading Coolify
description: Downgrade self-hosted Coolify to previous versions by disabling auto-update, using SSH terminal commands, and handling database compatibility risks.
---
<ZoomImage src="/docs/images/get-started/downgrade-banner.webp" alt="Coolify downgrade banner" />
<br />
If you're using [Coolify Cloud](https://coolify.io/pricing/), the Coolify team handles all updates so you **cannot** downgrade the version of Coolify. If you are facing any issues, please contact [support](/get-started/support).
For those who **self-host** Coolify, you can easily downgrade to the previous version. Follow the steps below to perform a downgrade on to a previous version.
<Callout type="error" title="Backup First!">
- Always back up your Coolify data before performing an downgrade.
- Downgrading can introduce issues that can be difficult to fix.
</Callout>
The Downgrade process involves the following three steps:
- [Disable Auto Update](#_1-disable-auto-update)
- [Login to Your Server via SSH](#_2-login-to-your-server-via-ssh)
- [Execute the Downgrade Command](#_3-execute-the-downgrade-command)
## 1. Disable Auto Update
Before downgrading, it's important to disable the Auto Update feature to prevent Coolify from automatically upgrading again after you perform the downgrade.
1. Log in as the root user (or any user who has access to the root or initial team).
2. Navigate to the Settings menu in your Coolify dashboard.
3. In the Settings menu, disable the **Auto Update** feature.
<ZoomImage src="/docs/images/get-started/upgrade/disable-auto-update.webp" alt="Disable Auto Update" />
<Callout type="warn" title="Important!">
Disabling auto-update is essential, as it ensures that Coolify doesn’t override your downgrade with a newer version.
</Callout>
## 2. Login to Your Server via SSH
Next, you need to SSH into your server to execute the downgrade command.
## 3. Execute the Downgrade Command
To downgrade Coolify to the desired version, run the following command in your terminal:
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash -s 4.0.0-beta.369
```
Replace `4.0.0-beta.369` with the version number you want to downgrade to.
For example, you can downgrade to `4.0.0-beta.333` or any previous version.
<Callout type="warn" title="Note">
Double-check the version number you are specifying to ensure you are downgrading to the correct version. You can check the Coolify [release notes](https://github.com/coollabsio/coolify/releases) for version details.
</Callout>
## Potential Issues with Downgrading
While downgrading is possible, be aware of the following risks:
- [Database Schema Compatibility](#database-schema-compatibility)
- [Feature Incompatibility](#feature-incompatibility)
---
#### Database Schema Compatibility:
Downgrading can cause issues since the database schema may not be backward compatible. Some features may not work as expected due to changes in the database structure between versions.
#### Feature Incompatibility:
Some features might not function properly after downgrading, as certain features in the newer version may rely on changes that are not present in the older version.
content/docs/get-started/installation.mdx
+464
View File
@@ -0,0 +1,464 @@
---
title: Installation
description: Install Coolify self-hosted PaaS on Linux servers with automated Docker setup script, manual configuration, SSH access, and firewall setup.
outline: 2
---
<ZoomImage src="/docs/images/get-started/installation-banner.webp" alt="Coolify installation banner" />
<br />
If you decide to go with **Coolify Cloud**, there's no installation required. Simply visit [Coolify Cloud Registration](https://app.coolify.io/register) to create an account and start using Coolify within minutes!
Below, you'll find instructions for installing Coolify if you prefer to **self-host** it.
## Self-hosted Installation
If you like taking control and managing everything yourself, self-hosting Coolify is the way to go.
It's completely free (apart from your server costs) and gives you full control over your setup.
<Callout type="success" title="Quick Installation (recommended):">
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash
```
Run this script in your terminal, and Coolify will be installed automatically. For more details, including firewall configuration and prerequisites, check out the guide below.
</Callout>
<Callout type="warn" title="Note for Ubuntu Users:">
The automatic installation script only works with Ubuntu LTS versions (20.04, 22.04, 24.04). If you're using a non-LTS version (e.g., 24.10), please use the [Manual Installation](#manual-installation) method below.
</Callout>
## Before You Begin
Before installing Coolify, make sure your server meets the necessary requirements.
### 1. Server Requirements
You need a server with SSH access. This could be:
- A VPS (Virtual Private Server)
- A Dedicated Server
- A Virtual Machine (VM)
- A Raspberry Pi (see our [Raspberry Pi OS Setup Guide](/knowledge-base/how-to/raspberry-pi-os#prerequisites))
- Or any other server with SSH access
<Callout type="warn" title="Note:">
It’s best to use a fresh server for Coolify to avoid any conflicts with existing applications.
</Callout>
<Callout type="info" title="Tip:">
If you haven't picked a server provider yet, consider using [Hetzner](https://coolify.io/hetzner). You can even use our [referral link](https://coolify.io/hetzner) to support the project.
</Callout>
### 2. Supported Operating Systems
Coolify supports several Linux distributions:
- Debian-based (e.g., Debian, Ubuntu - all versions supported, but non-LTS Ubuntu requires manual installation)
- Redhat-based (e.g., CentOS, TencentOS, Fedora, Redhat, AlmaLinux, Rocky, Asahi)
- SUSE-based (e.g., SLES, SUSE, openSUSE)
- Arch Linux (Note: Not all Arch derivatives are supported)
- Alpine Linux
- Raspberry Pi OS 64-bit (Raspbian)
<Callout type="info" title="Note">
For some distros (like AlmaLinux), Docker must be pre-installed. If the install script fails, manually install Docker and re-run the script.
Other Linux distributions may work with Coolify, but have not been officially tested.
</Callout>
### 3. Supported Architectures
Coolify runs on 64-bit systems:
- AMD64
- ARM64
<Callout type="warn" title="Note for Raspberry Pi users:">
Be sure to use the 64-bit version of Raspberry Pi OS (Raspbian). For details, check our [Raspberry Pi OS Setup Guide](/knowledge-base/how-to/raspberry-pi-os#prerequisites).
</Callout>
### 4. Minimum Hardware Requirements
Your server should have at least:
- **CPU**: 2 cores
- **Memory (RAM)**: 2 GB
- **Storage**: 30 GB of free space
Coolify may function properly on servers with lower specs than those mentioned above, but we recommend slightly higher minimum requirements.
This ensures that users have sufficient resources to deploy multiple applications without performance issues.
<Callout type="warn" title="Heads up!">
If you’re running both builds and Coolify on the same server, monitor your resource usage. High resource usage could make your server unresponsive.
Consider enabling swap space or upgrading your server if needed.
</Callout>
### 5. Server Resources for Your Projects
The resources you need depend on your projects. For example, if you're hosting multiple services or larger applications, choose a server with higher CPU, memory, and storage.
<Callout type="success" title="⚙️ Example Setup:">
Andras runs his production apps on a server with:
- **Memory**: 8GB (average usage: 3.5GB)
- **CPU**: 4 cores (average usage: 20–30%)
- **Storage**: 150GB (average usage: 40GB)
This setup comfortably supports:
- 3 NodeJS apps
- 4 Static sites
- Plausible Analytics
- Fider (feedback tool)
- UptimeKuma (uptime monitoring)
- Ghost (newsletters)
- 3 Redis databases
- 2 PostgreSQL databases
</Callout>
## Installation Methods
There are two ways to install Coolify:
- [Quick Installation](#quick-installation-recommended) (Recommended)
- [Manual Installation](#manual-installation)
We highly recommend the **Quick Installation** method as it automates the process and reduces the chance of errors.
---
### Quick Installation (Recommended)
This is the simplest and fastest way to get Coolify up and running.
#### 1. Prepare Your Server
- Log in as the root user (non-root users are not fully supported yet).
- Configure SSH by following the [SSH Settings Guide](/knowledge-base/server/openssh#ssh-settings-configuration).
- Set up your firewall with the help of the [Firewall Guide](/knowledge-base/server/firewall).
- Ensure that [curl](https://curl.se/) is installed (it usually comes pre-installed).
#### 2. Run the Installation Script
Once your server is ready, run:
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
```
View the [Script's Source Code](https://github.com/coollabsio/coolify/blob/main/scripts/install.sh)
<Callout type="info" title="Tip:">
If you're not logged in as the root user, run the script with sudo:
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash
```
</Callout>
#### Advanced: Customizing Installation with Environment Variables
The installation script supports several environment variables to customize your Coolify installation. These are completely optional.
<details>
<summary>Click to view all available environment variables</summary>
You can set these environment variables before running the installation script to customize your Coolify setup:
| Environment Variable | Description | Default Value | Example |
| ---------------------------- | ----------------------------------------------------- | ------------- | -------------------- |
| `ROOT_USERNAME` | Predefined root username for first admin account | - | `admin` |
| `ROOT_USER_EMAIL` | Predefined root user email for first admin account | - | `admin@example.com` |
| `ROOT_USER_PASSWORD` | Predefined root user password for first admin account | - | `SecurePassword123!` |
| `DOCKER_ADDRESS_POOL_BASE` | Custom Docker address pool base (CIDR notation) | `10.0.0.0/8` | `172.16.0.0/12` |
| `DOCKER_ADDRESS_POOL_SIZE` | Custom Docker address pool size (must be 16-28) | `24` | `20` |
| `DOCKER_POOL_FORCE_OVERRIDE` | Force override existing Docker pool configuration | `false` | `true` |
| `AUTOUPDATE` | Enable/disable automatic Coolify updates | `true` | `false` |
| `REGISTRY_URL` | Custom Docker registry URL for Coolify images | `ghcr.io` | `your-registry.com` |
**Usage Examples:**
**1. Create Admin Account During Installation:**
```bash
env ROOT_USERNAME=admin \
ROOT_USER_EMAIL=admin@example.com \
ROOT_USER_PASSWORD=SecurePassword123 \
bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
See the [Create Root User with Environment Variables](/knowledge-base/create-root-user-with-env) guide for more details.
**2. Custom Docker Network Pool:**
```bash
env DOCKER_ADDRESS_POOL_BASE=172.16.0.0/12 \
DOCKER_ADDRESS_POOL_SIZE=20 \
bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
See the [Define Custom Docker Network with ENV](/knowledge-base/define-custom-docker-network-with-env) guide for more details.
**3. Disable Auto-Updates:**
```bash
env AUTOUPDATE=false \
bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
**4. Use Custom Docker Registry:**
```bash
env REGISTRY_URL=your-registry.com \
bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
When using a custom registry, make sure all required Coolify images are available in your registry.
**5. Combine Multiple Variables:**
```bash
env ROOT_USERNAME=admin \
ROOT_USER_EMAIL=admin@example.com \
ROOT_USER_PASSWORD=SecurePassword123 \
AUTOUPDATE=false \
DOCKER_ADDRESS_POOL_BASE=172.16.0.0/12 \
bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
</details>
#### 3. Access Coolify
After installation, the script will display your Coolify URL (e.g., `http://203.0.113.1:8000`). Visit this URL, and you'll be redirected to a registration page to create your first admin account.
<Callout type="error" title="CAUTION:">
**Immediately create your admin account after installation. If someone else accesses the registration page before you, they might gain full control of your server.**
</Callout>
<Callout type="info" title="Note:">
If you installed Coolify on a Raspberry Pi within your home network, use your private IP address to access it, as the public IP may not work.
</Callout>
#### What the Installer Does:
- Installs essential tools (curl, wget, git, jq, openssl)
- Installs Docker Engine (version 24+)
- Configures Docker settings (logging, daemon)
- Sets up directories at `/data/coolify`
- Configures SSH keys for server management
- Installs and starts Coolify
<Callout type="warn" title="Caution:">
Docker installed via snap is not supported!
</Callout>
**The quick installation guide ends here. If you’ve followed the steps above, you can start using Coolify now. The guide below is for those who want to manually install and set up Coolify.**
---
### Manual Installation
For those who prefer more control, you can install Coolify manually. This method requires a few extra steps.
<Callout type="info" title="Note">
This manual installation method is required for:
- Non-LTS Ubuntu versions (e.g., 24.10)
- Systems where the automatic script encounters issues
</Callout>
#### Prerequisites
- **SSH**: Ensure SSH is enabled and set up correctly (see [SSH Configuration Guide](/knowledge-base/server/openssh)).
- **curl**: Confirm that [curl](https://curl.se/) is installed.
- **Docker Engine**: Install Docker by following the official [Docker Engine Installation guide](https://docs.docker.com/engine/install/#server) (version 24+).
<Callout type="warn" title="Caution:">
Docker installed via snap is not supported!
</Callout>
---
Follow these steps for a manual setup:
#### 1. Create Directories
Create the base directories for Coolify under `/data/coolify`:
```bash
mkdir -p /data/coolify/{source,ssh,applications,databases,backups,services,proxy,webhooks-during-maintenance}
mkdir -p /data/coolify/ssh/{keys,mux}
mkdir -p /data/coolify/proxy/dynamic
```
#### 2. Generate & Add SSH Key
Generate an SSH key for Coolify to manage your server:
```bash
ssh-keygen -f /data/coolify/ssh/keys/id.root@host.docker.internal -t ed25519 -N '' -C root@coolify
```
Then, add the public key to your `~/.ssh/authorized_keys`:
```bash
cat /data/coolify/ssh/keys/id.root@host.docker.internal.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
```
<Callout type="info" title="Tip!">
If you already have an SSH key, you can skip generating a new one, but remember to add it to your Coolify instance after installation.
</Callout>
#### 3. Setup Configuration Files
Download the necessary files from Coolify’s CDN to `/data/coolify/source`:
```bash
curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml -o /data/coolify/source/docker-compose.yml
curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.prod.yml -o /data/coolify/source/docker-compose.prod.yml
curl -fsSL https://cdn.coollabs.io/coolify/.env.production -o /data/coolify/source/.env
curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh -o /data/coolify/source/upgrade.sh
```
#### 4. Set Permissions
Set the correct permissions for the Coolify files and directories:
```bash
chown -R 9999:root /data/coolify
chmod -R 700 /data/coolify
```
#### 5. Generate Values
Update the `.env` file with secure random values:
```bash
sed -i "s|APP_ID=.*|APP_ID=$(openssl rand -hex 16)|g" /data/coolify/source/.env
sed -i "s|APP_KEY=.*|APP_KEY=base64:$(openssl rand -base64 32)|g" /data/coolify/source/.env
sed -i "s|DB_PASSWORD=.*|DB_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
sed -i "s|REDIS_PASSWORD=.*|REDIS_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
sed -i "s|PUSHER_APP_ID=.*|PUSHER_APP_ID=$(openssl rand -hex 32)|g" /data/coolify/source/.env
sed -i "s|PUSHER_APP_KEY=.*|PUSHER_APP_KEY=$(openssl rand -hex 32)|g" /data/coolify/source/.env
sed -i "s|PUSHER_APP_SECRET=.*|PUSHER_APP_SECRET=$(openssl rand -hex 32)|g" /data/coolify/source/.env
```
<Callout type="warn" title="Important:">
Run these commands only the first time you install Coolify. Changing these values later can break your installation. Keep them safe!
</Callout>
#### 6. Create Docker Network
Ensure the Docker network is created:
```bash
docker network create --attachable coolify
```
#### 7. Start Coolify
Launch Coolify using Docker Compose:
```bash
docker compose --env-file /data/coolify/source/.env -f /data/coolify/source/docker-compose.yml -f /data/coolify/source/docker-compose.prod.yml up -d --pull always --remove-orphans --force-recreate
```
<Callout type="warn" title="Important:">
You might have to do `docker login` at this point if you have any issues above.
</Callout>
<Callout type="info">
You can customize Coolify's containers (ports, resource limits, labels, etc.) in a way that survives upgrades by creating a `docker-compose.custom.yml` file. See [Custom Compose Overrides](/knowledge-base/custom-compose-overrides) for details.
</Callout>
#### 8. Access Coolify
You can now access Coolify by visiting `http://203.0.113.1:8000` (replace the `203.0.113.1` with the IP address of your server).
If you get stuck at any step, feel free to join our [Discord community](https://coolify.io/discord) and create a post in the support forum channel.
content/docs/get-started/introduction.mdx
+96
View File
@@ -0,0 +1,96 @@
---
title: Introduction to Coolify
description: Coolify is an open-source self-hosted PaaS alternative to Vercel, Heroku, and Railway with unlimited deployments, no vendor lock-in, and free SSL.
outline: [2, 4]
lastUpdated: true
editLink: true
---
<ZoomImage src="/docs/images/get-started/introduction-banner.webp" alt="Coolify introduction banner" />
<br />
## What is Coolify?
Coolify is a software that makes self-hosting simple and powerful. It lets you run your applications, databases, and services on your own server, whether that’s an old laptop, a Raspberry Pi, or a rented server from a provider like [Hetzner](https://coolify.io/hetzner).
With Coolify, you get full control over your projects, your data, and your costs. It’s completely free to use, open-source, and has no features locked behind a paywall.
Think of Coolify as your personal alternative to cloud platforms like [Vercel](https://vercel.com?utm_source=coolify.io), [Railway](https://railway.com/?utm_source=coolify.io), or [Heroku](https://www.heroku.com/?utm_source=coolify.io), but without the huge bills or privacy trade-offs.
### What Coolify Is Not
Coolify isn’t a cloud service that hosts everything for you, you need your own server. That could be your old laptop, a Raspberry Pi, or a rented server from a hosting provider like [Hetzner](https://coolify.io/hetzner), and you’ll need SSH access to use it.
It’s not a zero-effort solution either, if you choose to self-host, you’ll need to set up your server and install Coolify. But once it’s running, managing your projects becomes very easy.
## Features of Coolify
Coolify is loaded with tools to make self-hosting smooth and powerful. Here’s a detailed look at what it offers:
| Features | Explanation |
| :------------------------ | :-------------------------------------------------------------------------------------------------------- |
| **Any Language** | Deploy static sites, APIs, backends, databases, and more with support for all major frameworks. |
| **Any Server** | Deploy to any server - VPS, Raspberry Pi, EC2, your laptop via SSH. |
| **Any Use-Case** | Supports single servers, multi-server setups, and Docker Swarm clusters (Kubernetes support coming soon). |
| **Any Service** | Deploy any Docker-compatible service, plus a wide range of one-click options. |
| **Push to Deploy** | Git integration with GitHub, GitLab, Bitbucket, Gitea, and other platforms. |
| **Free SSL Certificates** | Automatically sets up and renews Let's Encrypt SSL certificates for custom domains. |
| **No Vendor Lock-In** | Your data and settings stay on your servers for full control and easy portability. |
| **Automatic Backups** | Back up data to S3-compatible storage and restore it with one click if needed. |
| **Webhooks** | Integrate with CI/CD tools like GitHub Actions, GitLab CI, or Bitbucket Pipelines. |
| **Powerful API** | Automate deployments, manage resources, and integrate with your existing tools easily. |
| **Real-Time Terminal** | Run server commands directly from your browser in real-time. |
| **Collaborative** | Share projects with your team, control roles, and manage permissions. |
| **PR Deployments** | Deploy commits and pull requests separately for quick reviews and faster teamwork. |
| **Server Automations** | Handles server setup tasks automatically after connection, saving you time. |
| **Monitoring** | Monitor deployments, servers, disk usage, and receive alerts for issues. |
## Benefits of Using Coolify
Coolify delivers unbeatable advantages for developers who want to self-host. Here’s why it stands out:
| Benefits | Explanation |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cost Savings** | Avoid skyrocketing cloud costs. Use your own server for a steady, predictable price. |
| **No Hidden Costs** | Transparent pricing with no unexpected charges. |
| **Highly Cost-Efficient** | Save thousands monthly compared to traditional cloud platforms. Real examples can be found [here](https://twitter.com/heyandras/status/1742078215986860460), [here](https://twitter.com/heyandras/status/1752209429276086688), and [here](https://twitter.com/heyandras/status/1724510876256944244) |
| **Complete Data Privacy** | Your data stays on your server, ensuring total control and security. |
| **No Feature Restrictions** | All features are included in the open-source version—nothing locked behind a paywall. |
| **Unlimited Usage** | Deploy unlimited websites and applications across any number of servers. |
| **Quick Setup** | Start hosting in minutes with minimal maintenance required. |
| **User-Friendly Interface** | Manage your infrastructure through a clean, simple dashboard designed for developers. |
| **100% Open Source** | Review the code, contribute to development, and help shape the platform’s future. |
| **Active Community** | Join over 16,000 people on Discord and 204,000+ servers running Coolify worldwide. |
## Getting Started with Coolify
Before you jump into using Coolify, it’s worth understanding a few key concepts to make your journey smoother.
Learn about servers, SSH access, and how Coolify manages your projects by checking out our [concepts guide](/get-started/concepts).
You have two ways to use Coolify:
- [Self-Host Coolify](#self-host-coolify)
- [Use Coolify Cloud](#use-coolify-cloud)
---
### Self-Host Coolify
- Install Coolify on your own server. This requires setting up the server, installing Coolify, and handling updates yourself.
- You’ll also need to allocate some server resources to run Coolify.
- It’s completely free (except your server bills) and gives you full control over your infrastructure.
### Use Coolify Cloud
- Let the Coolify team manage Coolify for you.
- With Coolify Cloud, you don’t need to install or update Coolify yourself, and no server resources are required for Coolify itself, it runs on the Coolify team’s managed servers.
- Simply create an account from [here](https://app.coolify.io/register), connect your servers via SSH keys, and start deploying.
This is a paid service (starting at $5/mo), as it costs the team to host and maintain the infrastructure.
- Updates on Coolify Cloud are thoroughly tested by the core team, so they might be slightly delayed for added stability.
## Join Our Community
Got questions or need support? Our [discord community](https://coollabs.io/discord) is here to help.
Connect with other Coolify users on our community server to get assistance and share your experiences.
content/docs/get-started/meta.json
+19
View File
@@ -0,0 +1,19 @@
{
"title": "Get Started",
"pages": [
"introduction",
"installation",
"upgrade",
"downgrade",
"uninstallation",
"cloud",
"usage",
"concepts",
"screenshots",
"videos",
"team",
"support",
"sponsors",
"contribute"
]
}
content/docs/get-started/screenshots.mdx
+63
View File
@@ -0,0 +1,63 @@
---
title: Coolify UI Screenshots
description: View screenshots of Coolify's user interface showing dashboard, deployment options, server management, and application configuration features.
---
# Coolify UI Screenshots
The Coolify team is currently developing a brand new UI design. Below are the images showing the current UI.
<ZoomImage src="/docs/images/resources/screenshots/1.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/2.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/3.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/4.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/5.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/6.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/7.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/8.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/9.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/10.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/11.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/12.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/13.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/14.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/15.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/16.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/17.webp" alt="Coolify dashboard screenshot" />
<br />
<ZoomImage src="/docs/images/resources/screenshots/18.webp" alt="Coolify dashboard screenshot" />
content/docs/get-started/sponsors.mdx
+336
View File
@@ -0,0 +1,336 @@
---
layout: page
title: Coolify Sponsors
description: Meet the companies and organizations sponsoring Coolify development including Hetzner, Logto, Tolgee, and other technology partners.
---
# Coolify Sponsors
We have amazing sponsors who support the development of Coolify.
<div className="not-prose grid gap-4 sm:grid-cols-2 xl:grid-cols-3">
<a href="http://htznr.li/CoolifyXHetzner" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/hetzner.webp" alt="Hetzner logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Hetzner</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Server, cloud, hosting, and data center solutions</p>
</div>
</div>
</a>
<a href="https://logto.io/?ref=coolify" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/logto.webp" alt="Logto logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Logto</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">The better identity infrastructure for developers</p>
</div>
</div>
</a>
<a href="https://tolgee.io/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/tolgee.webp" alt="Tolgee logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Tolgee</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">The open source localization platform</p>
</div>
</div>
</a>
<a href="https://bc.direct/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/bc.webp" alt="Best Consultant logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Best Consultant</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Your trusted technology consulting partner</p>
</div>
</div>
</a>
<a href="https://www.quantcdn.io/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/quant.webp" alt="QuantCDN logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">QuantCDN</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Enterprise-grade content delivery network</p>
</div>
</div>
</a>
<a href="https://arcjet.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/arcjet.webp" alt="Arcjet logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Arcjet</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Advanced web security and performance solutions</p>
</div>
</div>
</a>
<a href="https://supa.guide/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/supaguide.webp" alt="SupaGuide logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">SupaGuide</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Your comprehensive guide to Supabase</p>
</div>
</div>
</a>
<a href="https://coderabbit.ai/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/coderabbit.webp" alt="CodeRabbit logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">CodeRabbit</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Cut Code Review Time & Bugs in Half</p>
</div>
</div>
</a>
<a href="https://convex.link/coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/convex.webp" alt="Convex logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Convex</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Open-source reactive database for web app developers</p>
</div>
</div>
</a>
<a href="https://billing.goldenvm.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/goldenvm.webp" alt="GoldenVM logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">GoldenVM</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Premium virtual machine hosting solutions</p>
</div>
</div>
</a>
<a href="https://www.tigrisdata.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/tigris.webp" alt="Tigris logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Tigris</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Modern developer data platform</p>
</div>
</div>
</a>
<a href="https://cloudify.ro/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/cloudify.webp" alt="Cloudify logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Cloudify</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Cloud hosting solutions</p>
</div>
</div>
</a>
<a href="https://trieve.ai/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/trieve.webp" alt="Trieve logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Trieve</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">AI-powered search and analytics</p>
</div>
</div>
</a>
<a href="https://blacksmith.sh/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/blacksmith.webp" alt="Blacksmith logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Blacksmith</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Infrastructure automation platform</p>
</div>
</div>
</a>
<a href="https://comit.international/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/comit.webp" alt="Comit International logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Comit International</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">New York Times award–winning contractor!</p>
</div>
</div>
</a>
<a href="https://brand.dev/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/branddev.webp" alt="Brand.dev logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Brand.dev</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">The #1 Brand API for B2B software startups</p>
</div>
</div>
</a>
<a href="https://syntax.fm?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/syntax.webp" alt="Syntax.fm logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Syntax.fm</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Podcast for web developers</p>
</div>
</div>
</a>
<a href="https://jobscollider.com/remote-jobs?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/jobscollider.webp" alt="Jobs Collider logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Jobs Collider</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">30,000+ remote jobs for developers</p>
</div>
</div>
</a>
<a href="https://www.hostinger.com/vps/coolify-hosting?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/hostinger.webp" alt="Hostinger logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Hostinger</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Web hosting and VPS solutions</p>
</div>
</div>
</a>
<a href="https://www.glueops.dev/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/glueops.webp" alt="GlueOps logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">GlueOps</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">DevOps automation and infrastructure management</p>
</div>
</div>
</a>
<a href="https://www.ubicloud.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/ubicloud.webp" alt="Ubicloud logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Ubicloud</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Open source cloud infrastructure platform</p>
</div>
</div>
</a>
<a href="https://pfglabs.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/pfglabs.webp" alt="Pfglabs logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Pfglabs</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Build Real Projects with Golang</p>
</div>
</div>
</a>
<a href="https://juxtdigital.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/juxtdigital.webp" alt="JuxtDigital logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">JuxtDigital</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Digital transformation and web solutions</p>
</div>
</div>
</a>
<a href="https://saasykit.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/saasykit.webp" alt="SaasyKit logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">SaasyKit</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Complete SaaS starter kit for developers</p>
</div>
</div>
</a>
<a href="https://massivegrid.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/massivegrid.webp" alt="MassiveGrid logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">MassiveGrid</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Enterprise cloud hosting solutions</p>
</div>
</div>
</a>
<a href="https://americancloud.com/?utm_source=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/americancloud.webp" alt="American Cloud logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">American Cloud</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">US-based cloud infrastructure services</p>
</div>
</div>
</a>
<a href="https://algora.io/?utm_source=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/algora.webp" alt="Algora logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Algora</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Open source contribution platform</p>
</div>
</div>
</a>
<a href="https://liquidweb.com/?utm_source=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/liquidweb.webp" alt="LiquidWeb logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">LiquidWeb</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Premium managed hosting solutions</p>
</div>
</div>
</a>
<a href="https://yaak.app/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/yaak.webp" alt="Yaak logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Yaak</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">The API client for modern developers</p>
</div>
</div>
</a>
<a href="https://www.trycomp.ai/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/comp.webp" alt="Comp AI logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Comp AI</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">The open-source platform that automates compliance</p>
</div>
</div>
</a>
<a href="https://darweb.nl/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/darweb.webp" alt="Darweb logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Darweb</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Design. Develop. Deliver. Specialized in 3D CPQ Solutions for eCommerce</p>
</div>
</div>
</a>
<a href="https://wz-it.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/wzit.webp" alt="WZ-IT logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">WZ-IT</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">German agency for customized cloud solutions, migration, managed services and open source hosting</p>
</div>
</div>
</a>
<a href="https://supadata.ai/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/supadata.webp" alt="Supadata logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Supadata</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Scrape YouTube, web, and files. Get AI-ready, clean data for your next project</p>
</div>
</div>
</a>
<a href="https://gozunga.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/gozunga.webp" alt="Gozunga logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Gozunga</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Seriously Simple Cloud Infrastructure</p>
</div>
</div>
</a>
<a href="https://macarne.com/?ref=coolify.io" className="rounded-lg border border-fd-border bg-fd-card p-4 no-underline transition hover:border-fd-primary/60 hover:bg-fd-muted/40">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/sponsors/macarne.webp" alt="Macarne logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Macarne</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Best IP Transit & Carrier Ethernet Solutions for Simplified Network Connectivity</p>
</div>
</div>
</a>
<div className="rounded-lg border border-fd-border bg-fd-card p-4">
<div className="flex min-w-0 items-center gap-4">
<img src="/docs/images/team/coollabs-logo-smaller.webp" alt="Your Company? logo" className="size-14 shrink-0 rounded-md object-contain" />
<div className="min-w-0">
<p className="m-0 font-semibold text-fd-foreground">Your Company?</p>
<p className="m-0 mt-1 text-sm leading-6 text-fd-muted-foreground">Will Your Company Be Next?</p>
</div>
</div>
</div>
</div>
content/docs/get-started/support.mdx
+25
View File
@@ -0,0 +1,25 @@
---
title: Support
description: Get Coolify support through Discord community with 19K+ members, direct email support for Cloud users, and core team developer assistance.
---
<ZoomImage src="/docs/images/get-started/support-banner.webp" alt="Coolify support banner" />
<br />
## Community Support
Join our [Discord community](https://coollabs.io/discord) with over **19K members**, where you can create a post in the **support forum channel** for assistance.
While the community does provide some help, the [Core team](/get-started/team) is actively involved in the forum to ensure questions are addressed.
## Direct Support from Core Developers
If you are a **Coolify Cloud user**, you can reach out via email at **hi@coollabs.io** for direct support from [Andras (Coolify’s founder)](https://x.com/heyandras). Since he personally handles emails, response times may be delayed.
We highly recommend posting in the **Discord support forum** first, as core team members can escalate issues to the developers ([Andras](https://x.com/heyandras) & [Peak](https://x.com/peaklabs_dev)) if necessary.
## Important Notes
- We are a **small team** (fewer than **6 people**) supporting **325K+ users**, making it challenging to offer direct assistance to everyone. However, we do our best to help as much as possible.
- We are planning a **paid support option** for **self-hosted users**. If you need dedicated support for your **self-hosted instance**, email **hi@coollabs.io** to discuss options.
content/docs/get-started/team.mdx
+16
View File
@@ -0,0 +1,16 @@
---
layout: page
title: coolLabs Team
description: Meet the international team developing Coolify including founder Andras Bacsai, core developers, community leads, and documentation maintainers.
---
# coolLabs Team
Meet the international team developing Coolify including founder Andras Bacsai, core developers, community leads, and documentation maintainers.
- **Andras Bacsai** - Founder, Lead Developer
- **Peaklabs Dev** - Core Developer
- **ShadowArcanist** - Community Lead, Docs Maintainer
- **Aditya Tripathi** - Developer, Community Moderator
- **Oren Aksakal** - Developer
- **You?** - Will You Be Next?
content/docs/get-started/uninstallation.mdx
+111
View File
@@ -0,0 +1,111 @@
---
title: Uninstalling Coolify
description: Completely remove Coolify from your self-hosted server by stopping containers, deleting volumes, networks, data directories, and Docker images.
---
<ZoomImage src="/docs/images/get-started/uninstallation-banner.webp" alt="Coolify uninstallation banner" />
<br />
If you're using [Coolify Cloud](https://coolify.io/pricing/), you don't need to uninstall Coolify since the Coolify Team manages everything on their servers.
To stop using Coolify Cloud, simply visit the [Billing page](https://app.coolify.io/subscription/) and cancel your subscription.
For those who **self-host** Coolify and wish to remove it from your server, follow the steps below to uninstall it safely:
- [Stop and Remove Containers](#_1-stop-and-remove-containers)
- [Remove Docker Volumes](#_2-remove-docker-volumes)
- [Remove Docker Network](#_3-remove-docker-network)
- [Delete Coolify Data Directory](#_4-delete-coolify-data-directory)
- [Remove Docker Images](#_5-remove-docker-images)
## 1. Stop and Remove Containers
Stop all Coolify-related Docker containers and remove them to free up system resources.
Run the following commands in your terminal:
```bash
sudo docker stop -t 0 coolify coolify-realtime coolify-db coolify-redis coolify-proxy coolify-sentinel
sudo docker rm coolify coolify-realtime coolify-db coolify-redis coolify-proxy coolify-sentinel
```
The `-t 0` flag ensures that the containers stop immediately without waiting for a timeout.
## 2. Remove Docker Volumes
To remove the persistent data stored in Docker volumes for Coolify, run:
```bash
sudo docker volume rm coolify-db coolify-redis
```
<Callout type="error" title="CAUTION!!">
Removing volumes will delete all data stored in them permanently. Ensure you have backups if needed.
</Callout>
## 3. Remove Docker Network
Coolify uses a custom Docker network named coolify. Remove it with the following command:
```bash
sudo docker network rm coolify
```
<Callout type="info" title="Info">
If you encounter an error indicating the network is in use, ensure that no containers are using the network before retrying.
</Callout>
## 4. Delete Coolify Data Directory
Remove the directory where Coolify stores its data on your server:
```bash
sudo rm -rf /data/coolify
```
<Callout type="error" title="CAUTION!">
This will permanently delete all Coolify-related data. Double-check the directory path before executing this command.
</Callout>
## 5. Remove Docker Images
To free up disk space, remove all Docker images used by Coolify by running the following commands:
```bash
sudo docker rmi ghcr.io/coollabsio/coolify:latest
sudo docker rmi ghcr.io/coollabsio/coolify-helper:latest
sudo docker rmi quay.io/soketi/soketi:1.6-16-alpine
sudo docker rmi postgres:15-alpine
sudo docker rmi redis:alpine
```
If you were using the default proxy, also remove its image:
```bash
sudo docker rmi traefik:v3.1
```
If you switched to the Caddy proxy, remove its image instead:
```bash
sudo docker rmi lucaslorentz/caddy-docker-proxy:2.8-alpine
```
---
### Coolify Successfully Uninstalled
After completing these steps, Coolify and all its related resources will be completely removed from your server.
content/docs/get-started/upgrade.mdx
+107
View File
@@ -0,0 +1,107 @@
---
title: Upgrading Coolify
description: Upgrade self-hosted Coolify automatically, semi-automatically with UI notifications, or manually via terminal with version-specific installation.
---
<ZoomImage src="/docs/images/get-started/upgrade/banner.webp" alt="Coolify banner" />
<br />
If you're using [Coolify Cloud](https://coolify.io/pricing/), the Coolify team handles all updates so you don’t need to worry about them.
For those who **self-host** Coolify, there are three ways to upgrade your instance:
- [Automatic Upgrade:](#_1-automatic-upgrade) For users who want easy, hands-off updates.
- [Semi-Automatic Upgrade:](#_2-semi-automatic-upgrade) For users who want control over when to apply updates.
- [Manual Upgrade:](#_3-manual-upgrade) For advanced users who prefer to manage the upgrade process themselves.
<Callout type="error" title="Backup First!">
- Always back up your Coolify data before starting an upgrade.
</Callout>
## 1. Automatic Upgrade
Coolify can update itself automatically. This option keeps your instance always up-to-date without any extra effort.
### How it works?
Coolify periodically checks the [CDN](https://cdn.coollabs.io/coolify/versions.json) for updates. When a new version is available, it automatically fetches the latest release from the [official repository](https://github.com/orgs/coollabsio/packages?repo_name=coolify) and starts the upgrade process on its own.
### Customize Automatic Updates
If you’d rather manage updates yourself, you can disable auto-updates in your Coolify dashboard’s Settings.
<ZoomImage src="/docs/images/get-started/upgrade/disable-auto-update.webp" alt="Disable Auto Update" />
<Callout type="info" title="Tip">
Turning off automatic updates lets you test a new version on a staging setup before updating your live environment.
</Callout>
## 2. Semi-Automatic Upgrade
This option gives you a bit more control. Coolify notifies you when an update is available, and you decide when to apply it.
### How it works?
Coolify periodically checks the [CDN](https://cdn.coollabs.io/coolify/versions.json) for updates. When a new version is available, you will see an "**Upgrade**" button in the sidebar of your Coolify dashboard.
<ZoomImage src="/docs/images/get-started/upgrade/upgrade-button-ui.webp" alt="Upgrade Button Ui" />
Click the upgrade button to start the update process.
### Set Update Frequency
You can also choose how often Coolify checks for updates by adjusting the settings (daily, weekly, etc.).
<ZoomImage src="/docs/images/get-started/upgrade/change-frequency.webp" alt="Change Frequency" />
<Callout type="info" title="Tip:">
This method is perfect if you want to review update details or test the upgrade before applying it.
</Callout>
## 3. Manual Upgrade
For those who prefer full control, you can upgrade Coolify manually.
### How to do this?
Open your server's terminal and run the command below:
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
```
To upgrade to a specific version, run the following command in your terminal:
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash -s 4.0.0-beta.400
```
Replace `4.0.0-beta.400` with the version number you want to upgrade to.
### How it works?
This command runs the official [Coolify installation script](https://github.com/coollabsio/coolify/blob/main/scripts/install.sh). The script checks the [CDN](https://cdn.coollabs.io/coolify/versions.json) for the latest version and updates your Coolify Instance.
<Callout type="success" title="Tip">
In the Automatic and Semi-Automatic methods, Coolify runs the installation script automatically in the background.
In the Manual upgrade method, you run the script yourself.
</Callout>
content/docs/get-started/usage.mdx
+58
View File
@@ -0,0 +1,58 @@
---
title: Usage
description: Compare Coolify Cloud managed service starting at $5/month versus free self-hosted deployment with maintenance, support, and backup differences.
---
<ZoomImage src="/docs/images/get-started/usage-banner.webp" alt="Coolify usage banner" />
<br />
So, you’ve decided to use Coolify, awesome choice!
Now, you might be wondering whether to go with **Coolify Cloud** or set it up yourself through **self-hosting**. Let’s break it down so you can pick the best option for you.
## Coolify Cloud
Coolify Cloud is the easy way to get started. It’s a paid service (starting at just **$5 a month**) where you bring your own servers and connect them to a Coolify instance that’s fully managed by our team.
<Callout type="warn" title="Note">
**We host and update the Coolify instance for you, so you don't have to allocate any of your server resources to Coolify, but you’re still responsible for your own servers and any other services running on them**
</Callout>
## Coolify Self-Hosted
If you’re more of a hands-on person, self-hosting Coolify might be your thing.
It’s completely free (except for your server costs, of course), and you get to control everything.
You’ll install Coolify on your own server, keep it updated, and manage all the related services yourself.
## How Do They Compare?
_All of the features below refer only to the Coolify instance, not your entire server or other services._
| Feature | Coolify Cloud | Self-Hosted Coolify |
| ----------------------- | ------------------------------------------------------------------- | --------------------------------------------------------- |
| **Maintenance** | We take care of hosting and updating the Coolify instance for you | You’re in charge of keeping the instance running smoothly |
| **Support** | Help from Coolify experts and our core team | Chat with the community on Discord |
| **Email Notifications** | Pre-configured and ready to use for free | You’ll need to set this up yourself |
| **Backups** | We handle automatic backups for your Coolify instance | Set up your own backup system for the Coolify instance |
| **High Availability** | We’ve got you covered with reliable uptime for the Coolify instance | Depends on how you set things up |
| **Stability** | We test updates thoroughly before rolling them out | Test updates yourself before upgrading |
| **Cost** | Starts at **$5/month** | Free forever (just pay for your server) |
And just so you know, we don’t play the “**feature lock**” game. Whether you choose Coolify Cloud or self-host, you get all the same powerful features.
We’re all about giving you the full Coolify experience, no matter which path you take.
## Which One is Right for You?
If you want a quick, easy setup and don’t mind paying a small fee for convenience, **Coolify Cloud** is perfect.
But if you love getting hands-on, want to save every penny, and enjoy being in full control, **Self-Hosting** is the way to go.
If you're still not sure which path to take, join our [Discord community](https://coolify.io/discord) and ask any questions you might have! We're here to help you decide what's best for your needs.
content/docs/get-started/videos.mdx
+98
View File
@@ -0,0 +1,98 @@
---
title: Coolify Tutorial videos
description: Watch community video tutorials on Coolify self-hosted PaaS including installation, deployment, and complete walkthroughs for beginners.
---
# Video Tutorials created by the community
Only few of the videos are listed here
### Syntax: 1.5 hours long complete walkthrough
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/taJlPG82Ucw?si=O4Gu8_Dxcb68agfu"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
### WebdevCody: 6 minutes quick overview
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/44uWIkGZ4W8"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
### Developedbyed: 20 minutes overview
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/ZZ1lnw8D3Qo?si=U5jfyp-wykHd1OTL"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
### Fireship video
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/SCIfWhAheVw"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
### MelkeyDev video
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/SANSysQlS18"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
### Brendan O'Connell
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/8pLDDcEZlbo?si=L-QXX-3hHbbqd7kN"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
### Awesome Open Source
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/cg28Ztt4-os?si=u6asFexlFpe8FmK7"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
### Airoflare Coolify beginner playlist
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/videoseries?list=PLoVHNPkf8ZxrVW0vclP5ngQQcTz6-VzL-"
title="YouTube playlist"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
content/docs/index.mdx
+7
View File
@@ -0,0 +1,7 @@
---
title: Coolify
description: Coolify is an open-source Platform as a Service (PaaS) for self-hosting databases, services, and applications with free SSL, backups, and Git integration.
full: true
---
<CoolifyHome />
content/docs/integrations/cloudflare/ddos-protection.mdx
+356
View File
@@ -0,0 +1,356 @@
---
title: Cloudflare DDoS Protection
description: Learn how to set up Cloudflare DDoS protection for applications deployed with Coolify.
---
# Cloudflare DDoS Protection
Cloudflare provides a robust layer of DDoS protection for your server and applications.
When using Cloudflare’s Proxy, CDN, and security features, all incoming traffic to your Coolify-hosted apps is shielded from malicious attacks, like DDoS, and secured through Cloudflare’s global network.
---
### Why Use Cloudflare for DDoS Protection with Coolify?
1. Blocks malicious traffic before it reaches your server, reducing risk and server load.
2. No need to scale server resources during DDoS attacks — Cloudflare absorbs the impact.
3. Minimal configuration required to enable robust protection against potentially costly attacks.
4. Hides your server’s real IP address by resolving your domain to Cloudflare’s IPs.
---
### When Not to Use Cloudflare for DDoS Protection
1. You prefer not to route all traffic through Cloudflare’s network.
2. Privacy concerns, Cloudflare terminates TLS, which means they can inspect incoming requests.
3. Cloudflare downtime, although extremely rare, could affect your service if you rely entirely on their protection.
4. You want full control over SSL/TLS certificates issued by a global Certificate Authority.
5. You need free wildcard support for deep subdomains (more than 1 level subdomains -- e.g., `*.sub.domain.com` which Cloudflare does not offer for free).
---
<Callout type="info" title="Example Data">
The following data is used as an example in this guide. Please replace it with your actual data when following the steps:
- **IPv4 Address of Origin Server:** 203.0.113.1
- **Domain Name:** shadowarcanist.com
- **Username:** shadowarcanist
</Callout>
## 1. Create the Origin Certificate
Communication between your server and Cloudflare is encrypted using a custom Cloudflare Origin Certificate (required when using Cloudflare’s proxy).
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/origin-cert-illustration.webp" />
To create your Cloudflare Origin Certificate, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/1.webp" />
1. In your Cloudflare dashboard, go to **SSL/TLS**.
2. Select **Origin Server**.
3. Click the **Create Certificate** button.
You’ll be asked to choose a private key type, hostnames, and certificate validity.
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/2.webp" />
1. Choose **RSA (2048)** for the key type.
2. Add the hostnames you want the certificate to cover.
<Callout type="warn" title="HEADS UP!">
- **`shadowarcanist.com`** will cover only the main domain.
- **`*.shadowarcanist.com`** will cover all subdomains.
On Cloudflare’s free plan, wildcard certificates cover just one level of subdomains
For example, it works for **`coolify.shadowarcanist.com`** but not **`www.coolify.shadowarcanist.com`**.
To cover multiple levels, you'll need to purchase the [Advanced Certificate Manager ↗](https://www.cloudflare.com/application-services/products/advanced-certificate-manager/)
</Callout>
3. Set the certificate validity to **15 years**.
Your certificate will now be generated.
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/3.webp" />
1. Choose **PEM** as the key format.
2. Copy your **Certificate**.
3. Copy your **Private Key**.
Next, you'll add these to your server running Coolify and configure Coolify to use this certificate.
## 2. Add Certificate to Your Server
SSH into your server or use Coolify's terminal feature. For this guide, I’m using SSH:
```bash
ssh shadowarcanist@203.0.113.1
```
Once logged in, navigate to the Coolify proxy directory:
```bash
$ cd /data/coolify/proxy
```
Adding certificates slightly varies for Caddy and Traefik proxy so choose the correct one from the below section
<Callout type="info">
== Traefik
Create the `certs` directory:
```bash
$ mkdir certs
```
Verify it was created:
```bash
$ ls
> acme.json certs docker-compose.yml dynamic
```
Now, navigate into the **certs** directory:
```bash
$ cd certs
```
Create two new files for the certificate and private key:
```bash
$ touch shadowarcanist.cert shadowarcanist.key
```
Verify the files were created:
```bash
$ ls
> shadowarcanist.cert shadowarcanist.key
```
Open the **shadowarcanist.cert** file and paste the certificate from the Cloudflare dashboard:
```bash
$ nano shadowarcanist.cert
```
Save and exit after pasting the certificate.
Do the same for the **shadowarcanist.key** file and paste the private key:
```bash
$ nano shadowarcanist.key
```
Save and exit.
== Caddy
Create the `caddy/data/certs` directory:
```bash
$ mkdir -p caddy/data/certs
```
Verify it was created:
```bash
$ ls caddy/data
> certs
```
Now, navigate into the **certs** directory:
```bash
$ cd caddy/data/certs
```
Create two new files for the certificate and private key:
```bash
$ touch shadowarcanist.cert shadowarcanist.key
```
Verify the files were created:
```bash
$ ls
> shadowarcanist.cert shadowarcanist.key
```
Open the **shadowarcanist.cert** file and paste the certificate from the Cloudflare dashboard:
```bash
$ nano shadowarcanist.cert
```
Save and exit after pasting the certificate.
Do the same for the **shadowarcanist.key** file and paste the private key:
```bash
$ nano shadowarcanist.key
```
Save and exit.
</Callout>
Now the origin certificate is installed on your server.
## 3. Set Up DNS Records and TLS Encryption
To make the origin certificate work, configure your DNS records, enable TLS, and set up HTTP to HTTPS redirects in Cloudflare:
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/4.webp" />
1. In Cloudflare, go to **DNS**.
2. Select **Records**.
3. Add 2 A records:
4. Enter name as **`shadowarcanist.com`** and `*`
5. Use the **IP address** of your server as the content for both records.
6. Set the proxy status to **Proxied** for both records.
<Callout type="info">
Enabling the "Proxied" (orange cloud) option for both A records — `shadowarcanist.com` and `*` — will proxy the root domain and all one-level subdomains via a wildcard.
This isn't necessary if you only need to proxy (or protect against DDoS) for a specific domain. In that case, simply enable proxying for the domain you want protection for.
</Callout>
Next, set up TLS encryption:
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/5.webp" />
1. Go to **SSL/TLS** in Cloudflare.
2. Select **Overview**.
3. Click **Configure** button
Choose **Full (Strict)** as the encryption mode.
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/6.webp" />
Finally, enable HTTP to HTTPS redirects:
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/7.webp" />
1. In Cloudflare, go to **SSL/TLS**
2. Select **Edge Certificates**.
3. Enable **Always Use HTTPS**.
## 4. Configure Coolify proxy to Use the Origin Certificate
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/8.webp" />
1. Go to the **Server** section in the sidebar.
2. Select **Proxy**.
3. Open the **Dynamic Configuration** page
4. Click **Add** button
You will now be prompted to enter the Dynamic Configuration.
Adding Dynamic Configuration slightly varies for Caddy and Traefik proxy so choose the correct one from the below section
<Callout type="info">
== Traefik
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/9.webp" />
1. Choose a name for your configuration (must end with `.yaml`).
2. Enter the following details in the configuration field:
```bash
tls:
certificates:
-
certFile: /traefik/certs/shadowarcanist.cert
keyFile: /traefik/certs/shadowarcanist.key
```
3. Save the configuration
---
If you want to add multiple certificates and keys, you can do it like this:
```bash
tls:
certificates:
-
certFile: /traefik/certs/shadowarcanist.cert
keyFile: /traefik/certs/shadowarcanist.key
-
certFile: /traefik/certs/name2.cert
keyFile: /traefik/certs/name2.key
-
certFile: /traefik/certs/name3.cert
keyFile: /traefik/certs/name3.key
```
== Caddy
<ZoomImage src="/docs/images/integrations/cloudflare/ddos-protection/10.webp" />
1. Choose a name for your configuration (must end with `.caddy`).
2. Enter the following details in the configuration field:
```bash
*.shadowarcanist.com, shadowarcanist.com {
tls /data/certs/shadowarcanist.cert /data/certs/shadowarcanist.key
}
```
> Note: The wildcard `*.shadowarcanist.com` provides coverage for all subdomains, exclude it if you’re only securing a single domain (i.e, `shadowarcanist.com`).
3. Save the configuration
---
If you want to add multiple certificates and keys, you can do it like this:
```bash
*.shadowarcanist.com, shadowarcanist.com {
tls /data/certs/shadowarcanist.cert /data/certs/shadowarcanist.key
}
*.name2.com, name2.com {
tls /data/certs/name2.cert /data/certs/name2.key
}
*.name3.com, name3.com {
tls /data/certs/name3.cert /data/certs/name3.key
}
```
</Callout>
From now on, Coolify will use the origin certificate for requests matching the hostname.
Now you’re done! Your server is set up to use the Cloudflare Origin Certificate, and all traffic is proxied through Cloudflare network so all incoming attacks like DDoS are prevented by Cloudflare before it reaches your server.
<Callout type="error" title="HEADS UP!!">
**All the steps below are optional. Cloudflare should already be protecting your applications. Follow the below steps if you want to prevent attackers from directly attacking your server by it's IP Address on Port 80 and 443**
</Callout>
## 5. Configure Firewall to Allow Only Cloudflare Traffic
Configure your firewall to allow incoming traffic on port **443** only from [Cloudflare’s IP ranges ↗](https://www.cloudflare.com/en-gb/ips/).
Block all other inbound traffic, except for your SSH port.
This prevents attackers from bypassing Cloudflare and directly targeting your server with traffic on ports 80 or 443.
This step is completely optional but recommended.
## Credits
The origin-cert-illustration image is designed using icons from [Flaticon ↗](https://www.flaticon.com/).
Links to each icon can be found below:
- [Medal icon ↗](https://www.flaticon.com/free-icon/medal_14468558) by [Vlad Szirka ↗](https://www.flaticon.com/authors/vlad-szirka)
- [Award icon ↗](https://www.flaticon.com/free-icon/award_15218157) by [explanaicon ↗](https://www.flaticon.com/authors/explanaicon)
- [Worldwide icon ↗](https://www.flaticon.com/free-icon/worldwide_870169) by [Freepik ↗](https://www.flaticon.com/authors/freepik)
- [Lock icon ↗](https://www.flaticon.com/free-icon/lock_2089784) by [Those Icons ↗](https://www.flaticon.com/authors/those-icons)
- [Browser icon ↗](https://www.flaticon.com/free-icon/browser_331190) by [Alfredo Hernandez ↗](https://www.flaticon.com/authors/alfredo-hernandez)
- [Database icon ↗](https://www.flaticon.com/free-icon/database_8028666) by [Tanah Basah ↗](https://www.flaticon.com/authors/tanah-basah)
content/docs/integrations/cloudflare/meta.json
+7
View File
@@ -0,0 +1,7 @@
{
"title": "Cloudflare",
"pages": [
"tunnels",
"ddos-protection"
]
}
content/docs/integrations/cloudflare/tunnels/all-resource.mdx
+199
View File
@@ -0,0 +1,199 @@
---
title: "Access All Resource via Cloudflare Tunnels"
description: "Expose all Coolify resources securely through Cloudflare Tunnels without public IPs or port forwarding using wildcard domains and HTTP proxy routing."
---
# Access All Resource via Cloudflare Tunnels
Accessing All Resource deployed on Coolify using a Cloudflare Tunnel allows you to securely reach your app without exposing your server’s IP address or without having a Public IP address for the server.
## Who this is for?
This setup is ideal for people who:
- Don't have a public IP for their server (could be a laptop, raspberry pi etc..).
- Are unable to port forward (e.g., using home internet or on a private network).
- Want to keep their server’s IP address private and avoid exposing it to the public internet.
- Have an resource already deployed on Coolify and need an external method to access it securely.
## Setup Requirements
To follow this guide, you'll need:
- A free [Cloudflare](https://cloudflare.com) account.
- You need a domain that has it's **DNS managed by Cloudflare**.
## Before We Start
- We assume you have Coolify running on your server.
- If your app requires HTTPS for functionality like cookies or login, then you need to follow the [Full TLS HTTPS guide](/integrations/cloudflare/tunnels/full-tls) after following this guide. This is because in this guide, Cloudflare will manage HTTPS externally, while your app will run over HTTP within Coolify.
## How It Works?
A simple high-level overview diagram to give you a visual idea of how this works:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/high-level-diagram.webp" />
---
### Quick Links to Important Sections:
- [Create a Cloudflare Tunnel](#_1-create-a-cloudflare-tunnel)
- [Setup Encryption mode on Cloudflare](#_2-setup-encryption-mode-on-cloudflare)
- [Setup Cloudflare Tunnel on Coolify](#_3-setup-cloudflare-tunnel-on-coolify)
- [Start Coolify Proxy](#_4-start-coolify-proxy)
- [Configure Your Resource to Use the Tunnel Domain](#_5-configure-your-resource-to-use-the-tunnel-domain)
- [How to use Multiple Different Domains](#how-to-use-multiple-different-domains)
- [Known issues and Solutions](#known-issues-and-solutions)
---
<Callout type="warn" title="Example Data">
The following data is used as an example in this guide. Please replace it with your actual data when following the steps:
- **Domain Name:** shadowarcanist.com
</Callout>
---
## 1. Create a Cloudflare Tunnel
To create a Cloudflare Tunnel, first log in to your Cloudflare account and go to the [Zero Trust](https://one.dash.cloudflare.com/) page.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/1.webp" />
1. On the Zero Trust page, go to **Networks** in the sidebar.
2. Click on **Tunnels**
3. Click on **Add a tunnel** button
You will be prompted to choose a tunnel type. Click the **Select Cloudflared** button.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/2.webp" />
You will be prompted to enter a tunnel name. Choose a name that you prefer.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/3.webp" />
Next you will see the configuration page with multiple options to install cloudflared.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/4.webp" />
Copy the install command, which contains the token for your tunnel (token starts with "eyJ"). Make sure to save only the token, removing the command part before it, and store it in a safe place, as we need it later.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/5.webp" />
Scroll down until you see the **Next** button, then click it.
Then, you will be prompted to add a hostname.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/6.webp" />
1. **Subdomain** - (Optional) You can make your all of your resource accessible on any subdomain/domain. For this guide, we are using a wildcard subdomain.
2. **Domain** - Choose the domain you want to use for the tunnel.
3. **Path** - Leave this field empty.
4. **Type** - Choose **HTTP** (this is very important).
5. **URL** - Enter **localhost:80** (this is very important).
6. After filling in the details, click the **Save Tunnel** button.
## 2. Setup Encryption mode on Cloudflare
To set up encryption on Cloudflare, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/15.webp" />
1. Go to https://dash.cloudflare.com/ and select the domain you created the tunnel for.
2. Click **SSL/TLS** in the sidebar.
3. Select **Overview**.
4. Click **Configure** button
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/16.webp" />
Choose **Full** as the encryption mode.
## 3. Setup Cloudflare Tunnel on Coolify
To set up the tunnel on Coolify, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/7.webp" />
Go to your project on Coolify dashboard and click the **+ New** button to create a new resource.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/8.webp" />
You will see many options to deploy a new app. Search for Cloudflared and click on it.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/9.webp" />
Go to the **Environment Variables** page, enter your tunnel token, and deploy the Cloudflared app. This token was copied in [Step 1](#_1-create-a-cloudflare-tunnel)
## 4. Start Coolify Proxy
To start the Coolify proxy, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/10.webp" />
1. In the Coolify dashboard, go to the **Servers** page from the sidebar.
2. Select the server where coolify is running, then Click on the **Proxy** tab.
3. Open the **General** tab.
4. Click the **Start Proxy** button.
<Callout type="success" title="Tip">
The Coolify proxy is used to route traffic to apps running on your server. This eliminates the need to create new hostnames on the Cloudflare tunnel every time you deploy a new app.
</Callout>
## 5. Configure Your Resource to Use the Tunnel Domain
Enter the domain you want to use for your resource/app and deploy your resource.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/11.webp" />
<Callout type="warn" title="HEADS UP!">
You should enter the domain as **HTTP** because Cloudflare handles **HTTPS** and TLS terminations. If you use **HTTPS** for your resource, you may encounter a **TOO_MANY_REDIRECTS** error.
If your app requires **HTTPS** for features like cookies or login, follow the [Full TLS HTTPS Guide](/integrations/cloudflare/tunnels/full-tls) after completing this guide.
</Callout>
**Congratulations**! You've successfully set up a resource that can be accessed by anyone on the internet your domain.
## How to use Multiple Different Domains?
You don't need to create new tunnels for each domain, just create a new hostname with the new domain and point it to the `localhost:80`.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/12.webp" />
## Known issues and Solutions
When you create a new public hostname in [Step 1](#_1-create-a-cloudflare-tunnel), Cloudflare will create a DNS record for the hostname.
However, if a DNS record for the hostname already exists, Cloudflare won’t create a new one.
In this case, your app won’t work. To fix this issue, follow the steps below:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/13.webp" />
First, copy your tunnel ID from the Tunnels page on the Cloudflare dashboard.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/all-resource/14.webp" />
Create a new DNS record with the following details:
1. In the Cloudflare dashboard, go to **DNS**.
2. Select **Records**.
3. Add a **CNAME** record.
4. Enter the name as `*` or the name of your subdomain (this should match the hostname you have for your app on the tunnel).
5. For the **Target**, enter the tunnel ID followed by `.cfargotunnel.com`
6. Set the proxy status to **Proxied**.
Now, visit the domain of your application, and it should be accessible there.
content/docs/integrations/cloudflare/tunnels/full-tls.mdx
+375
View File
@@ -0,0 +1,375 @@
---
title: "Full HTTPS/TLS Setup for All Resources"
description: "Configure end-to-end HTTPS for Coolify resources through Cloudflare Tunnels with Origin Certificates, strict TLS encryption, and proper domain setup."
---
# Full HTTPS/TLS Setup for All Resources
When tunneling resources with Coolify through Cloudflare, Cloudflare typically handles HTTPS and TLS termination, while Coolify runs your resources over HTTP.
This setup works for most users, but some may face issues with URL mismatches, especially for apps that require HTTPS on Coolify to issue JWT tokens or handle callback URLs.
This guide solves that issue by configuring your resources to run fully on HTTPS, bypassing Cloudflare's HTTPS handling and ensuring your app functions correctly with secure connections.
## Who this is for?
This guide is ideal for users who:
- Have followed our [Tunnel All Resources Using Cloudflare Tunnel](/integrations/cloudflare/tunnels/all-resource) or [Tunnel Specific Resources Using Cloudflare Tunnel](/integrations/cloudflare/tunnels/single-resource) guide.
- Need their resources deployed with Coolify to run on HTTPS for applications requiring HTTPS for JWT issuance, callback functions, or similar features.
## Setup Requirements
To follow this guide, you'll need:
- A working Cloudflare tunnel setup as described in the previous guides.
- A domain configured in Cloudflare to handle HTTP traffic and redirect to HTTPS.
## Before We Start
- If your Coolify instance is on the same tunnel as the domain you want to configure, make sure you can access the Coolify Dashboard using the server IP and port (e.g., **203.0.113.1:8000**) before starting these steps.
- The default port is **8000**, but if you’ve changed or disabled it, ensure you can access the Coolify Dashboard through the new port or that port **8000** is re-enabled on the server.
---
### Quick Links to Important Sections:
- [Create a Cloudflare Origin Certificate](#_1-create-a-cloudflare-origin-certificate)
- [Add Origin Certificate to Your Server](#_2-add-origin-certificate-to-your-server)
- [Configure Coolify to Use the Origin Certificate](#_3-configure-coolify-to-use-the-origin-certificate)
- [Setup Encryption mode on Cloudflare](#_4-setup-encryption-mode-on-cloudflare)
- [Configure Tunnel to Use HTTPS](#_5-configure-tunnel-to-use-https)
- [Configure Cloudflare to Always Use HTTPS](#_6-configure-cloudflare-to-always-use-https)
- [Update URLs from HTTP to HTTPS](#_7-update-urls-from-http-to-https)
---
<Callout type="warn" title="Example Data">
The following data is used as an example in this guide. Please replace it with your actual data when following the steps:
- **IPv4 Address of Origin Server:** 203.0.113.1
- **Domain Name:** shadowarcanist.com
- **Username:** shadowarcanist
</Callout>
## 1. Create a Cloudflare Origin Certificate
To create your Cloudflare Origin Certificate, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/1.webp" />
1. In your Cloudflare dashboard, go to **SSL/TLS**.
2. Select **Origin Server**.
3. Click the **Create Certificate** button.
You’ll be asked to choose a private key type, hostnames, and certificate validity.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/2.webp" />
1. Choose **RSA (2048)** for the key type.
2. Add the hostnames you want the certificate to cover.
<Callout type="warn" title="HEADS UP!">
- **`shadowarcanist.com`** will cover only the main domain.
- **`*.shadowarcanist.com`** will cover all subdomains.
On Cloudflare’s free plan, wildcard certificates cover just one level of subdomains
For example, it works for **`coolify.shadowarcanist.com`** but not **`www.coolify.shadowarcanist.com`**.
To cover multiple levels, you'll need to purchase the [Advanced Certificate Manager](https://www.cloudflare.com/application-services/products/advanced-certificate-manager/)
</Callout>
3. Set the certificate validity to **15 years**.
Your certificate will now be generated.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/3.webp" />
1. Choose **PEM** as the key format.
2. Copy your **Certificate**.
3. Copy your **Private Key**.
Next, you'll add these to your server running Coolify and configure Coolify to use this certificate.
## 2. Add Origin Certificate to Your Server
SSH into your server or use Coolify's terminal feature. For this guide, I’m using SSH:
```bash
ssh shadowarcanist@203.0.113.1
```
Once logged in, navigate to the Coolify proxy directory:
```bash
$ cd /data/coolify/proxy
```
Adding certificates slightly varies for Caddy and Traefik proxy so choose the correct one from the below section
<Callout type="info">
== Traefik
Create the `certs` directory:
```bash
$ mkdir certs
```
Verify it was created:
```bash
$ ls
> acme.json certs docker-compose.yml dynamic
```
Now, navigate into the **certs** directory:
```bash
$ cd certs
```
Create two new files for the certificate and private key:
```bash
$ touch shadowarcanist.cert shadowarcanist.key
```
Verify the files were created:
```bash
$ ls
> shadowarcanist.cert shadowarcanist.key
```
Open the **shadowarcanist.cert** file and paste the certificate from the Cloudflare dashboard:
```bash
$ nano shadowarcanist.cert
```
Save and exit after pasting the certificate.
Do the same for the **shadowarcanist.key** file and paste the private key:
```bash
$ nano shadowarcanist.key
```
Save and exit.
== Caddy
Create the `caddy/data/certs` directory:
```bash
$ mkdir -p caddy/data/certs
```
Verify it was created:
```bash
$ ls caddy/data
> certs
```
Now, navigate into the **certs** directory:
```bash
$ cd caddy/data/certs
```
Create two new files for the certificate and private key:
```bash
$ touch shadowarcanist.cert shadowarcanist.key
```
Verify the files were created:
```bash
$ ls
> shadowarcanist.cert shadowarcanist.key
```
Open the **shadowarcanist.cert** file and paste the certificate from the Cloudflare dashboard:
```bash
$ nano shadowarcanist.cert
```
Save and exit after pasting the certificate.
Do the same for the **shadowarcanist.key** file and paste the private key:
```bash
$ nano shadowarcanist.key
```
Save and exit.
</Callout>
Now the origin certificate is installed on your server.
## 3. Configure Coolify to Use the Origin Certificate
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/14.webp" />
1. Go to the **Server** section in the sidebar.
2. Select **Proxy**.
3. Open the **Dynamic Configuration** page
4. Click **Add** button
You will now be prompted to enter the Dynamic Configuration.
Adding Dynamic Configuration slightly varies for Caddy and Traefik proxy so choose the correct one from the below section
<Callout type="info">
== Traefik
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/15.webp" />
1. Choose a name for your configuration (must end with `.yaml`).
2. Enter the following details in the configuration field:
```bash
tls:
certificates:
-
certFile: /traefik/certs/shadowarcanist.cert
keyFile: /traefik/certs/shadowarcanist.key
```
3. Save the configuration
---
If you want to add multiple certificates and keys, you can do it like this:
```bash
tls:
certificates:
-
certFile: /traefik/certs/shadowarcanist.cert
keyFile: /traefik/certs/shadowarcanist.key
-
certFile: /traefik/certs/name2.cert
keyFile: /traefik/certs/name2.key
-
certFile: /traefik/certs/name3.cert
keyFile: /traefik/certs/name3.key
```
== Caddy
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/16.webp" />
1. Choose a name for your configuration (must end with `.caddy`).
2. Enter the following details in the configuration field:
```bash
*.shadowarcanist.com, shadowarcanist.com {
tls /data/certs/shadowarcanist.cert /data/certs/shadowarcanist.key
}
```
> Note: The wildcard `*.shadowarcanist.com` provides coverage for all subdomains, exclude it if you’re only securing a single domain (i.e, `shadowarcanist.com`).
3. Save the configuration
---
If you want to add multiple certificates and keys, you can do it like this:
```bash
*.shadowarcanist.com, shadowarcanist.com {
tls /data/certs/shadowarcanist.cert /data/certs/shadowarcanist.key
}
*.name2.com, name2.com {
tls /data/certs/name2.cert /data/certs/name2.key
}
*.name3.com, name3.com {
tls /data/certs/name3.cert /data/certs/name3.key
}
```
</Callout>
From now on, Coolify will use the origin certificate for requests matching the hostname.
## 4. Setup Encryption mode on Cloudflare
To set up encryption on Cloudflare, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/4.webp" />
1. Go to **SSL/TLS** in Cloudflare.
2. Select **Overview**.
3. Click **Configure** button
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/5.webp" />
Choose **Full (Strict)** as the encryption mode.
## 5. Configure Tunnel to Use HTTPS
To configure the tunnel for HTTPS, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/6.webp" />
1. Click the three dots icon to open the settings menu.
2. Select **Edit** to allow hostname modifications.
Next, update the hostnames as follows:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/7.webp" />
1. Change the type from **HTTP** to **HTTPS**.
2. Change the port from **80** to **443**.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/8.webp" />
3. Click on **Additional Application Settings**.
4. Select **TLS**.
5. Enter your root domain in the **Origin Server Name** field.
6. Scroll down and click the **Save Hostname** button.
## 6. Configure Cloudflare to Always Use HTTPS
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/9.webp" />
1. In the Cloudflare dashboard, go to **SSL/TLS**.
2. Select **Edge Certificates**.
3. Enable **Always Use HTTPS**.
## 7. Update URLs from HTTP to HTTPS
Now, update all URLs from **HTTP** to **HTTPS** in Coolify, including resources and the instance domain on the settings page.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/10.webp" />
<br />
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/full-tls/11.webp" />
**Congratulations!** All your resources are now running on HTTPS at all times.
content/docs/integrations/cloudflare/tunnels/index.mdx
+46
View File
@@ -0,0 +1,46 @@
---
title: "Cloudflare Tunnels"
description: "Connect Coolify resources securely without port forwarding using Cloudflare Tunnels for all resources, single apps, SSH access, or full HTTPS setups."
---
# Cloudflare Tunnels
[Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) allow you to securely expose your local server or applications to the internet without opening ports on your router.
This makes them a great option for hosting projects on devices like old laptops or Raspberry Pis.
## Why Use Cloudflare Tunnels?
- No need to open or forward ports on your device to the public internet.
- Simplifies routing and DNS configuration.
- Supports exposing a single application or multiple services.
- Hides your server's IP address by routing traffic through a Cloudflare Tunnel, showing only your domain.
- Works even if you have a dynamic IP (or) no public IP at all.
- Eliminates the hassle of managing and setting up SSL certificates.
## When Not to Use Cloudflare Tunnels?
- If you prefer direct access to your server without a proxy layer.
- If you're concerned about routing traffic through Cloudflare's servers.
- If you rely on additional firewall tools, as Cloudflare Tunnels bypass all firewall rules.
- If you need SSL certificates trusted by entities other than Cloudflare.
## Ways to Use Cloudflare Tunnels with Coolify
You can set up Cloudflare Tunnels with Coolify in several ways, depending on your needs. Below are the available options, each linked to a detailed guide for easy setup:
1. [All Resources](/integrations/cloudflare/tunnels/all-resource) -> Use a tunnel for all resources deployed through Coolify. This is the **easiest** and **most recommended** way for beginners.
2. [Single Resource](/integrations/cloudflare/tunnels/single-resource) -> Use a tunnel for a single resource deployed through Coolify.
3. [Server SSH Access](/integrations/cloudflare/tunnels/server-ssh) -> Securely connect your server to Coolify using a domain through Cloudflare Tunnel.
4. [Full HTTPS/TLS](/integrations/cloudflare/tunnels/full-tls) -> Setup always-on **HTTPS** for all domains and subdomains. Normally, Coolify uses **HTTP** while Cloudflare manages **HTTPS**. If certain apps require **HTTPS** directly on Coolify.
<Callout type="success" title="Tip:">
It’s highly recommended to go with the first option [All Resources](/integrations/cloudflare/tunnels/all-resource) if you're new to Coolify and Cloudflare Tunnels, as it’s much easier to set up and manage.
</Callout>
content/docs/integrations/cloudflare/tunnels/meta.json
+9
View File
@@ -0,0 +1,9 @@
{
"title": "Tunnels",
"pages": [
"all-resource",
"single-resource",
"server-ssh",
"full-tls"
]
}
content/docs/integrations/cloudflare/tunnels/server-ssh.mdx
+374
View File
@@ -0,0 +1,374 @@
---
title: "Server SSH Access via Cloudflare Tunnels"
description: "Enable secure SSH access to Coolify servers via Cloudflare Tunnels with automated or manual cloudflared installation hiding server IP addresses."
---
# Server SSH Access via Cloudflare Tunnels
Accessing your server using SSH over a Cloudflare Tunnel is a secure and easy way to connect to a remote server while keeping its IP address hidden.
This guide explains how to set it up using Coolify's automated cloudflare tunnel installation.
## Who this is for?
This setup is ideal for people who:
- Want to keep their server's IP address private.
- Want to close all SSH ports on their server.
- Don’t want to rely on static public IPs for accessing their remote server.
- Don't have a static public IP for the server (only applies if you're doing the [manual setup](#manual-setup)).
## Before We Start
- We assume you already have a server running Coolify and you are looking to set up a tunnel to connect a different server to Coolify.
- If you are trying to set up a tunnel on the server where Coolify is running and you don’t have any other servers to connect, you don’t need a SSH tunnel. Coolify already has full root access to the server it’s running on, so there’s no need for an SSH tunnel in this case.
## How It Works?
A simple high-level overview diagram to give you a visual idea of how this works:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/high-level-diagram.webp" />
---
# Setup Methods
There are two ways to set this up: automated and manual.
The main difference is that in the manual setup, you install cloudflared yourself, while in the automated setup, Coolify does it for you.
Choose one of the links below for the setup guide:
- [Automated](#automated-setup)
- [Manual Setup](#manual-setup)
## Automated Setup
To use Coolify's automated setup for a Cloudflare Tunnel:
- Your remote server must have a **public IP address** and an **active SSH port** during the initial setup for Coolify to configure the tunnel. After setup, you can close all ports on the server.
- If your server doesn’t have a public IP address, then this automated setup is **not for you**. Please follow the [Manual setup guide](#manual-setup) instead.
- You need a domain that has it's **DNS managed by Cloudflare**.
### Quick Links to Important Sections:
- [Create a Private SSH Key](#_1-create-a-private-ssh-key)
- [Add Public Key to Your Server](#_2-add-public-key-to-your-server)
- [Add your Server to Coolify](#_3-add-your-server-to-coolify)
- [Validate your Server on Coolify](#_4-validate-your-server-on-coolify)
- [Create a Cloudflare Tunnel](#_5-create-a-cloudflare-tunnel)
- [Setup Cloudflare Tunnel on Coolify](#_6-setup-cloudflare-tunnel-on-coolify)
---
<Callout type="warn" title="Example Data">
The following data is used as an example in this guide. Please replace it with your actual data when following the steps:
- **IPv4 Address of Remote Server:** 203.0.113.1
- **Domain Name:** shadowarcanist.com
- **Username:** root
- **SSH Port:** 22
</Callout>
---
## 1. Create a Private SSH Key
To create a Private SSH Key, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-1.webp" />
1. In your Coolify Dashboard, go to **Keys & Tokens**
2. Click the **+ Add** button
You will be prompted to choose a key type, along with providing a name and description for the key.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-2.webp" />
1. Click on Generate new **ED25519** or **RSA** button to generate a new SSH key.
2. Copy the public key and save it somewhere safe (you'll need it in the next step). Then, click Continue.
## 2. Add Public Key to Your Server
SSH into the server you want to connect to Coolify:
```bash
ssh root@203.0.113.1
```
Once logged in, add your public key to the authorized keys file:
```bash
$ echo "<PASTE YOUR PUBLIC KEY INSIDE OF THESE QUOTES>" >> ~/.ssh/authorized_keys
```
## 3. Add your Server to Coolify
To add your server to Coolify, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-3.webp" />
1. In your Coolify Dashboard, go to **Servers**
2. Click the **+ Add** button
You will be prompted to enter details about your server. Make sure the information you provide is accurate, as Coolify will use these details to access your server.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-4.webp" />
1. **Name** - Choose a name to easily identify your server in the dashboard.
2. **Description** - (Optional) Provide a description for your server.
3. **IP Address/Domain** - Enter the public IP address of your server.
4. **Port** - Enter the port number your server uses for SSH connections.
5. **User** - Enter the username Coolify will use (it should have root privileges on the server).
6. **Private key** - Select the private key you created in [Step 1](#_1-create-a-private-ssh-key)
7. After filling in the details, click the **Continue** button.
## 4. Validate your Server on Coolify
To validate your server, simply click the **Validate Server & Install Docker Engine** button.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-5.webp" />
During this process, Coolify will log in to your server and set up everything needed for Coolify to use the server.
Once the validation is completed, your server page will look like this:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-6.webp" />
## 5. Create a Cloudflare Tunnel
To create a Cloudflare Tunnel, first log in to your Cloudflare account and go to the [Zero Trust](https://one.dash.cloudflare.com/) page.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-7.webp" />
1. On the Zero Trust page, go to **Networks** in the sidebar.
2. Click on **Tunnels**
3. Click on **Add a tunnel** button
You will be prompted to choose a tunnel type. Click the **Select Cloudflared** button.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-8.webp" />
You will be prompted to enter a tunnel name. Choose a name that you prefer.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-9.webp" />
Next you will see the configuration page with multiple options to install cloudflared.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-10.webp" />
Copy the install command, which contains the token for your tunnel (token starts with "eyJ"). Make sure to save only the token, removing the command part before it, and store it in a safe place, as we need it later.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-11.webp" />
Scroll down until you see the **Next** button, then click it.
Then, you will be prompted to add a hostname. This is where we expose our SSH tunnel.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-12.webp" />
1. **Subdomain** - (Optional) You can make SSH accessible on any subdomain. For this guide, we are using the subdomain **ssh**.
2. **Domain** - Choose the domain you want to use for the tunnel.
3. **Path** - Leave this field empty.
4. **Type** - Choose **SSH** (this is very important).
5. **URL** - Enter **localhost:22** If your SSH port is different from 22, use that port instead.
6. After filling in the details, click the **Save Tunnel** button.
## 6. Setup Cloudflare Tunnel on Coolify
To set up the tunnel on Coolify, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-13.webp" />
Go to the **Servers** page and select the server you want to connect. This is the server you added in [Step 3](#_3-add-your-server-to-coolify)
1. Click on **Cloudflare Tunnels**
2. Click on **Automated** button
You will be prompted to enter the Tunnel Token and SSH domain.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-14.webp" />
1. Enter your **Tunnel Token** (this is the token we copied in [Step 5](#_5-create-a-cloudflare-tunnel))
2. Enter your **SSH Domain** (this is the subdomain we set up in [Step 5](#_5-create-a-cloudflare-tunnel))
3. Click on **Continue** button.
Coolify will now install **cloudflared** on the server and set everything up automatically. This process will take about 30 seconds to 1 minute.
Once completed, you will see that the Cloudflare tunnel is enabled on the Cloudflare Tunnels page, like this:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-15.webp" />
At this point, your server's IP address will be automatically updated to the SSH domain by Coolify.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/automated-16.webp" />
You can now block your SSH port on the server if you wish.
**Congratulations**! You've successfully set up a server that can be accessed by Coolify over SSH using Cloudflare tunnels via your domain.
<Callout type="error" title="HEADS UP!">
**The steps above show how to do the automated setup. Below are the steps for the manual setup.**
</Callout>
## Manual Setup
To manually setup Cloudflare Tunnel:
- You need access to your remote server to install cloudflared (a public IP for your server is not required).
- You need a domain that has it's **DNS managed by Cloudflare**.
### Quick Links to Important Sections:
- [Create a Private SSH Key](#_1-create-a-private-ssh-key-1)
- [Add Public Key to Your Server](#_2-add-public-key-to-your-server-1)
- [Create a Cloudflare Tunnel](#_3-create-a-cloudflare-tunnel)
- [Add your Server to Coolify](#_4-add-your-server-to-coolify)
- [Validate your Server on Coolify](#_5-validate-your-server-on-coolify)
- [Setup Cloudflare Tunnel on Coolify](#_6-setup-cloudflare-tunnel-on-coolify-1)
---
<Callout type="warn" title="Example Data">
The following data is used as an example in this guide. Please replace it with your actual data when following the steps:
- **IPv4 Address of Remote Server:** 203.0.113.1
- **Domain Name:** shadowarcanist.com
- **Username:** root
- **SSH Port:** 22
</Callout>
---
## 1. Create a Private SSH Key
To create a Private SSH Key, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-1.webp" />
1. In your Coolify Dashboard, go to **Keys & Tokens**
2. Click the **+ Add** button
You will be prompted to choose a key type, along with providing a name and description for the key.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-2.webp" />
1. Click on Generate new **ED25519** or **RSA** button to generate a new SSH key.
2. Copy the public key and save it somewhere safe (you'll need it in the next step). Then, click Continue.
## 2. Add Public Key to Your Server
SSH into the server you want to connect to Coolify:
```bash
ssh root@203.0.113.1
```
This server can be on your local network without a public IP address. All you need is SSH access to the terminal to run commands.
Once logged in, add your public key to the authorized keys file:
```bash
$ echo "<PASTE YOUR PUBLIC KEY INSIDE OF THESE QUOTES>" >> ~/.ssh/authorized_keys
```
## 3. Create a Cloudflare Tunnel
To create a Cloudflare Tunnel, first log in to your Cloudflare account and go to the [Zero Trust](https://one.dash.cloudflare.com/) page.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-3.webp" />
1. On the Zero Trust page, go to **Networks** in the sidebar.
2. Click on **Tunnels**
3. Click on **Add a tunnel** button
You will be prompted to choose a tunnel type. Click the **Select Cloudflared** button.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-4.webp" />
You will be prompted to enter a tunnel name. Choose a name that you prefer.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-5.webp" />
Next you will see the configuration page with multiple options to install cloudflared.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-6.webp" />
Select your preferred option and follow the installation instructions provided by Cloudflare on the page.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-7.webp" />
Scroll down a bit and wait for your server (connector) to appear in the list. Once it appears, click the **Next** button.
Then, you will be prompted to add a hostname. This is where we expose our SSH tunnel.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-8.webp" />
1. **Subdomain** - (Optional) You can make SSH accessible on any subdomain. For this guide, we are using the subdomain **ssh**.
2. **Domain** - Choose the domain you want to use for the tunnel.
3. **Path** - Leave this field empty.
4. **Type** - Choose **SSH** (this is very important).
5. **URL** - Enter **localhost:22** If your SSH port is different from 22, use that port instead.
6. After filling in the details, click the **Save Tunnel** button.
## 4. Add your Server to Coolify
To add your server to Coolify, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-9.webp" />
1. In your Coolify Dashboard, go to **Servers**
2. Click the **+ Add** button
You will be prompted to enter details about your server. Make sure the information you provide is accurate, as Coolify will use these details to access your server.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-10.webp" />
1. **Name** - Choose a name to easily identify your server in the dashboard.
2. **Description** - (Optional) Provide a description for your server.
3. **IP Address/Domain** - Enter the SSH domain of your server (which we set up in the previous step).
4. **Port** - Enter the port number your server uses for SSH connections.
5. **User** - Enter the username Coolify will use (it should have root privileges on the server).
6. **Private key** - Select the private key you created in [Step 1](#_1-create-a-private-ssh-key-1)
7. After filling in the details, click the **Continue** button.
## 5. Validate your Server on Coolify
To validate your server, simply click the **Validate Server & Install Docker Engine** button.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-11.webp" />
During this process, Coolify will log in to your server and set up everything needed for Coolify to use the server.
Once the validation is completed, your server page will look like this:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-12.webp" />
## 6. Setup Cloudflare Tunnel on Coolify
To set up the tunnel on Coolify, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-13.webp" />
Go to the **Servers** page and select the server (which we added in the previous step) you want to connect.
1. Click on **Cloudflare Tunnels**
2. Click on **Manual** button
Once completed, you will see that the Cloudflare tunnel is enabled on the Cloudflare Tunnels page, like this:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/server-ssh/manual-14.webp" />
**Congratulations**! You've successfully set up a server that can be accessed by Coolify over SSH using Cloudflare tunnels via your domain.
content/docs/integrations/cloudflare/tunnels/single-resource.mdx
+255
View File
@@ -0,0 +1,255 @@
---
title: "Access Single Resource via Cloudflare Tunnels"
description: "Securely access individual Coolify applications through Cloudflare Tunnels with port mapping, domain configuration, and multi-resource tunneling support."
---
# Access Single Resource via Cloudflare Tunnels
Accessing an Resource deployed on Coolify using a Cloudflare Tunnel allows you to securely reach your app without exposing your server’s IP address or without having a Public IP address for the server.
## Who this is for?
This setup is ideal for people who:
- Don't have a public IP for their server (could be a laptop, raspberry pi etc..).
- Are unable to port forward (e.g., using home internet or on a private network).
- Want to keep their server’s IP address private and avoid exposing it to the public internet.
- Have an app already deployed on Coolify and need an external method to access it securely.
## Setup Requirements
To follow this guide, you'll need:
- A free [Cloudflare](https://cloudflare.com) account.
- You need a domain that has it's **DNS managed by Cloudflare**.
- Your Resource has to be deployed and managed with Coolify.
## Before We Start
- We assume you have Coolify running and an app already deployed.
- If your app requires HTTPS for functionality like cookies or login, then you need to follow the [Full TLS HTTPS guide](/integrations/cloudflare/tunnels/full-tls) after following this guide. This is because in this guide, Cloudflare will manage HTTPS externally, while your app will run over HTTP within Coolify.
## How It Works?
A simple high-level overview diagram to give you a visual idea of how this works:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/high-level-diagram.webp" />
---
### Quick Links to Important Sections:
- [Setup your app for tunneling](#_1-setup-your-app-for-tunneling)
- [Create a Cloudflare Tunnel](#_2-create-a-cloudflare-tunnel)
- [Setup Cloudflare Tunnel on Coolify](#_3-setup-cloudflare-tunnel-on-coolify)
- [Expose Multiple Resource on Different Domains](#expose-multiple-resource-on-different-domains)
- [Known issues and Solutions](#known-issues-and-solutions)
---
<Callout type="warn" title="Example Data">
The following data is used as an example in this guide. Please replace it with your actual data when following the steps:
- **Domain Name:** shadowarcanist.com
- **Ports Exposes:** 80
- **Ports Mapping:** 4477:80
</Callout>
---
## 1. Setup your app for tunneling
To setup your app for tunneling, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/1.webp" />
1. Remove all domains from the **Domains** field.
2. Set the correct port in **Ports Exposed** (the port your app uses).
3. Set the correct ports in **Port Mappings** (left is the host port, right is the app port).
4. Deploy your app by clicking the **Deploy** button.
## 2. Create a Cloudflare Tunnel
To create a Cloudflare Tunnel, first log in to your Cloudflare account and go to the [Zero Trust](https://one.dash.cloudflare.com/) page.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/2.webp" />
1. On the Zero Trust page, go to **Networks** in the sidebar.
2. Click on **Tunnels**
3. Click on **Add a tunnel** button
You will be prompted to choose a tunnel type. Click the **Select Cloudflared** button.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/3.webp" />
You will be prompted to enter a tunnel name. Choose a name that you prefer.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/4.webp" />
Next you will see the configuration page with multiple options to install cloudflared.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/5.webp" />
Copy the install command, which contains the token for your tunnel (token starts with "eyJ"). Make sure to save only the token, removing the command part before it, and store it in a safe place, as we need it later.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/6.webp" />
Scroll down until you see the **Next** button, then click it.
Then, you will be prompted to add a hostname.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/7.webp" />
1. **Subdomain** - (Optional) You can make your app/resource accessible on any subdomain/domain. For this guide, we are not using a subdomain.
2. **Domain** - Choose the domain you want to use for the tunnel.
3. **Path** - Leave this field empty.
4. **Type** - Choose **HTTP** (this is very important).
5. **URL** - Enter **localhost:4477** The port 4477 is the one we mapped to the host system in [Step 1](#_1-setup-your-app-for-tunneling). Replace 4477 with your own port.
6. After filling in the details, click the **Save Tunnel** button.
## 3. Setup Cloudflare Tunnel on Coolify
To set up the tunnel on Coolify, follow these steps:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/8.webp" />
Go to your project on Coolify dashboard and click the **+ New** button to create a new resource.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/9.webp" />
You will see many options to deploy a new app. Search for Cloudflared and click on it.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/10.webp" />
Go to the **Environment Variables** page, enter your tunnel token, and deploy the Cloudflared app. This token was copied in [Step 2](#_2-create-a-cloudflare-tunnel)
**Congratulations**! You've successfully set up a resource that can be accessed by anyone on the internet your domain.
<Callout type="error" title="HEADS UP!">
**The steps above show how to tunnel a single resource. Below are the steps for tunneling multiple resources**
</Callout>
## Tunnel Multiple Resources
The easiest way to tunnel multiple resources is by following our [Tunnel All Resources](/integrations/cloudflare/tunnels/all-resource) guide, which uses Coolify's built-in proxy. However, if you prefer not to use the proxy, there are two alternative methods:
- [Tunnel Multiple Single Resources](#tunnel-multiple-single-resources)
- [Tunnel Coolify](#tunnel-coolify)
Tunneling multiple single resources is straightforward, but tunneling Coolify itself requires additional manual setup.
## Tunnel Multiple Single Resources
If you want to expose different apps individually, you can follow our [Tunnel All Resources](/integrations/cloudflare/tunnels/all-resource), or take an alternate approach:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/11.webp" />
1. Follow [Step 1](#_1-setup-your-app-for-tunneling) for your new resource.
2. Create a new public hostname on Cloudflare Tunnel as described in [Step 2](#_2-create-a-cloudflare-tunnel).
There’s no need to create a separate tunnel for each resources, simply create a new hostname and point it to the port your app is listening on.
## Tunnel Coolify
Tunneling Coolify itself to make it accessible over a domain requires a bit more manual configuration. Here's how you can set it up:
### 1. Create Public Hostnames in Cloudflare Tunnel
Follow [Step 2](#_2-create-a-cloudflare-tunnel) from the main guide to create public hostnames for each service Coolify exposes. Use the following mapping:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/14.webp" />
- **Hostnames**:
1. `app.shadowarcanist.com/terminal/ws` → `localhost:6002` (WebSocket terminal)
2. `realtime.shadowarcanist.com` → `localhost:6001` (Realtime server)
3. `app.shadowarcanist.com` → `localhost:8000` (Coolify dashboard)
- **Type**: HTTP (Ensure you select HTTP for each hostname.)
<Callout type="warn" title="HEADS UP!">
The order of the hostnames matters! Be sure to match it exactly as shown above.
</Callout>
---
### 2. Update Coolify’s `.env` File
After creating public hostnames, update the `.env` file in your Coolify instance located at `/data/coolify/source` to enable connections to the realtime server. Add the following lines:
```bash
APP_ID=<random string>
APP_KEY=<random string>
APP_NAME=Coolify
DB_PASSWORD=<random string>
PUSHER_APP_ID=<random string>
PUSHER_APP_KEY=<random string>
PUSHER_APP_SECRET=<random string>
REDIS_PASSWORD=<random string>
###########
# Add these lines
PUSHER_HOST=realtime.shadowarcanist.com
PUSHER_PORT=443
###########
```
This ensures that Coolify uses the Cloudflare Tunnel for its realtime server.
### 3. Restart Coolify
Run the following command to restart Coolify and apply the changes:
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
```
### 4. Verify the Setup
1. Access your Coolify dashboard at `https://app.shadowarcanist.com`.
2. Test the realtime functionality by visiting `https://app.shadowarcanist.com/realtime` in another browser tab. You should see a notification about a test event.
3. If you know what are you doing, you can check the network tab as well. Search for a websocket connection.
<Callout type="warn" title="HEADS UP!">
If you use a firewall, ensure that the required ports (e.g., `8000`, `6001`, `6002`) are open for internal communication but not exposed to the public internet.
</Callout>
## Known issues and Solutions
When you create a new public hostname in [Step 2](#_2-create-a-cloudflare-tunnel), Cloudflare will create a DNS record for the hostname.
However, if a DNS record for the hostname already exists, Cloudflare won’t create a new one.
In this case, your app won’t work. To fix this issue, follow the steps below:
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/12.webp" />
First, copy your tunnel ID from the Tunnels page on the Cloudflare dashboard.
<ZoomImage src="/docs/images/integrations/cloudflare/tunnels/single-resource/13.webp" />
Create a new DNS record with the following details:
1. In the Cloudflare dashboard, go to **DNS**.
2. Select **Records**.
3. Add a **CNAME** record.
4. Enter the name as `*` or the name of your subdomain (this should match the hostname you have for your app on the tunnel).
5. For the **Target**, enter the tunnel ID followed by `.cfargotunnel.com`
6. Set the proxy status to **Proxied**.
Now, visit the domain of your application, and it should be accessible there.
content/docs/integrations/meta.json
+7
View File
@@ -0,0 +1,7 @@
{
"title": "Integrations",
"pages": [
"cloudflare",
"external:[Crowdsec](https://www.crowdsec.net/blog/securing-automated-app-deployment-crowdsec-and-coolify)"
]
}
content/docs/knowledge-base/change-localhost-key.mdx
+64
View File
@@ -0,0 +1,64 @@
---
title: "Change Localhost Key"
description: "Replace and regenerate Coolify's localhost SSH private key with safe database backup procedures and Docker container key installation."
---
# Change Localhost Key
This guide will show you how to replace the stored localhost private key for Coolify.
<Callout type="warn" title="Caution">
Take a backup of the stored private key in the database before starting this operation.
</Callout>
## Key deletion from database
In the Postgres database in which the data for Coolify is stored, there is a private_keys table.
This table contains the private keys for all servers connected to the Coolify instance.
Be careful to not accidentally delete the wrong keys, as there usually is no way to undo.
1. Navigate to the private_keys table in the Postgres database for Coolify
- Said table is located under the public schema in the database.
2. Select the row that is marked with:
- Row index and ID of 0, as well as the name of "localhost's key"
3. Delete the selected row from the database
- If completed successfully, proceed to the next section.
<Callout type="success" title="Tip">
It helps to do this with a graphical interface for managing the database.
</Callout>
## Installing new keys in the host machine
After the key has been deleted from the database, you need to add the new keys into the correct place in the Coolify data folders.
1. Stop your Coolify instance completely.
2. Find the /ssh/keys directory for your Coolify installation.
- Usually located in /data/ssh/keys if you followed the quick install.
3. Write the public and private keys to the correct files
- Your ED25519 public key shall be stored in id.root@host.docker.internal.pub
- Your ED25519 private key shall be stored in id.root@host.docker.internal
4. Start your Coolify instance
- Coolify will now proceed to seed your keys to the Postgres database.
- Make sure the Database\Seeders\PopulateSshKeysDirectorySeeder does not error.
<Callout type="info" title="Note">
If you receive an output of "SSH key found for the Coolify host machine (localhost)", the operation completed successfully and unless you get any other output, your new key shall now be working.
</Callout>
content/docs/knowledge-base/commands.mdx
+33
View File
@@ -0,0 +1,33 @@
---
title: Commands
description: "Essential Coolify CLI commands for root password reset, email changes, and deleting stuck services via Docker exec and Artisan commands."
---
# Commands
## Root password reset without SMTP
You can use the following method to reset the root user's password, in case you forgot and do not have an SMTP server set, so you cannot request a forgot password.
Login to your server through SSH and execute the following command:
```bash
docker exec -ti coolify sh -c "php artisan root:reset-password"
```
## Root email change
You can change root user's email.
Login to your server through SSH and execute the following command:
```bash
docker exec -ti coolify sh -c "php artisan root:change-email"
```
## Delete a stuck service
You can easily delete a stuck service.
Login to your server through SSH and execute the following command:
```bash
docker exec -ti coolify sh -c "php artisan services:delete"
```
content/docs/knowledge-base/create-root-user-with-env.mdx
+103
View File
@@ -0,0 +1,103 @@
---
title: "Create Root User with Environment Variables"
description: "Create Coolify root user during installation with environment variables including email validation, username requirements, and strong password policies."
---
# Create Root User with Environment Variables
Creating the root user during installation is optional but recommended as it prevents the registration page from ever being exposed.
## Validation Requirements
The following requirements must be met for the root user credentials in a production environment.
### Email
- Must be a valid email address
- Must have a valid DNS record
- Maximum length: 255 characters
### Username
- Minimum length: 3 characters
- Maximum length: 255 characters
- Can only contain letters, numbers, spaces, underscores, and hyphens
### Password
- Minimum length: 8 characters
- Must contain both uppercase and lowercase letters
- Must contain at least one number
- Must contain at least one special symbol
- Must not be a commonly used or compromised password
## Automated Installation Method
1. **Prepare Your Credentials**
Create your root user credentials according to the validation requirements above.
2. **Run Installation Command**
Execute the automated installation script with your prepared credentials:
```bash
env ROOT_USERNAME=RootUser ROOT_USER_EMAIL=example@example.com ROOT_USER_PASSWORD=Password bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
> View the [Scripts Source Code](https://github.com/coollabsio/coolify/blob/main/scripts/install.sh)
<Callout type="info">
The installation script must be run as `root`. If you're not logged in as `root`, the script will use `sudo` to elevate privileges.
```bash
sudo -E env ROOT_USERNAME=RootUser ROOT_USER_EMAIL=example@example.com ROOT_USER_PASSWORD=Password bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
</Callout>
<Callout type="warn">
If any of the environment variables values contain a space, wrap the values in double quotes, for example `ROOT_USERNAME="Root User"`.
</Callout>
3. **Complete Setup**
After configuring the root user credentials, continue with the [installation steps](/get-started/installation#quick-installation-recommended) to complete your Coolify setup.
## Manual Installation Method
1. **Prepare Your Credentials**
Create your root user credentials according to the validation requirements above.
2. **Configure Environment Variables**
Edit the environment variables file:
```bash
nano /data/coolify/source/.env
```
Add the following variables with your prepared credentials:
```bash
ROOT_USERNAME=RootUser
ROOT_USER_EMAIL=example@example.com
ROOT_USER_PASSWORD=Password
```
<Callout type="warn">
If any of the environment variables values contain a space, wrap the values in double quotes, for example `ROOT_USERNAME="Root User"`
</Callout>
3. **Complete Setup**
After configuring the root user credentials, continue with the [installation steps](/get-started/installation#quick-installation-recommended) to complete your Coolify setup.
content/docs/knowledge-base/cron-syntax.mdx
+31
View File
@@ -0,0 +1,31 @@
---
title: "Supported Cron Syntax"
description: "Complete cron syntax reference for Coolify scheduled tasks including standard format and predefined schedules like hourly, daily, and weekly."
---
# Supported Cron Syntax
Coolify supports scheduling automated tasks like cleanups, backups, and more using cron syntax.
## Supported Syntax
### Standard Cron Format
Coolify supports the complete standard cron syntax format (`* * * * *`).
### Predefined Schedules
For convenience, Coolify also supports the following predefined schedule strings:
#### Without @ Prefix
- `every_minute` - Runs every minute
- `hourly` - Runs once per hour
- `daily` - Runs once per day
- `weekly` - Runs once per week
- `monthly` - Runs once per month
- `yearly` - Runs once per year
#### With @ Prefix
- `@every_minute` - Runs every minute
- `@hourly` - Runs once per hour
- `@daily` - Runs once per day
- `@weekly` - Runs once per week
- `@monthly` - Runs once per month
- `@yearly` - Runs once per year
content/docs/knowledge-base/custom-compose-overrides.mdx
+165
View File
@@ -0,0 +1,165 @@
---
title: "Custom Compose Overrides"
description: "Customize Coolify's infrastructure containers using a docker-compose.custom.yml file that persists across upgrades"
---
# Custom Compose Overrides
Coolify runs as a set of Docker Compose services. On every upgrade, the base `docker-compose.yml` and `docker-compose.prod.yml` files are **overwritten** with the latest versions. Any manual edits to those files will be lost.
To make persistent customizations to Coolify's own containers, you can create a **custom override file** that is automatically merged during upgrades.
## How It Works
Place a file at:
```
/data/coolify/source/docker-compose.custom.yml
```
During startup and upgrades, Coolify's upgrade script checks for this file. If it exists, the containers are started with:
```bash
docker compose \
-f docker-compose.yml \
-f docker-compose.prod.yml \
-f docker-compose.custom.yml \
up -d
```
Docker Compose [merges these files](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/?utm_source=coolify.io) in order — properties in later files override the same properties in earlier files. You only need to specify the keys you want to change.
<Callout type="info">
The base files (`docker-compose.yml` and `docker-compose.prod.yml`) are re-downloaded on every upgrade. Your `docker-compose.custom.yml` is **never touched** by the upgrade process, so your customizations persist automatically.
</Callout>
## Service Names
The Compose services are defined with these names — you must use these exact names in your override file:
| Service name | Container name | Description |
|--------------|--------------------|--------------------------|
| `coolify` | `coolify` | Main Coolify application |
| `postgres` | `coolify-db` | PostgreSQL database |
| `redis` | `coolify-redis` | Redis cache |
| `soketi` | `coolify-realtime` | WebSocket server |
## Examples
### Add Container Labels
Add labels for external tooling such as monitoring or log aggregation:
```yaml
services:
coolify:
labels:
com.example.monitoring: "true"
com.example.environment: "production"
```
### Set Resource Limits
Restrict CPU and memory usage for the main Coolify container:
```yaml
services:
coolify:
cpus: 2.0
mem_limit: 2G
mem_reservation: 512M
```
See the Docker Compose documentation for the full list of available attributes: [`cpus`](https://docs.docker.com/reference/compose-file/services/#cpus?utm_source=coolify.io), [`mem_limit`](https://docs.docker.com/reference/compose-file/services/#mem_limit?utm_source=coolify.io), [`mem_reservation`](https://docs.docker.com/reference/compose-file/services/#mem_reservation?utm_source=coolify.io), and [other resource constraints](https://docs.docker.com/reference/compose-file/services/#cpu_count?utm_source=coolify.io).
### Change Port Binding
The port number can be changed via the `APP_PORT` variable in [Coolify's `.env` file](/get-started/installation#manual-installation). However, the override file lets you control *how* the port is bound — something `.env` cannot do.
Bind the Coolify UI to localhost only, so it is only accessible through a reverse proxy:
```yaml
services:
coolify:
ports:
- "127.0.0.1:8000:8080"
```
Or close the port entirely and rely on the Docker network (useful when the Coolify Proxy is enabled and configured for the Coolify Dashboard):
```yaml
services:
coolify:
ports: !override []
```
<Callout type="warn">
If you remove or restrict port access, make sure you have another way to reach the Coolify UI (e.g., a reverse proxy). Otherwise you will lock yourself out.
</Callout>
### Adjust Database Configuration
Add custom PostgreSQL parameters:
```yaml
services:
postgres:
command: postgres -c max_connections=200 -c shared_buffers=512MB
```
### Combine Multiple Customizations
A single override file can modify multiple services:
```yaml
services:
coolify:
mem_limit: 2G
labels:
com.example.monitoring: "true"
postgres:
mem_limit: 1G
redis:
mem_limit: 256M
```
## Important Considerations
<Callout type="error">
A malformed or invalid `docker-compose.custom.yml` can **prevent Coolify from starting**. Always validate your YAML before saving the file.
You can test your configuration without restarting by running:
```bash
cd /data/coolify/source
docker compose \
-f docker-compose.yml \
-f docker-compose.prod.yml \
-f docker-compose.custom.yml \
config
```
If the output is valid merged YAML with no errors, your file is safe to use.
</Callout>
- **Service names must match exactly** — use `coolify`, `postgres`, `redis`, and `soketi`, not the container names.
- **Do not redefine the `image` property** unless you know what you are doing — using an incompatible image will break Coolify.
- **Scalar properties are replaced, list properties are merged** — for example, setting `ports` replaces all port mappings, but `volumes` entries are appended.
- To apply changes immediately without waiting for an upgrade, re-run the upgrade script:
```bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
```
content/docs/knowledge-base/custom-docker-registry.mdx
+68
View File
@@ -0,0 +1,68 @@
---
title: "Custom Docker Registry"
description: "Switch between Docker Hub and GitHub Container Registry (ghcr.io) for pulling Coolify images during installation or runtime"
---
# Custom Docker Registry
If you would like to get Coolify's images from `dockerhub` instead of the default `ghcr.io`, you can do it by setting the `REGISTRY_URL` environment variable to `docker.io`.
## Registry URL (`REGISTRY_URL`)
- Valid values: `docker.io` & `ghcr.io`.
## Automated Installation Method
1. **Run Installation Command**
Execute the automated installation script with your prepared credentials:
```bash
env REGISTRY_URL=docker.io bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
> View the [Scripts Source Code](https://github.com/coollabsio/coolify/blob/main/scripts/install.sh)
<Callout type="info">
The installation script must be run as `root`. If you're not logged in as `root`, the script will use `sudo` to elevate privileges.
```bash
sudo -E env REGISTRY_URL=docker.io bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
</Callout>
## Manual Installation Method
1. **Configure Environment Variables**
Edit the environment variables file:
```bash
nano /data/coolify/source/.env
```
Add the following variables with your prepared credentials:
```bash
REGISTRY_URL=docker.io
```
## Switch after installation
If you want to switch the registry after installation, you can do it by running the following command:
```bash
env REGISTRY_URL=docker.io bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
<Callout type="info">
The installation script must be run as `root`. If you're not logged in as `root`, the script will use `sudo` to elevate privileges.
```bash
sudo -E env REGISTRY_URL=docker.io bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
</Callout>
content/docs/knowledge-base/define-custom-docker-network-with-env.mdx
+76
View File
@@ -0,0 +1,76 @@
---
title: "Define Custom Docker Network with Environment Variables"
description: "Configure custom Docker network CIDR blocks and address pools using environment variables during Coolify installation for advanced network setups"
---
# Define Custom Docker Network with Environment Variables
## Validation Requirements
The following requirements must be met for the custom docker network in a production environment.
### Network Name (`DOCKER_ADDRESS_POOL_BASE`)
- Must be a valid CIDR block, like `10.0.0.0/8`.
### Address Pool Size (`DOCKER_ADDRESS_POOL_SIZE`)
- Must be a valid number, like `10`.
### Force Override (`DOCKER_POOL_FORCE_OVERRIDE`)
- This only needed if you already have a docker address pool on the host and you want to override it.
## Automated Installation Method
1. **Prepare Your Credentials**
Create your root user credentials according to the validation requirements above.
2. **Run Installation Command**
Execute the automated installation script with your prepared credentials:
```bash
env DOCKER_ADDRESS_POOL_BASE=10.0.0.0/8 DOCKER_ADDRESS_POOL_SIZE=10 bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
> View the [Scripts Source Code](https://github.com/coollabsio/coolify/blob/main/scripts/install.sh)
<Callout type="info">
The installation script must be run as `root`. If you're not logged in as `root`, the script will use `sudo` to elevate privileges.
```bash
sudo -E env DOCKER_ADDRESS_POOL_BASE=10.0.0.0/8 DOCKER_ADDRESS_POOL_SIZE=10 bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'
```
</Callout>
3. **Complete Setup**
After configuring the root user credentials, continue with the [installation steps](/get-started/installation#quick-installation-recommended) to complete your Coolify setup.
## Manual Installation Method
1. **Prepare Your Credentials**
Create your root user credentials according to the validation requirements above.
2. **Configure Environment Variables**
Edit the environment variables file:
```bash
nano /data/coolify/source/.env
```
Add the following variables with your prepared credentials:
```bash
DOCKER_ADDRESS_POOL_BASE=10.0.0.0/8
DOCKER_ADDRESS_POOL_SIZE=10
DOCKER_POOL_FORCE_OVERRIDE=false
```
3. **Complete Setup**
After configuring the root user credentials, continue with the [installation steps](/get-started/installation#manual-installation) to complete your Coolify setup.
content/docs/knowledge-base/delete-user.mdx
+52
View File
@@ -0,0 +1,52 @@
---
title: Delete User
description: "Safely delete users from Coolify with automatic team ownership transfer, resource cleanup, and team member reassignment procedures."
---
# Delete User
This guide will show you how to delete a user from the self-hosted Coolify instance.
<Callout type="warn" title="Caution">
If you delete a user, and Coolify still has connection to the servers, it will
delete all the resources on the servers as well, not just from Coolify's
database.
</Callout>
Only users who are in the `root` team can delete users from the UI.
- Go to the `Team` page.
- Switch to `Admin View` tab.
Here you can see all the users registered in Coolify. Click on the `Delete` button next to the user you want to delete.
## Deletion process
<Callout type="info" title="Tip">
The root team or root user cannot be deleted.
</Callout>
Coolify iterate over all the teams of a user and decide of the followings:
### The user is alone in the team
The team and all resources from the server and from Coolify's database are deleted.
### The user is not alone in the team
1. The user is the owner/admin of the team and no other owners/admins found, but the team **has members**:
- The ownership is transferred to the first user in the team who is not the owner/admin.
- The user is removed from the team. No resources are deleted.
2. The user is the owner/admin of the team and no other owners/admins found, but the team has **no members**:
- The team and all resources from the server and from Coolify's database are deleted.
3. The user is not the owner/admin of the team:
- The user is removed from the team. No resources are deleted.
content/docs/knowledge-base/destinations/create.mdx
+120
View File
@@ -0,0 +1,120 @@
---
title: "Creating Destinations"
description: "Create Docker network destinations in Coolify for standalone or Swarm deployments with automatic proxy configuration and network scanning."
---
# Creating Destinations
This guide shows you how to create new destinations in Coolify for deploying your applications and databases.
## Prerequisites
Before creating a destination, ensure you have:
- At least one server connected to Coolify
- Appropriate permissions to manage destinations
- Basic understanding of [Docker networks](https://docs.docker.com/engine/network/)
## Creating a New Destination
### Method 1: From Destinations Page
<ZoomImage src="/docs/images/destinations/create-destination.webp" alt="Create Destination configuration" />
1. Navigate to **Destinations** in the main navigation
2. Click on **+ Add**
3. Fill in the destination details.
### Method 2: From Server Management
<ZoomImage src="/docs/images/destinations/server-create-destination.webp" alt="Server Create Destination configuration" />
1. Go to **Servers** and select your server
2. Navigate to the **Destinations** tab
3. Click **+ Add**
4. Fill in the destination details.
## Configuration Options
<ZoomImage src="/docs/images/destinations/create-destination-modal.webp" alt="Create Destination Modal configuration" />
### Destination Name
- Auto-generated based on server name and network ID
- Can be customized to be more descriptive
### Network Name
- Must be unique per server
- Auto-generated unique identifier (CUID2 format)
- Can be customized to be more descriptive
- Cannot be changed after creation
- Used as the actual Docker network name
### Server Selection
- Choose from available servers in your team
- Server must be online and accessible
- Can not be a [build server](/knowledge-base/server/build-server)
- Determines where the Docker network will be created
### Destination Type
The destination type is **automatically determined** based on your selected server's configuration:
#### Standalone Docker
- **Automatically selected** when the server is configured as a standalone Docker host
- Creates a standard Docker network
- Suitable for single-server deployments
- Supports bridge and custom networks
#### Docker Swarm
- **Automatically selected** when the server is configured as a Docker Swarm manager or worker
- Creates overlay networks for multi-node communication
- Server must have Docker Swarm mode enabled during server setup
- Advanced feature for clustered deployments
<Callout type="info" title="Server Configuration Determines Type">
You cannot manually choose between Standalone Docker and Docker Swarm when creating a destination. The type is determined by how your server was configured when it was added to Coolify.
</Callout>
## Automatic Network Creation
When you create a destination, Coolify automatically:
1. **Creates the Docker network** on the target server
2. **Connects the proxy** (Traefik/Caddy) to the network
3. **Configures network settings** for proper isolation
4. **Enables inter-container communication** within the network
## Network Scanning
You can also scan existing Docker networks on a server and add them as destinations:
<ZoomImage src="/docs/images/destinations/scan-networks.webp" alt="Scan Networks configuration" />
1. Go to **Server** and select your server
2. Navigate to **Destinations**
3. Click **Scan for Destinations**
4. Select existing networks to import and Coolify will create destination entries for them
## Validation and Errors
Common errors when creating destinations:
- **Network already added to this server**: The network name conflicts with an existing one
## After Creation
Once created, your destination will:
- Appear in the destinations list
- Be available for deploying applications and databases
- Have network connectivity configured automatically
- Be ready to host your containerized resources
content/docs/knowledge-base/destinations/index.mdx
+61
View File
@@ -0,0 +1,61 @@
---
title: "Destinations"
description: "Manage Docker network destinations in Coolify for isolated deployment environments supporting standalone Docker and Swarm cluster configurations."
---
# Destinations
Destinations in Coolify are **Docker network endpoints** where your applications, databases, and services are deployed. They represent isolated network environments on your servers that provide containerized isolation and networking for your resources.
## What are Destinations?
A destination is essentially a [Docker network](https://docs.docker.com/engine/network/) that acts as a deployment target for your resources. When you deploy an application or database, it gets deployed to a specific destination (Docker network) on a server, providing network isolation and organization for your containerized workloads.
## Types of Destinations
Coolify differentiates destinations between two types based on the server configuration:
### 1. Standalone Docker
- **Purpose**: For single-server deployments
- **Use Case**: Most common setup for individual servers
- **Network Type**: [Docker bridge](https://docs.docker.com/engine/network/drivers/bridge/) or custom networks
### 2. Docker Swarm
- **Purpose**: For [Docker Swarm](https://docs.docker.com/engine/swarm/) cluster deployments
- **Use Case**: Multi-node cluster environments
- **Network Type**: [Docker overlay networks](https://docs.docker.com/engine/network/drivers/overlay/)
## Key Concepts
### Network Isolation
Each destination provides network isolation between different deployments. Applications deployed to different destinations cannot communicate with each other unless explicitly configured.
### Server Relationship
- Each destination belongs to exactly one server
- A server can have multiple destinations
- Destinations are tied to the server's Docker daemon
### Resource Assignment
Destinations can host multiple types of resources:
- **Applications** (web apps, APIs, microservices)
- **Databases** (PostgreSQL, MySQL, Redis, MongoDB, etc.)
- **Services** (one-click deployments like WordPress, Ghost, etc.)
## Benefits
1. **Isolation**: Network-level separation between different projects or environments
2. **Organization**: Logical grouping of related applications and databases
3. **Security**: Prevents unauthorized network access between different deployments
4. **Flexibility**: Ability to deploy the same application to multiple destinations/servers
5. **Scalability**: Support for multi-server deployments through additional destinations
## Related Topics
- [Creating Destinations](./create.md)
- [Managing Destinations](./manage.md)
content/docs/knowledge-base/destinations/manage.mdx
+94
View File
@@ -0,0 +1,94 @@
---
title: "Managing Destinations"
description: "Manage Coolify destinations including editing, deleting, resource assignment, and connecting service stacks to predefined Docker networks."
---
# Managing Destinations
Learn how to manage your existing destinations in Coolify, and how to assign resources to them.
## Viewing Destinations
### Destinations Overview
Navigate to **Destinations** to see all your destinations across all servers.
<ZoomImage src="/docs/images/destinations/destinations-overview.webp" alt="Destinations Overview configuration" />
### Server-Specific Destinations
Navigate to **Servers** → **[Server Name]** → **Destinations** to view destinations specific to that server.
<ZoomImage src="/docs/images/destinations/destinations-server-overview.webp" alt="Destinations Server Overview configuration" />
## Editing & Deleting Destinations
Click on a destination to access its management page where you can either edit or delete it.
<ZoomImage src="/docs/images/destinations/destinations-settings.webp" alt="Destinations Settings configuration" />
### Basic Information
- **Name**: Update the destination display name
- **Server IP**: View the server IP address where the destination is hosted (read-only)
- **Docker Network**: View the Docker network name (read-only)
### Before You Delete
#### Check for Active Resources
Coolify won't allow you to delete a destination that has active resources. Therefore, before deleting a destination, ensure it's not being used:
1. **Applications**: No applications deployed to this destination
2. **Databases**: No databases running in this destination
3. **Services**: No services configured for this destination
#### Resource Dependencies
Verify that no other resources depend on this destination, to avoid issues after deletion:
- **Environment Variables**: Check for hardcoded references
- **Network Dependencies**: Ensure no cross-destination communication
- **Proxies & Load Balancers**: Update load balancer and proxy configuration
## Assign Resources to a Destination
When you have more then one destination on a server, you will get prompted to select a destination when creating a new resource.
<ZoomImage src="/docs/images/destinations/destinations-selection.webp" alt="Destinations Selection configuration" />
If your resource is already created, you can make a **Clone** of it to another destination:
<ZoomImage src="/docs/images/destinations/destinations-clone.webp" alt="Destinations Clone configuration" />
1. Navigate to the resource's management page over the **Projects** tab.
2. Go to **Resource Operations**
3. Select the destination
<Callout type="warn">
Cloning a resource to another destination will create a new instance of that resource. This will not move the resource or it's data but create a duplicate.
</Callout>
### Service Stacks
Unlike applications or databases, service stacks are not by default connected to the assigned destination. This also includes applications using the [Docker Compose Build Pack](/applications/build-packs/docker-compose). Coolify creates an isolated network for each service stack, allowing you to run multiple instances of the same service on the same server without conflicts.
If you want to connect a service stack to a destination, enable [Connect to Predefined Networks](/knowledge-base/docker/compose#connect-to-predefined-networks) in it's settings. This allows the service stack to communicate with other resources on the same destination.
<Callout type="error" title="WARNING">
Avoid defining network configurations directly in your service stack's `docker-compose.y[a]ml` and instead use Coolify's Destination settings to manage network connections. This could otherwise lead to undesired behavior, such as [Gateway Timeout](/troubleshoot/applications/gateway-timeout) errors.
</Callout>
## Best Practices
1. **Naming Convention**: Use descriptive names for destinations
2. **Resource Organization**: Group related applications in the same destination
3. **Monitoring**: Regularly check destination health and resource usage
4. **Documentation**: Document purpose and configuration of each destination
5. **Cleanup**: Remove unused destinations to reduce server load
content/docs/knowledge-base/destinations/meta.json
+7
View File
@@ -0,0 +1,7 @@
{
"title": "Destinations",
"pages": [
"create",
"manage"
]
}

Some files were not shown because too many files have changed in this diff Show More