Docker Integration

Docker sidecar container for automatic volume and database backups. Deploy alongside your application containers.

v1.0.0Updated 2026-01-01
View on Docker Hub

Overview

The LOX Docker sidecar runs alongside your application containers to provide automated backups for:

  • Docker volumes (files, uploads, configurations)
  • MySQL/MariaDB databases
  • PostgreSQL databases
  • Any file-based data in shared volumes

Quick Start

Basic Volume Backup

# docker-compose.yml
version: '3.8'

services:
  app:
    image: your-app:latest
    volumes:
      - app_data:/var/www/html/uploads

  lox-backup:
    image: loxbackup/sidecar:latest
    environment:
      LOX_API_KEY: ${LOX_API_KEY}
      BACKUP_SCHEDULE: "0 3 * * *"  # Daily at 3 AM
      BACKUP_NAME: "my-app"
    volumes:
      - app_data:/backup/data:ro

volumes:
  app_data:

With MySQL Database

# docker-compose.yml
version: '3.8'

services:
  app:
    image: wordpress:latest
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wp_user
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - wp_content:/var/www/html/wp-content

  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wp_user
      MYSQL_PASSWORD: ${DB_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql

  lox-backup:
    image: loxbackup/sidecar:latest
    environment:
      LOX_API_KEY: ${LOX_API_KEY}
      BACKUP_SCHEDULE: "0 */6 * * *"  # Every 6 hours
      BACKUP_NAME: "wordpress-prod"
      # Database configuration
      DB_TYPE: mysql
      DB_HOST: db
      DB_PORT: 3306
      DB_NAME: wordpress
      DB_USER: wp_user
      DB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - wp_content:/backup/data:ro
    depends_on:
      - db

volumes:
  wp_content:
  db_data:

With PostgreSQL Database

# docker-compose.yml
version: '3.8'

services:
  app:
    image: your-app:latest
    environment:
      DATABASE_URL: postgres://app_user:${DB_PASSWORD}@db:5432/myapp
    volumes:
      - uploads:/app/uploads

  db:
    image: postgres:15
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: app_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pg_data:/var/lib/postgresql/data

  lox-backup:
    image: loxbackup/sidecar:latest
    environment:
      LOX_API_KEY: ${LOX_API_KEY}
      BACKUP_SCHEDULE: "0 2 * * *"
      BACKUP_NAME: "myapp-prod"
      # PostgreSQL configuration
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_NAME: myapp
      DB_USER: app_user
      DB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - uploads:/backup/data:ro
    depends_on:
      - db

volumes:
  uploads:
  pg_data:

Environment Variables

Required

VariableDescription
LOX_API_KEYYour LOX API key from backlox.com

Backup Configuration

VariableDefaultDescription
BACKUP_NAMEdocker-backupName prefix for backups
BACKUP_SCHEDULE0 3 * * *Cron expression for backup schedule
BACKUP_RETENTION30Days to retain backups
BACKUP_ON_STARTfalseRun backup when container starts
BACKUP_PATHS/backup/dataComma-separated paths to backup

Database Configuration

VariableDefaultDescription
DB_TYPE-Database type: mysql, postgres, or mariadb
DB_HOST-Database hostname
DB_PORTautoDatabase port (3306 for MySQL, 5432 for PostgreSQL)
DB_NAME-Database name to backup
DB_USER-Database username
DB_PASSWORD-Database password
DB_EXTRA_ARGS-Extra arguments for mysqldump/pg_dump

Advanced Options

VariableDefaultDescription
LOX_API_URLhttps://backlox.com/apiCustom API endpoint
COMPRESSIONgzipCompression: gzip, zstd, or none
EXCLUDE_PATTERNS-Comma-separated glob patterns to exclude
HEALTHCHECK_PORT8080Port for healthcheck endpoint
LOG_LEVELinfoLog verbosity: debug, info, warn, error

Common Patterns

Multiple Volumes

lox-backup:
  image: loxbackup/sidecar:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    BACKUP_NAME: "multi-volume-app"
    BACKUP_PATHS: "/backup/uploads,/backup/config,/backup/logs"
  volumes:
    - uploads:/backup/uploads:ro
    - config:/backup/config:ro
    - logs:/backup/logs:ro

Exclude Patterns

lox-backup:
  image: loxbackup/sidecar:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    BACKUP_NAME: "app-filtered"
    EXCLUDE_PATTERNS: "*.log,*.tmp,cache/*,node_modules/*"
  volumes:
    - app_data:/backup/data:ro

Multiple Databases

# For multiple databases, use multiple sidecar containers
lox-backup-main:
  image: loxbackup/sidecar:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    BACKUP_NAME: "main-db"
    DB_TYPE: postgres
    DB_HOST: main-db
    DB_NAME: main_database
    DB_USER: admin
    DB_PASSWORD: ${MAIN_DB_PASSWORD}

lox-backup-analytics:
  image: loxbackup/sidecar:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    BACKUP_NAME: "analytics-db"
    DB_TYPE: postgres
    DB_HOST: analytics-db
    DB_NAME: analytics
    DB_USER: admin
    DB_PASSWORD: ${ANALYTICS_DB_PASSWORD}

Kubernetes Deployment

# kubernetes/backup-cronjob.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: lox-backup
spec:
  schedule: "0 3 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: loxbackup/sidecar:latest
            env:
            - name: LOX_API_KEY
              valueFrom:
                secretKeyRef:
                  name: lox-secrets
                  key: api-key
            - name: BACKUP_NAME
              value: "k8s-app"
            - name: DB_TYPE
              value: "postgres"
            - name: DB_HOST
              value: "postgres-service"
            - name: DB_NAME
              value: "myapp"
            - name: DB_USER
              valueFrom:
                secretKeyRef:
                  name: db-secrets
                  key: username
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: db-secrets
                  key: password
            volumeMounts:
            - name: app-data
              mountPath: /backup/data
              readOnly: true
          volumes:
          - name: app-data
            persistentVolumeClaim:
              claimName: app-data-pvc
          restartPolicy: OnFailure

Health Checks

The sidecar exposes health endpoints for container orchestration:

EndpointDescription
/healthLiveness check - container is running
/readyReadiness check - can accept backup requests
/statusDetailed status with last backup info
/metricsPrometheus metrics endpoint
# Docker Compose with health check
lox-backup:
  image: loxbackup/sidecar:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 10s

Manual Backup Trigger

You can trigger a backup manually without waiting for the schedule:

# Trigger backup via exec
docker exec lox-backup /backup now

# Or via HTTP endpoint
curl -X POST http://localhost:8080/backup

Backup Structure

docker-myapp-20240115_030000.tar.gz
├── database.sql        # Database dump (if DB configured)
├── data/               # Contents of /backup/data
│   ├── uploads/
│   ├── config/
│   └── ...
└── manifest.json       # Backup metadata

Troubleshooting

Cannot connect to database

Ensure the database container is running and the sidecar has depends_on set. Verify DB_HOST matches the service name in docker-compose.

Permission denied on volumes

The sidecar runs as non-root by default. Ensure volumes are readable by UID 1000 or set user: root in compose file.

Backup too large / timing out

Use EXCLUDE_PATTERNS to skip unnecessary files. Consider using COMPRESSION: zstd for better compression.

View logs

Use docker logs lox-backup to see backup status and any errors. Set LOG_LEVEL: debug for verbose output.

Complete Example

Full production-ready setup with WordPress, MySQL, and automated backups:

# docker-compose.yml
version: '3.8'

services:
  wordpress:
    image: wordpress:6-php8.2
    restart: unless-stopped
    environment:
      WORDPRESS_DB_HOST: mysql
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - wp_content:/var/www/html/wp-content
    ports:
      - "80:80"
    depends_on:
      mysql:
        condition: service_healthy

  mysql:
    image: mysql:8.0
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  lox-backup:
    image: loxbackup/sidecar:latest
    restart: unless-stopped
    environment:
      # LOX Configuration
      LOX_API_KEY: ${LOX_API_KEY}
      BACKUP_NAME: "wordpress-production"
      BACKUP_SCHEDULE: "0 */6 * * *"  # Every 6 hours
      BACKUP_RETENTION: 30

      # Database
      DB_TYPE: mysql
      DB_HOST: mysql
      DB_PORT: 3306
      DB_NAME: wordpress
      DB_USER: wordpress
      DB_PASSWORD: ${MYSQL_PASSWORD}

      # Options
      COMPRESSION: zstd
      EXCLUDE_PATTERNS: "*.log,cache/*"
      LOG_LEVEL: info
    volumes:
      - wp_content:/backup/data:ro
    depends_on:
      mysql:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  wp_content:
  mysql_data:

# .env file (not committed to git)
# LOX_API_KEY=lox_xxxxxxxxxxxx
# MYSQL_PASSWORD=secure_password
# MYSQL_ROOT_PASSWORD=very_secure_password
← GitHub ActionsCLI Tool →