first version of the knowledge base :)

20 - Knowledge/containers/persistent-volumes.md

@@ -0,0 +1,125 @@
+---
+title: Persistent Volumes
+description: Storage patterns for keeping container data durable across restarts and upgrades
+tags:
+  - containers
+  - docker
+  - storage
+category: containers
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Persistent Volumes
+
+## Introduction
+
+Containers are disposable, but application data usually is not. Persistent volumes provide storage that survives container restarts, recreation, and image upgrades.
+
+## Purpose
+
+Use persistent volumes to:
+
+- Preserve databases, uploads, and application state
+- Separate data lifecycle from container lifecycle
+- Simplify backup and restore workflows
+- Reduce accidental data loss during redeployments
+
+## Architecture Overview
+
+Docker storage typically falls into three categories:
+
+- Named volumes: managed by Docker and usually the best default for persistent app data
+- Bind mounts: direct host paths mounted into a container
+- Tmpfs mounts: memory-backed storage for temporary data
+
+## Storage Patterns
+
+### Named volumes
+
+Named volumes are portable within a host and reduce the chance of coupling to host directory layouts.
+
+```bash
+docker volume create postgres-data
+docker run -d \
+  --name db \
+  -v postgres-data:/var/lib/postgresql/data \
+  postgres:16
+```
+
+### Bind mounts
+
+Bind mounts are useful when:
+
+- The application expects editable configuration files
+- You need direct host visibility into files
+- Backups are based on host file paths
+
+Example:
+
+```bash
+docker run -d \
+  --name caddy \
+  -v /srv/caddy/Caddyfile:/etc/caddy/Caddyfile:ro \
+  -v /srv/caddy/data:/data \
+  caddy:2
+```
+
+### Permissions and ownership
+
+Many container storage issues come from mismatched UID and GID values between the host and containerized process. Check the image documentation and align ownership before assuming the application is broken.
+
+## Configuration Example
+
+Compose example with named volumes:
+
+```yaml
+services:
+  app:
+    image: ghcr.io/example/app:1.2.3
+    volumes:
+      - app-data:/var/lib/app
+
+  db:
+    image: postgres:16
+    volumes:
+      - db-data:/var/lib/postgresql/data
+
+volumes:
+  app-data:
+  db-data:
+```
+
+## Troubleshooting Tips
+
+### Data disappears after updating a container
+
+- Verify the service is writing to the mounted path
+- Check whether a bind mount accidentally hides expected image content
+- Inspect mounts with `docker inspect <container>`
+
+### Permission denied errors
+
+- Check ownership and mode bits on bind-mounted directories
+- Match container user expectations to host permissions
+- Avoid mounting sensitive directories with broad write access
+
+### Backups restore but the app still fails
+
+- Confirm the restored data matches the application version
+- Restore metadata such as permissions and database WAL files if applicable
+- Test restores on a separate host before using them in production
+
+## Best Practices
+
+- Use named volumes for most stateful container data
+- Use bind mounts deliberately for human-managed configuration
+- Keep backups separate from the production host
+- Record where every service stores its critical state
+- Test restore procedures, not only backup creation
+
+## References
+
+- [Docker: Volumes](https://docs.docker.com/engine/storage/volumes/)
+- [Docker: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts/)
+- [Docker: Tmpfs mounts](https://docs.docker.com/engine/storage/tmpfs/)