Skip to content

README.en.md

Latest commit

 

History

History
238 lines (173 loc) · 5.52 KB

README.en.md

File metadata and controls

238 lines (173 loc) · 5.52 KB

Docker Ofelia Stack

GitHub Release License

🇩🇪 Deutsch | 🇫🇷 Français

A production-ready Docker stack for Ofelia - a modern cron job scheduler for Docker containers with integrated logrotate functionality.

What is Ofelia?

Ofelia is a Docker job scheduler that enables running cron jobs directly in Docker containers. Instead of running a separate cron daemon in each container, Ofelia centrally manages all time-based tasks via Docker labels.

Features

  • Central management of all cron jobs for Docker containers
  • Automatic log rotation with configurable schedule
  • Secure configuration (Docker socket read-only)
  • Timezone support (Europe/Berlin)
  • Job logging in separate directory
  • Production-ready with restart policy

Requirements

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • Access to /var/run/docker.sock

Installation

  1. Clone repository:
git clone https://github.com/csaeum/DockerStackOfelia.git
cd DockerStackOfelia
  1. Adjust environment variables (optional):
cp .env.example .env
nano .env
  1. Start stack:
docker-compose up -d

Configuration

Environment Variables (.env)

COMPOSE_PROJECT_NAME=ofelia      # Prefix for container names
TIMEZONE=Europe/Berlin            # Timezone for cron jobs

Define Cron Jobs in Other Containers

Add labels to your Docker containers to define cron jobs:

services:
  myapp:
    image: myapp:latest
    labels:
      ofelia.enabled: "true"
      ofelia.job-exec.backup.schedule: "0 2 * * *"
      ofelia.job-exec.backup.command: "/app/backup.sh"

Job Types

  • job-exec: Execute command in running container
  • job-run: Execute command in new container (deleted afterwards)
  • job-local: Execute command on host

Schedule Format

  • Cron format: 0 2 * * * (daily at 2 AM)
  • Go format: @every 5m (every 5 minutes)
  • Shortcuts: @hourly, @daily, @weekly, @monthly

Logrotate Configuration

The logrotate configuration is located in config/logrotate.conf:

/ofelia/logs/*.log {
    daily
    rotate 2
    missingok
    notifempty
    compress
    delaycompress
    copytruncate
}

Customizations:

  • rotate 2: Number of log files to keep
  • daily: Rotation interval (daily, weekly, monthly)
  • compress: Compress logs after rotation

Usage

Stack Commands

# Start stack
docker-compose up -d

# Show logs
docker-compose logs -f ofelia

# Stop stack
docker-compose down

# Restart stack
docker-compose restart

Check Job Status

# Show Ofelia logs
docker logs ofelia

# Job logs in logs directory
tail -f logs/*.log

Manual Log Rotation

docker exec ofelia-logrotate logrotate /etc/logrotate.conf

Directory Structure

.
├── config/
│   └── logrotate.conf          # Logrotate configuration
├── logs/                        # Job logs (created automatically)
├── .env                         # Environment variables
├── docker-compose.yaml          # Docker Compose configuration
├── Dockerfile                   # Logrotate container image
└── README.md                    # This file

Security

  • Docker socket mounted read-only (:ro)
  • No root privileges required
  • Logs stored in separate volume
  • No sensitive data in container images

Troubleshooting

Jobs Not Running

  1. Container running?
docker ps | grep ofelia
  1. Labels set correctly?
docker inspect <container-name> | grep ofelia
  1. Check Ofelia logs:
docker logs ofelia

Log Rotation Not Working

  1. Logrotate container running?
docker ps | grep logrotate
  1. Test manually:
docker exec ofelia-logrotate logrotate -d /etc/logrotate.conf

Examples

Daily Backup

services:
  database:
    image: postgres:15
    labels:
      ofelia.enabled: "true"
      ofelia.job-exec.db-backup.schedule: "0 3 * * *"
      ofelia.job-exec.db-backup.command: "pg_dump -U postgres mydb > /backup/dump.sql"

Log Cleanup Every 6 Hours

services:
  webapp:
    image: nginx:alpine
    labels:
      ofelia.enabled: "true"
      ofelia.job-exec.cleanup.schedule: "@every 6h"
      ofelia.job-exec.cleanup.command: "find /var/log -name '*.log' -mtime +7 -delete"

License & Support

This project is open source (GPL-3.0-or-later) and free. If it helped you, I'd appreciate your support:

Buy Me a Coffee GitHub Sponsors PayPal

Made with ❤️ by WSC - Web SEO Consulting

Credits

  • Ofelia by mcuadros
  • Alpine Linux for minimal container images

Contributing

Pull requests are welcome! For major changes, please open an issue first.

Links