Adding Cron Jobs to a Docker Compose application

I am Philip—an engineer working at Distr, which helps software and AI companies distribute their applications to self-managed environments. Our Open Source Software Distribution platform is available on GitHub (github.com/distr-sh/distr).

Docker Compose is a great orchestration tool for easily deploying multi-container applications. However, Docker Compose doesn’t natively support scheduled jobs. Although this sounds like a complicated problem at first, possible solutions are actually quite simple.

Cron Job Support in Docker Compose

Traditionally, servers used to run for a long time (usually even way too long). The Unix cron utility was invented in the early days of Unix to schedule tasks at specific times on the host system. Although nowadays multiple abstractions and reimplementations of cron exist, its original configuration file crontab (short for “cron table”) syntax is still widely adopted and used today.

A cronjob implementation is also available in several container orchestration platforms:

This is contrary to Docker, which never had a built-in cron implementation. On a single container level this actually makes sense as a container often represents a process that usually doesn’t spawn other processes, simplifying container management and monitoring.

Although Docker compose is a tool for defining multi-container applications, it doesn’t provide a built-in cron job implementation for container scheduling. A lot of applications depend on scheduled tasks, such as cleanup jobs, report generation, or data synchronization. While this could theoretically be done on an application level (e.g. Spring Boot’s @Scheduled annotation or a Golang Job Scheduling Package gocron), when starting multiple replicas of an application, synchronizing these tasks can become complex to ensure they are not executed multiple times simultaneously. So it is still a challenge to reliably schedule cron jobs in a multi-container environment with Docker Compose.

I’ve encountered this challenge repeatedly while working on Distr deployments across different customer environments. After testing various approaches in production, three patterns emerged as practical solutions, each with different trade-offs.

Approach 1: Lightweight Cron Scheduling Container

The simplest approach uses a minimal Alpine Linux container running BusyBox’s crond. This container initiates actions in other services via HTTP calls or executes local scripts.

Cron Scheduler Docker Implementation

There are two ways to implement this approach:

Option 1: Custom Dockerfile - Build a dedicated image with your crontab baked in. This is ideal when you want to share your jobs container across different deployment methods and don’t have full control over your deployment target.

Option 2: Volume Mount - Use a stock Alpine image and mount your crontab file as a volume. This allows for quick iteration and changes without rebuilding images. Tip: You can also use Docker Compose Configs to inline your crontab file.

FROM alpine:3.23

COPY crontab /etc/crontabs/root

CMD ["busybox", "crond", "-f", "-L", "/dev/stdout"]

services:
  backend:
    image: backend
    ports:
      - '5000:5000'
    networks:
      - app-network

  jobs:
    image: alpine:3.23
    command: crond -f -L /dev/stdout
    volumes:
      - ./crontab:/etc/crontabs/root:ro
    networks:
      - app-network
    depends_on:
      - backend

networks:
  app-network:
    driver: bridge

# ┌───────────── minute (0-59)
# │ ┌───────────── hour (0-23)
# │ │ ┌───────────── day of month (1-31)
# │ │ │ ┌───────────── month (1-12)
# │ │ │ │ ┌───────────── day of week (0-6) (Sunday to Saturday)
# │ │ │ │ │
# * * * * * command

# Call the internal API of another container in the Docker network
* * * * * wget -O- http://backend:5000/health

Both options use the same crontab file format. Option 1 requires building a custom image, while Option 2 mounts the crontab file directly into an Alpine container.

A full production example using Option 1 can be found in our example application hello-distr:

Jobs service with its Dockerfile and crontab configuration
Full docker-compose.yml file including the jobs service

Cron Scheduler in Docker Architecture

The jobs service only initiates scheduled jobs by calling an endpoint on the backend service that will trigger the job actions.

Separate Cron Scheduler Trigger in Docker Architecture Conclusion

This is the most lightweight approach, and I personally prefer it because all the logic is contained within the backend service. If your service runs multiple replicas, the job will only be executed once. Additionally, memory usage remains stable, as no additional containers are spawned.

Choose Option 1 (Custom Dockerfile) when you want your cron schedule to be version-controlled alongside your application code, or when deploying to production environments where immutable infrastructure is preferred. The crontab becomes part of your deployment artifact.

Choose Option 2 (Volume Mount) during development or when your cron schedules need to change frequently without rebuilding images. This is also useful when the same base image needs different cron configurations across environments—simply mount different crontab files.

Approach 2: Integrate Cron Jobs into your Backend Container

The second approach reuses your existing backend image but overrides the entrypoint to run cron instead of your application server. This eliminates the need for a separate image while giving you access to your application’s full codebase and dependencies.

Integrated Cron Jobs Docker Implementation

This implementation creates an “all-in-one” container that runs both the backend application and the cron scheduler.

Shared environment variables are also a great way to avoid declaring them multiple times across services.

x-shared-env: &shared-env
  ENVIRONMENT: production
  DATABASE_URL: postgresql://user:password@postgres:5432/myapp

services:
  backend:
    image: backend-aio
    entrypoint: ['/app/app']
    environment:
      <<: *shared-env

  jobs:
    image: backend-aio
    entrypoint: ['busybox', 'crond', '-f', '-L', '/dev/stdout']
    environment:
      <<: *shared-env

FROM golang:1.25-alpine AS builder

WORKDIR /build

COPY go.mod ./
RUN go mod download

COPY main.go job.go ./
RUN CGO_ENABLED=0 GOOS=linux go build -o app main.go
RUN CGO_ENABLED=0 GOOS=linux go build -o job job.go

FROM alpine:3.23

WORKDIR /app

COPY --from=builder /build/app /app/app
COPY --from=builder /build/job /usr/local/bin/job
COPY crontab /etc/crontabs/root

RUN chmod +x /app/app /usr/local/bin/job

# Set environment variables at the top of crontab
# These are available to all cron jobs
ENVIRONMENT=$ENVIRONMENT
DATABASE_URL=$DATABASE_URL

# ┌───────────── minute (0-59)
# │ ┌───────────── hour (0-23)
# │ │ ┌───────────── day of month (1-31)
# │ │ │ ┌───────────── month (1-12)
# │ │ │ │ ┌───────────── day of week (0-6) (Sunday to Saturday)
# │ │ │ │ │
# * * * * * command

# Method 1: Use environment variables set at the top
*/5 * * * * /usr/local/bin/job >> /proc/1/fd/1 2>&1

# Method 2: Set environment variable inline before the command
*/10 * * * * ENVIRONMENT=staging /usr/local/bin/job >> /proc/1/fd/1 2>&1

# Method 3: Load environment from a file and execute
# */15 * * * * . /app/.env && /usr/local/bin/job >> /proc/1/fd/1 2>&1

Integrated Cron Jobs in Docker Architecture

Integrated cron jobs in Docker backend container

Both services use the same all-in-one image (backend-aio) but with different entrypoints. The backend service runs the application server, while the jobs service runs crond for scheduled tasks. This approach avoids maintaining separate images while keeping processes isolated in different containers.

Integrated Cron Jobs into Backend Container Conclusion

If your application’s jobs are designed as separate executables, or you have a CLI with different subcommands, this is the best approach without requiring extensive refactoring inside your application.

One of the disadvantages is that if your application requires significant resources, this resource usage is doubled. This can be especially disadvantageous for JVM-based applications that require substantial memory to start up.

Approach 3: Dedicated Job Launcher

The third approach uses dedicated job launcher tools like Ofelia that can spawn new containers for each job execution. This approach requires that you give the job launcher access to the Docker socket in order to spawn new containers.

Dedicated Job Launcher Docker Implementation

This implementation uses Ofelia to manage cron jobs by spawning separate containers for each job execution, providing maximum isolation and flexibility.

Ofelia discovers jobs via Docker labels on containers. Two job types are demonstrated:

job-exec (e.g. cleanup): Executes commands inside the running backend container
job-run (e.g. reports): Spawns a new temporary container for each execution, requiring an explicit image and network configuration

services:
  ofelia:
    image: mcuadros/ofelia:latest
    depends_on:
      - backend
    command: daemon --docker
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:
      ofelia.enabled: 'true'

  backend:
    image: myapp/backend:latest
    labels:
      ofelia.enabled: 'true'
      # job-exec runs command inside the existing backend container
      ofelia.job-exec.cleanup.schedule: '0 2 * * *'
      ofelia.job-exec.cleanup.command: 'python /app/jobs/cleanup.py'
      # job-run spawns a new container for each execution
      ofelia.job-run.reports.schedule: '0 8 * * *'
      ofelia.job-run.reports.image: 'myapp/backend:latest'
      ofelia.job-run.reports.command: 'python /app/jobs/reports.py'
      ofelia.job-run.reports.network: 'app_network'
    networks:
      - app_network

networks:
  app_network:
    driver: bridge

Dedicated Job Launcher Docker Architecture

Dedicated Docker job launcher with Ofelia spawning containers

The Ofelia scheduler communicates with the Docker socket to spawn ephemeral job containers on demand. Each job runs in complete isolation with its own resources and lifecycle.

Dedicated Job Launcher for Docker Compose Conclusion

This approach is the most intrusive as it requires full access to the Docker socket, allowing the scheduler to not only spawn new containers but also see and modify any other running container on the host system.

However, it’s also the most flexible, especially if you have many jobs requiring different tech stacks and base images, or if jobs require strong isolation from each other.

Although the architecture comes closest to cloud-native scheduling, all spawned containers still run on the same host system and share existing resources. In contrast, Cloud Run jobs typically run on new VMs, while Kubernetes jobs ensure resources via resource requirements.

This approach is only feasible if you have an oversized host system or lightweight jobs, preventing your backend from being killed due to resource exhaustion.

Comparison Matrix

Feature	Lightweight Cron Job Trigger	Embedded Cron Job Scheduler	Distinct Cron Job Launcher
Resource Requirements	Minimal	Medium (2x app size)	High (dynamic)*
Job Isolation	None	Process-level	Full container isolation
Docker Socket Access	Not required	Not required	Required (security risk)
Image Requirements	Separate minimal image	Same as app	Any image per job

* While resource requirements are high, parallel job execution is easier to achieve with isolated containers.

Conclusion

While I would love to see Docker add a native jobs extension (similar to how Secrets were added), implementing periodic jobs in Docker Compose is more straightforward than it might initially appear.

Each approach has its place depending on your specific requirements:

Choose Approach 1 (Lightweight Scheduler) if you value simplicity and minimal resource overhead. This is ideal when your backend already exposes HTTP endpoints for job triggers, and you’re comfortable keeping job logic within your main application. It’s particularly well-suited for applications running multiple replicas where you need guaranteed single execution.

Choose Approach 2 (Integrated Solution) when your jobs need direct access to your application’s codebase, database connections, or internal APIs. This works best for applications with CLI tools or separate job executables. Be mindful of the doubled resource consumption—this approach might not be suitable for memory-intensive applications like Java services with large startup overhead.

Choose Approach 3 (Dedicated Launcher) when you need maximum flexibility and job isolation. If your jobs require different runtime environments, programming languages, or heavy isolation from your main application, the additional complexity and security considerations of Docker socket access become worthwhile trade-offs.

For most production deployments I’ve worked on, Approach 1 proves to be the sweet spot—it’s simple, resource-efficient, and aligns well with container best practices. However, the “right” choice always depends on your specific application architecture and operational requirements.

Important scheduling tip: Avoid scheduling multiple jobs at minute zero of the hour. Distribute your cron schedules across the hour (e.g., 5 * * * *, 15 * * * *, 30 * * * *) to prevent resource spikes. While this is generally recommended for any cron setup, it’s particularly critical for Docker Compose deployments with non-dynamic resource allocation where simultaneous job execution can cause memory exhaustion or container crashes.

The key takeaway: scheduled jobs in Docker Compose don’t require complex orchestration systems. With a few lines of configuration and an understanding of these patterns, you can implement robust job scheduling that scales with your application.