docs: enhance volume backups and Docker Compose documentation

- Added important notes regarding the use of Docker named volumes for volume backups, clarifying that bind mounts are not supported.
- Updated the Docker Compose section to differentiate between bind mounts and named volumes, including guidance on when to use each method.
- Included a comparison table to help users choose the appropriate volume method based on their needs.
- Enhanced callouts to emphasize the implications of using bind mounts versus named volumes for data persistence and backup functionality.
This commit is contained in:
Mauricio Siu
2025-12-07 13:55:49 -06:00
parent a7fa8c1473
commit 0003348ad7
2 changed files with 59 additions and 3 deletions

View File

@@ -58,14 +58,20 @@ This section provides advanced configuration options for experienced users. It i
<Callout title="Volumes">
Docker volumes are a way to persist data generated and used by Docker containers. They are particularly useful for maintaining data between container restarts or for sharing data among different containers.
To bind a volume to the host machine, you can use the following syntax in your docker-compose.yml file, but this way will clean up the volumes when a new deployment is made:
Dokploy supports two methods for data persistence in Docker Compose:
### Method 1: Bind Mounts (../files folder)
Use bind mounts for simple persistence needs, configuration files, or when you need direct access to files on the host. This method maps a directory from the host machine into the container.
**Important:** Avoid using absolute host paths, as they will be cleaned up during deployments:
```yaml
volumes:
- "/folder:/path/in/container" ❌
```
It's recommended to use the ../files folder to ensure your data persists between deployments. For example:
Instead, use the `../files` folder to ensure your data persists between deployments:
```yaml
volumes:
@@ -73,6 +79,48 @@ volumes:
- "../files/my-configs:/etc/my-app/config" ✅
```
**Use bind mounts when:**
- You need simple data persistence
- You're mounting configuration files or small datasets
- You want direct file access on the host
- You don't need automated backups via Dokploy's Volume Backups feature
### Method 2: Docker Named Volumes
Use Docker named volumes when you need automated backups, better portability, or Docker-managed storage. Named volumes are managed by Docker and can be backed up automatically using Dokploy's [Volume Backups](/docs/core/volume-backups) feature.
```yaml
services:
app:
image: dokploy/dokploy:latest
volumes:
- my-database:/var/lib/mysql
- my-app-data:/app/data
volumes:
my-database:
my-app-data:
```
**Use named volumes when:**
- You need automated backups to S3 (via Volume Backups)
- You want Docker-managed storage (better portability)
- You're storing databases or large datasets
- You need backup and restore capabilities
**Note:** Volume Backups only work with Docker named volumes, not with bind mounts (`../files`). If you need backup functionality, use named volumes instead of bind mounts.
### Choosing the Right Method
| Feature | Bind Mounts (../files) | Named Volumes |
|---------|----------------------|---------------|
| Simple persistence | ✅ Yes | ✅ Yes |
| Direct host access | ✅ Yes | ❌ No |
| Automated backups | ❌ No | ✅ Yes |
| Docker-managed | ❌ No | ✅ Yes |
| Best for config files | ✅ Yes | ⚠️ Possible but less common |
| Best for databases | ⚠️ Possible | ✅ Recommended |
**Important:** If you need to use files from your repository (configuration files, scripts, etc.), you must move them to Dokploy's File Mounts (via Advanced → Mounts) instead of mounting them directly from the repository. When using AutoDeploy, Dokploy performs a `git clone` on each deployment, which clears the repository directory. Mounting files directly from your repository using relative paths (e.g., `./` or `./config/file.conf`) will cause them to be lost or empty in subsequent deployments. See the [Troubleshooting guide](/docs/core/troubleshooting#using-files-from-your-repository) for more details.
</Callout>

View File

@@ -7,6 +7,10 @@ Volume backups are essential when your service doesn't fit the traditional datab
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.
<Callout type="info">
**Important:** Volume Backups only work with Docker named volumes, not with bind mounts (like the `../files` folder). If you're currently using bind mounts and need backup functionality, you'll need to migrate to named volumes. See the [Docker Compose guide](/docs/core/docker-compose#volumes) for a comparison of both methods and guidance on choosing the right approach for your needs.
</Callout>
## Supported Services
Volume backups are available for:
@@ -16,6 +20,8 @@ Volume backups are available for:
## Setting Up Volume Mounts
Volume Backups require Docker named volumes. If you're using bind mounts (like `../files`), you'll need to switch to named volumes to use this feature.
### For Applications
1. Navigate to your application
@@ -24,7 +30,7 @@ Volume backups are available for:
### For Docker Compose
Define volumes directly in your `docker-compose.yml` file:
Define named volumes directly in your `docker-compose.yml` file. **Note:** Bind mounts (e.g., `../files/my-data:/app/data`) cannot be backed up using Volume Backups—you must use named volumes:
```yaml
services:
@@ -37,6 +43,8 @@ volumes:
my-volume:
```
For more information on choosing between bind mounts and named volumes, see the [Docker Compose volumes section](/docs/core/docker-compose#volumes).
## Practical Example: N8N Backup
Let's walk through a common scenario using N8N, which runs on SQLite and stores data in Docker volumes.