Diun

​

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

​

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

​

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

• Official Diun Documentation
• Diun GitHub Repository
• Cron Expression Format

​

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