> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymondo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

| Component            | Value                      |
| -------------------- | -------------------------- |
| Image                | crazymax/diun:4.29.0       |
| Container Name       | diun                       |
| Volume               | diun-data                  |
| Watch Schedule       | Every hour (0 \* \* \* \*) |
| Notification Channel | Discord                    |
| Time Zone            | America/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
```

<Warning>
  Never commit the `.env` file to version control. Store your webhook URL
  securely in a password manager.
</Warning>

## Deployment Configuration

### Docker Compose File

```yaml theme={null}
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:

   ```bash theme={null}
   mkdir -p /opt/apps/diun
   ```

2. Create the `docker-compose.yml` and `.env` files:

   ```bash theme={null}
   nano /opt/apps/diun/docker-compose.yml
   nano /opt/apps/diun/.env
   ```

3. Deploy the service:

   ```bash theme={null}
   cd /opt/apps/diun
   docker compose up -d
   ```

4. Verify the service is running:
   ```bash theme={null}
   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:

```yaml theme={null}
labels:
  - 'diun.enable=true'
```

### Advanced Container Monitoring

You can add additional labels to customize monitoring:

```yaml theme={null}
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:

```yaml theme={null}
# 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:

```bash theme={null}
# 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:

   ```bash theme={null}
   docker compose pull
   docker compose up -d
   ```

3. Check logs for any issues:
   ```bash theme={null}
   docker compose logs
   ```

## Troubleshooting

### No Notifications

If you're not receiving notifications:

1. Verify Discord webhook URL is correct:

   ```bash theme={null}
   docker compose logs diun | grep -i "discord"
   ```

2. Check if Diun is running on schedule:

   ```bash theme={null}
   docker compose logs diun | grep -i "cron"
   ```

3. Test the webhook manually:
   ```bash theme={null}
   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:

   ```bash theme={null}
   docker compose exec diun ls -la /var/run/docker.sock
   ```

2. Check container discovery logs:

   ```bash theme={null}
   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:

```bash theme={null}
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](https://crazymax.dev/diun/)
* [Diun GitHub Repository](https://github.com/crazy-max/diun)
* [Cron Expression Format](https://en.wikipedia.org/wiki/Cron#CRON_expression)

## Integration Examples

### Complete Stack Example

Add Diun labels to your existing infrastructure:

```yaml theme={null}
# 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
```