mirror of
https://github.com/Dokploy/website.git
synced 2026-06-18 05:35:28 +02:00
Merge pull request #50 from Dokploy/fix/add-volume-backups-docs
docs: add volume backups documentation and troubleshooting tips
This commit is contained in:
Mauricio Siu
GitHub
115
apps/docs/content/docs/core/(Git-Sources)/Docker.mdx
Normal file
115
apps/docs/content/docs/core/(Git-Sources)/Docker.mdx
Normal file
@@ -0,0 +1,115 @@
|
||||
---
|
||||
title: Docker Registry
|
||||
description: 'Configure your Docker Registry repositories for deployments. This includes setting up access tokens, repository names, and authentication.'
|
||||
---
|
||||
|
||||
Dokploy provides seamless integration with Docker Registry repositories, allowing you to deploy applications directly from your container images. This feature is available for single applications and supports both public and private registries.
|
||||
|
||||
## Configuration Overview
|
||||
|
||||
To connect a Docker Registry to your application:
|
||||
|
||||
1. Navigate to your application's **General** tab
|
||||
2. Select **Docker** as the source
|
||||
3. Configure the following settings:
|
||||
|
||||
| Setting | Description |
|
||||
|---------|-------------|
|
||||
| **Docker Image** | Full name of the Docker image (e.g., `nginx:latest`, `myorg/myapp:v1.0`) |
|
||||
| **Docker Registry URL** | Registry URL (defaults to Docker Hub if not specified) |
|
||||
| **Docker Registry Username** | Username for registry authentication |
|
||||
| **Docker Registry Password** | Password or access token for authentication |
|
||||
|
||||
<Callout type="info">
|
||||
For private registries, authentication is required. For public images, you can leave the username and password fields empty.
|
||||
</Callout>
|
||||
|
||||
## Docker Hub Integration
|
||||
|
||||
Docker Hub is the default registry and supports both username/password and token-based authentication.
|
||||
|
||||
### Method 1: Username and Password
|
||||
|
||||
1. **Username**: Enter your Docker Hub username
|
||||
2. **Password**: Enter your Docker Hub password
|
||||
|
||||
### Method 2: Access Token (Recommended)
|
||||
|
||||
Using access tokens is more secure and allows fine-grained permissions:
|
||||
|
||||
1. **Create Access Token**:
|
||||
- Go to [Docker Hub Settings](https://hub.docker.com/settings/security) → **Personal Access Tokens**
|
||||
- Click **Generate New Token**
|
||||
- Set description: `Dokploy-Docker-Hub-Token`
|
||||
- Select **Read-only** permissions
|
||||
- Click **Generate**
|
||||
|
||||
2. **Configure in Dokploy**:
|
||||
- **Username**: Your Docker Hub username
|
||||
- **Password**: Paste the generated access token
|
||||
- **Registry URL**: Leave empty (defaults to Docker Hub)
|
||||
|
||||
3. **Deploy**: Click **Save** and then **Deploy** from the General tab
|
||||
|
||||
## GitHub Container Registry (GHCR)
|
||||
|
||||
GHCR allows you to store container images alongside your GitHub repositories.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Your Docker image must already be published to GHCR
|
||||
- You need a GitHub Personal Access Token with appropriate permissions
|
||||
|
||||
### Setup Process
|
||||
|
||||
1. **Create GitHub Personal Access Token**:
|
||||
- Go to [GitHub Settings](https://github.com/settings/tokens) → **Personal Access Tokens**
|
||||
- Click **Generate new token (classic)**
|
||||
- Set token name: `Dokploy-GHCR-Token`
|
||||
- Select the following scopes:
|
||||
- `repo` - Access to repositories
|
||||
- `workflow` - Access to GitHub Actions
|
||||
- `write:packages` - Upload packages
|
||||
- `delete:packages` - Delete packages
|
||||
- Click **Generate token**
|
||||
|
||||
2. **Configure in Dokploy**:
|
||||
- **Docker Image**: `ghcr.io/username/repository:tag`
|
||||
- **Registry URL**: `ghcr.io`
|
||||
- **Username**: Your GitHub username
|
||||
- **Password**: Paste the generated personal access token
|
||||
|
||||
3. **Deploy**: Click **Save** and then **Deploy** from the General tab
|
||||
|
||||
|
||||
### Public Images
|
||||
|
||||
For public images from any registry:
|
||||
|
||||
- **Docker Image**: Full image path (e.g., `quay.io/prometheus/prometheus:latest`)
|
||||
- **Registry URL**: Registry domain (if not Docker Hub)
|
||||
- **Username**: Leave empty
|
||||
- **Password**: Leave empty
|
||||
|
||||
## Best Practices
|
||||
|
||||
<Callout type="tip">
|
||||
**Security Recommendations:**
|
||||
- Use access tokens instead of passwords when possible
|
||||
- Grant minimal required permissions to tokens
|
||||
- Regularly rotate access tokens
|
||||
- Use private registries for sensitive applications
|
||||
</Callout>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common issues and solutions:
|
||||
|
||||
- **Authentication Failed**: Verify your credentials and token permissions
|
||||
- **Image Not Found**: Check the image name and tag spelling
|
||||
- **Pull Rate Limits**: Consider using authenticated requests or private registries
|
||||
- **Registry Timeout**: Verify the registry URL is accessible from your Dokploy instance
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -28,7 +28,8 @@ Comparison of the following deployment tools:
|
||||
| **Rollbacks** | ✅ | ✅ | ❌ | ✅ |
|
||||
| **Shared Enviroment Variables** | ✅ | ❌ | ❌ | ✅ |
|
||||
| **Schedules Jobs** | ✅ | ❌ | ❌ | ✅ |
|
||||
| **Cloudflare Tunnels** | ❌ | ❌ | ❌ | ✅ |
|
||||
| **Cloudflare Tunnels** | ❌ | ❌ | ❌ | ✅ |
|
||||
| **Volume Backups** | ✅ | ❌ | ❌ | ❌ |
|
||||
| **Preview Deployments** | ✅ | ❌ | ❌ | ✅ |
|
||||
| **Teams** | ✅ | ❌ | ❌ | ✅ |
|
||||
| **Cloud/Paid Version** | ✅ | ✅ | ✅ | ✅ |
|
||||
|
||||
@@ -30,7 +30,7 @@ services:
|
||||
|
||||
When Isolated Deployments is enabled, Dokploy will:
|
||||
|
||||
1. Add a prefix to all your defined volumes and networks
|
||||
1. Add a prefix to all your defined networks
|
||||
2. Create a network based on your service's appName and associate it with each service in your compose file
|
||||
3. Connect the Traefik load balancer to this isolated network, maintaining service isolation while ensuring proper routing
|
||||
|
||||
|
||||
@@ -60,3 +60,18 @@ The "Container Port" specified in the domain settings is exclusively for routing
|
||||
When using the `Static` build type or `Nixpacks` and `Publish Directory` build type, you need to use the port `80` when creating a domain.
|
||||
|
||||
|
||||
## Adding WWW to your domain
|
||||
|
||||
If you want to add WWW to your domain, you can do it by adding a CNAME record to your DNS provider.
|
||||
|
||||
For example, if your domain is `example.com`, you can add a CNAME record to your DNS provider with the following configuration:
|
||||
|
||||
- TYPE: CNAME
|
||||
- NAME: www
|
||||
- VALUE: example.com
|
||||
|
||||
Create the domain in dokploy, using the host `www.example.com`
|
||||
|
||||
Now in dokploy, you can go to application -> advanced -> redirects (Select the preset www to non-www) and click on save.
|
||||
|
||||
now everytime you access `www.example.com` it will redirect to `example.com`
|
||||
|
||||
@@ -37,6 +37,7 @@
|
||||
"(examples)",
|
||||
"auto-deploy",
|
||||
"schedule-jobs",
|
||||
"volume-backups",
|
||||
"providers",
|
||||
"watch-paths",
|
||||
"---Advanced---",
|
||||
|
||||
@@ -118,6 +118,11 @@ serviceName: app
|
||||
port: 3000
|
||||
```
|
||||
|
||||
- Another reason of the domains are not working it may be because the healthchecks you've defined are not working, so this will cause the domains never work, so you have two options:
|
||||
|
||||
1. Remove the healthcheck from the service
|
||||
2. Make sure the healthcheck is working
|
||||
|
||||
## Getting "Bad Gateway Error" When Accessing Your Application Domain
|
||||
|
||||
If you're encountering a Bad Gateway Error when accessing your application through its domain, this typically indicates one of several common configuration issues:
|
||||
|
||||
142
apps/docs/content/docs/core/volume-backups.mdx
Normal file
142
apps/docs/content/docs/core/volume-backups.mdx
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: "Volume Backups"
|
||||
description: "Learn how to backup your volumes using Dokploy's Volume Backups feature"
|
||||
---
|
||||
|
||||
Volume backups are essential when your service doesn't fit the traditional database backup solutions. This is common when your application uses SQLite databases or doesn't have a database at all, making Dokploy's dedicated database backup features (PostgreSQL, MySQL, MongoDB, etc.) unsuitable for your use case.
|
||||
|
||||
Volume backups allow you to backup [Docker named volumes](https://docs.docker.com/engine/storage/volumes/) to S3 destinations, providing a comprehensive backup solution for any type of data stored in volumes.
|
||||
|
||||
## Supported Services
|
||||
|
||||
Volume backups are available for:
|
||||
|
||||
1. **Applications** - Single container applications
|
||||
2. **Docker Compose** - Multi-container applications
|
||||
|
||||
## Setting Up Volume Mounts
|
||||
|
||||
### For Applications
|
||||
|
||||
1. Navigate to your application
|
||||
2. Go to **Advanced** → **Mounts**
|
||||
3. Create a new mount and select **Volume Mount** option
|
||||
|
||||
### For Docker Compose
|
||||
|
||||
Define volumes directly in your `docker-compose.yml` file:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
image: dokploy/dokploy:latest
|
||||
volumes:
|
||||
- my-volume:/app/data
|
||||
|
||||
volumes:
|
||||
my-volume:
|
||||
```
|
||||
|
||||
## Practical Example: N8N Backup
|
||||
|
||||
Let's walk through a common scenario using N8N, which runs on SQLite and stores data in Docker volumes.
|
||||
|
||||
### N8N Docker Compose Configuration
|
||||
|
||||
```yaml
|
||||
version: "3.8"
|
||||
services:
|
||||
n8n:
|
||||
image: docker.n8n.io/n8nio/n8n:1.83.2
|
||||
restart: always
|
||||
environment:
|
||||
- N8N_HOST=${N8N_HOST}
|
||||
- N8N_PORT=${N8N_PORT}
|
||||
- N8N_PROTOCOL=http
|
||||
- NODE_ENV=production
|
||||
- WEBHOOK_URL=https://${N8N_HOST}/
|
||||
- GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
|
||||
- N8N_SECURE_COOKIE=false
|
||||
volumes:
|
||||
- n8n_data:/home/node/.n8n
|
||||
|
||||
volumes:
|
||||
n8n_data:
|
||||
```
|
||||
|
||||
Since N8N uses SQLite (stored in the `n8n_data` volume), we can't use Dokploy's database backup features. Instead, we'll backup the entire volume.
|
||||
|
||||
## Creating Volume Backups
|
||||
|
||||
### Backup Configuration
|
||||
|
||||
1. Deploy your N8N template
|
||||
2. Navigate to **Volume Backups** section
|
||||
3. Create a new volume backup with these settings:
|
||||
|
||||
| Setting | Value | Description |
|
||||
|---------|-------|-------------|
|
||||
| **Name** | `my-n8n-backup` | Unique identifier for your backup |
|
||||
| **Schedule** | `0 0 * * *` | Daily backup at midnight (cron format) |
|
||||
| **Destination** | Your S3 destination | Must be configured in your account |
|
||||
| **Service Name** | `n8n` | Auto-complete will suggest available services |
|
||||
| **Volume Name** | `n8n_data` | Auto-filled when service is selected |
|
||||
| **Backup Prefix** | Optional | Additional prefix for backup files |
|
||||
| **Turn off Container** | Optional | See safety considerations below |
|
||||
| **Enabled** | ✓ | Enable the backup schedule |
|
||||
|
||||
### Safety Considerations
|
||||
|
||||
**Turn off Container during backup** option provides two approaches:
|
||||
|
||||
- **Container OFF** (Recommended): Safer option that prevents data corruption during backup, this will stop the container during the backup, and then start it again after the backup is done.
|
||||
- **Container ON**: Faster but may cause inconsistencies if the service is actively writing to the volume
|
||||
|
||||
<Callout type="warning">
|
||||
When backing up with the container running, there's a risk of data corruption if the application is actively writing to the volume during backup.
|
||||
</Callout>
|
||||
|
||||
## Restoring Volume Backups
|
||||
|
||||
### Restore Process
|
||||
|
||||
1. Navigate to **Volume Backups** section
|
||||
2. Select **Restore Volume** option
|
||||
3. Choose your S3 destination where the backup is stored
|
||||
4. Select the specific backup you want to restore
|
||||
5. Enter the target volume name for restoration
|
||||
|
||||
### Volume Naming for Docker Compose
|
||||
|
||||
For Docker Compose services, volume names follow a specific pattern:
|
||||
`{appName}_{volumeName}`
|
||||
|
||||
**Example**: If your app name is `n8n-n8n-kqlble`, the volume name would be:
|
||||
`n8n-n8n-kqlble_n8n_data`
|
||||
|
||||
### Important Restore Considerations
|
||||
|
||||
<Callout type="warning">
|
||||
**Before restoring:**
|
||||
- Ensure the target volume doesn't already exist
|
||||
- Stop any containers using the volume
|
||||
- Remove the existing volume if necessary
|
||||
|
||||
The restore will fail if the volume is in use or already exists.
|
||||
</Callout>
|
||||
|
||||
### Finding the Correct Volume Name
|
||||
|
||||
1. **Check your Docker Compose file** to understand the volume structure
|
||||
2. **Verify the app name** in Dokploy (usually under the name of your service)
|
||||
3. **Use the pattern**: `{appName}_{volumeName}` for Docker Compose services
|
||||
4. **For single applications**: Volume names are typically simpler and match your mount configuration
|
||||
|
||||
This ensures your restored volume will be properly recognized and used by your Docker Compose services when they restart.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user