​
Overview

Diun (Docker Image Update Notifier) is a service that automatically monitors Docker container images and sends notifications when updates are detected. This document covers the deployment and configuration of Diun using Docker Compose.

​
Service Details

ComponentValue
Imagecrazymax/diun:4.29.0
Container Namediun
Volumediun-data
Watch ScheduleEvery hour (0 * * * *)
Notification ChannelDiscord
Time ZoneAmerica/Denver

​
Architecture

Diun operates as a standalone container with the following connections: 
┌─────────────┐
│   Discord   │
└─────────────┘
      ▲
      │ Notifications
      │
┌─────────────┐    ┌─────────────┐
│    Diun     │───▶│Docker Socket│
└─────────────┘    └─────────────┘
      │
      ▼
┌─────────────┐
│Persistent DB│
└─────────────┘
  • Docker Socket: Diun monitors running containers via the Docker socket
  • Persistent Data: State is maintained across restarts using a Docker volume
  • Notifications: Updates are sent to Discord via webhooks

​
Prerequisites

  • Docker Engine (24.0+)
  • Docker Compose v2
  • Discord server with webhook permissions (for notifications)
  • Running containers with the diun.enable=true label

​
Environment Variables

Create a .env file with the following variable: 
DIUN_DISCORD_WEBHOOK=https://discord.com/api/webhooks/your-webhook-url
Never commit the .env file to version control. Store your webhook URL securely in a password manager.

​
Deployment Configuration

​
Docker Compose File

services:
  diun:
    image: crazymax/diun:4.29.0
    container_name: diun
    command: serve
    volumes:
      - 'diun-data:/data'
      - '/var/run/docker.sock:/var/run/docker.sock'
    environment:
      - 'TZ=America/Denver'
      - 'LOG_LEVEL=info'
      - 'LOG_JSON=false'
      - 'DIUN_WATCH_WORKERS=20'
      - 'DIUN_WATCH_SCHEDULE=0 * * * *'
      - 'DIUN_WATCH_JITTER=30s'
      - 'DIUN_PROVIDERS_DOCKER=true'
      - 'DIUN_NOTIF_DISCORD_WEBHOOKURL=${DIUN_DISCORD_WEBHOOK}'
      - 'DIUN_NOTIF_DISCORD_MENTIONS=@here'
    restart: always

volumes:
  diun-data:

​
Deployment Instructions

  1. Create the deployment directory: 
    mkdir -p /opt/apps/diun
  2. Create the docker-compose.yml and .env files: 
    nano /opt/apps/diun/docker-compose.yml
nano /opt/apps/diun/.env
  3. Deploy the service: 
    cd /opt/apps/diun
docker compose up -d
  4. Verify the service is running: 
    docker compose ps
docker compose logs

​
Configuration Highlights

​
Watch Settings

Diun is configured with the following watch parameters:
  • Schedule: Every hour (0 * * * * cron expression)
  • Workers: 20 concurrent image checks
  • Jitter: 30-second random delay to avoid API rate limits

​
Notification Setup

Notifications are configured to:
  • Send to Discord via webhook
  • Mention @here for visibility
  • Include detailed image update information

​
Enabling Monitoring for Containers

To monitor a container for updates, add the following label to its configuration: 
labels:
  - 'diun.enable=true'

​
Advanced Container Monitoring

You can add additional labels to customize monitoring: 
labels:
  - 'diun.enable=true' # Enable monitoring
  - 'diun.watch_repo=true' # Watch all tags of this image
  - 'diun.max_tags=5' # Limit number of tags to watch
  - 'diun.include_tags=^1\\..*,^2\\..*$' # Only include specific tag patterns
  - 'diun.exclude_tags=.*-alpha.*' # Exclude specific tag patterns

​
Example: Monitoring Multiple Services

Here’s an example of enabling Diun monitoring for several containers: 
# Gitea configuration
services:
  server:
    image: gitea/gitea:1.23.7-rootless
    labels:
      - 'diun.enable=true'

  db:
    image: postgres:17.4
    labels:
      - 'diun.enable=true'

​
Maintenance

​
Backup Strategy

Back up Diun’s data regularly: 
# Option 1: Use Restic/Backrest for the volume
# Include /var/lib/docker/volumes/diun_diun-data in your backup paths

# Option 2: Manual backup
docker compose stop
tar -czf diun-backup-$(date +%Y%m%d).tar.gz -C /var/lib/docker/volumes/diun_diun-data .
docker compose start

​
Updates

To update Diun:
  1. Update the image tag in docker-compose.yml
  2. Apply the update: 
    docker compose pull
docker compose up -d
  3. Check logs for any issues: 
    docker compose logs

​
Troubleshooting

​
No Notifications

If you’re not receiving notifications:
  1. Verify Discord webhook URL is correct: 
    docker compose logs diun | grep -i "discord"
  2. Check if Diun is running on schedule: 
    docker compose logs diun | grep -i "cron"
  3. Test the webhook manually: 
    curl -X POST -H "Content-Type: application/json" \
  -d '{"content": "Testing webhook"}' \
  $DIUN_DISCORD_WEBHOOK

​
No Images Being Monitored

If no images are being monitored:
  1. Verify Docker socket access: 
    docker compose exec diun ls -la /var/run/docker.sock
  2. Check container discovery logs: 
    docker compose logs diun | grep -i "docker provider"
  3. Ensure containers have the proper diun.enable=true label

​
Image Update Triggers

Diun identifies image updates by:
  1. Tag Changes: When an image with a specific tag is updated
  2. New Tags: When configured to watch repositories for new tags
  3. Manifest Changes: When the image digest changes, even if the tag remains the same

​
Manual Update Check

To trigger an immediate update check: 
docker compose exec diun diun run

​
Security Considerations

  • Docker Socket: Diun has access to the Docker socket, granting it significant privileges
  • Discord Webhook: Keep your webhook URL confidential to prevent unauthorized notifications
  • Image Policies: Consider using diun.include_tags to only monitor production tags

​
Additional Resources

​
Integration Examples

​
Complete Stack Example

Add Diun labels to your existing infrastructure: 
# Example Traefik integration
services:
  traefik:
    image: traefik:v3.3.5
    labels:
      - 'diun.enable=true'
      - 'diun.include_tags=^v3\\..*$'

  postgres:
    image: postgres:17
    labels:
      - 'diun.enable=true'
      - 'diun.watch_repo=false' # Only watch the specific tag