diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 11f31a41..9f4d2871 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -452,6 +452,15 @@ export default defineConfig({ { text: 'Domains', link: '/knowledge-base/domains' }, ] }, + { + text: 'Destinations', + collapsed: true, + items: [ + { text: 'Overview', link: '/knowledge-base/destinations/index' }, + { text: 'Creating Destinations', link: '/knowledge-base/destinations/create' }, + { text: 'Managing Destinations', link: '/knowledge-base/destinations/manage' }, + ] + }, { text: 'Resources', collapsed: true, diff --git a/docs/knowledge-base/destinations/create.md b/docs/knowledge-base/destinations/create.md new file mode 100644 index 00000000..620ba948 --- /dev/null +++ b/docs/knowledge-base/destinations/create.md @@ -0,0 +1,111 @@ +# 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 + + + +1. Navigate to **Destinations** in the main navigation +2. Click on **+ Add** +3. Fill in the destination details. + +### Method 2: From Server Management + + + +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 + + + +### 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](/builds/servers) +- 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 + +::: tip 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. +::: + +## 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: + + + +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 diff --git a/docs/knowledge-base/destinations/index.md b/docs/knowledge-base/destinations/index.md new file mode 100644 index 00000000..30fbeef2 --- /dev/null +++ b/docs/knowledge-base/destinations/index.md @@ -0,0 +1,56 @@ +# 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) diff --git a/docs/knowledge-base/destinations/manage.md b/docs/knowledge-base/destinations/manage.md new file mode 100644 index 00000000..ad462ed1 --- /dev/null +++ b/docs/knowledge-base/destinations/manage.md @@ -0,0 +1,81 @@ +# 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. + + +### Server-Specific Destinations + +Navigate to **Servers** → **[Server Name]** → **Destinations** to view destinations specific to that server. + + +## Editing & Deleting Destinations + +Click on a destination to access its management page where you can either edit or delete it. + + + +### 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. + + + +If your resource is already created, you can make a **Clone** of it to another destination: + + + +1. Navigate to the resource's management page over the **Projects** tab. +2. Go to **Resource Operations** +3. Select the destination + +::: warning +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. +::: + +### 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](/builds/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. + +::: danger 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** errors. +::: + +## 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 diff --git a/docs/public/images/destinations/create-destination-modal.webp b/docs/public/images/destinations/create-destination-modal.webp new file mode 100644 index 00000000..4e714f2d Binary files /dev/null and b/docs/public/images/destinations/create-destination-modal.webp differ diff --git a/docs/public/images/destinations/create-destination.webp b/docs/public/images/destinations/create-destination.webp new file mode 100644 index 00000000..9f653a75 Binary files /dev/null and b/docs/public/images/destinations/create-destination.webp differ diff --git a/docs/public/images/destinations/destinations-clone.webp b/docs/public/images/destinations/destinations-clone.webp new file mode 100644 index 00000000..a01a433b Binary files /dev/null and b/docs/public/images/destinations/destinations-clone.webp differ diff --git a/docs/public/images/destinations/destinations-overview.webp b/docs/public/images/destinations/destinations-overview.webp new file mode 100644 index 00000000..fa1af788 Binary files /dev/null and b/docs/public/images/destinations/destinations-overview.webp differ diff --git a/docs/public/images/destinations/destinations-selection.webp b/docs/public/images/destinations/destinations-selection.webp new file mode 100644 index 00000000..1cfb26b9 Binary files /dev/null and b/docs/public/images/destinations/destinations-selection.webp differ diff --git a/docs/public/images/destinations/destinations-server-overview.webp b/docs/public/images/destinations/destinations-server-overview.webp new file mode 100644 index 00000000..2ede0054 Binary files /dev/null and b/docs/public/images/destinations/destinations-server-overview.webp differ diff --git a/docs/public/images/destinations/destinations-settings.webp b/docs/public/images/destinations/destinations-settings.webp new file mode 100644 index 00000000..da64ca12 Binary files /dev/null and b/docs/public/images/destinations/destinations-settings.webp differ diff --git a/docs/public/images/destinations/scan-networks.webp b/docs/public/images/destinations/scan-networks.webp new file mode 100644 index 00000000..7c834202 Binary files /dev/null and b/docs/public/images/destinations/scan-networks.webp differ diff --git a/docs/public/images/destinations/server-create-destination.webp b/docs/public/images/destinations/server-create-destination.webp new file mode 100644 index 00000000..d392c490 Binary files /dev/null and b/docs/public/images/destinations/server-create-destination.webp differ