Docker Deployment Guide

This guide explains how to deploy Mangrullo using Docker containers.

Quick Start

Option 1: One-shot Mode (Recommended)

Run a single update check:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mangrullo --once

Option 2: Daemon Mode

Run Mangrullo as a background daemon that periodically checks for updates:

docker run -d \
  --name mangrullo \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mangrullo --interval=300

Option 3: Dry Run Mode

See what would be updated without making changes:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mangrullo --dry-run

Option 4: Check Specific Containers

Check only specific containers:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mangrullo --once flatnotes atuin

Docker Compose

Use the provided docker-compose.yml for easier deployment:

Start Mangrullo

docker-compose up -d

Stop Mangrullo

docker-compose down

View Logs

docker-compose logs -f

Configuration

Environment Variables

Variable	Description	Default
`MANGRULLO_DOCKER_SOCKET`	Docker socket path	`/var/run/docker.sock`
`MANGRULLO_LOG_LEVEL`	Log level (debug, info, warn, error)	`info`
`MANGRULLO_INTERVAL`	Check interval in seconds	`3600`
`MANGRULLO_ALLOW_MAJOR`	Allow major version upgrades	`false`

Example with Custom Configuration

docker run -d \
  --name mangrullo \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e MANGRULLO_LOG_LEVEL=debug \
  -e MANGRULLO_INTERVAL=1800 \
  -e MANGRULLO_ALLOW_MAJOR=true \
  mangrullo daemon

Building the Image

Build the Docker image from source:

docker build -t mangrullo .

Build for a specific platform:

docker build -t mangrullo --platform linux/amd64 .
docker build -t mangrullo --platform linux/arm64 .

Security Considerations

Docker Socket Access

Mangrullo needs access to the Docker socket to manage containers. This is done with:

-v /var/run/docker.sock:/var/run/docker.sock

Note: Mangrullo needs write access to the Docker socket to recreate containers. The :ro flag cannot be used as it would prevent container operations. If you want to restrict access further, consider:

Using a Docker socket proxy that filters allowed operations
Running Mangrullo in a separate Docker network with limited access
Using Docker's socket activation with proper permissions

Non-root User

The Docker image runs Mangrullo as a non-root user (UID 1000) for improved security.

Monitoring

Logs

View container logs:

docker logs mangrullo
docker logs -f mangrullo  # Follow logs

Health Checks

Basic container health can be checked with:

docker inspect mangrullo --format='{{.State.Status}}'

Production Deployment

Using Docker Swarm

version: '3.8'
services:
  mangrullo:
    image: mangrullo:latest
    deploy:
      mode: replicated
      replicas: 1
      restart_policy:
        condition: on-failure
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - MANGRULLO_LOG_LEVEL=info
      - MANGRULLO_INTERVAL=3600
    networks:
      - mangrullo-network

networks:
  mangrullo-network:
    driver: overlay

Using Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mangrullo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mangrullo
  template:
    metadata:
      labels:
        app: mangrullo
    spec:
      containers:
      - name: mangrullo
        image: mangrullo:latest
        env:
        - name: MANGRULLO_LOG_LEVEL
          value: "info"
        - name: MANGRULLO_INTERVAL
          value: "3600"
        volumeMounts:
        - name: docker-socket
          mountPath: /var/run/docker.sock
          readOnly: true
      volumes:
      - name: docker-socket
        hostPath:
          path: /var/run/docker.sock

Troubleshooting

Permission Denied

If you get permission denied errors:

# Add user to docker group on host
sudo usermod -aG docker $USER

# Or run with elevated privileges
docker run --privileged ...

Connection Issues

If Mangrullo can't connect to Docker:

Verify Docker is running: docker ps
Check socket permissions: ls -la /var/run/docker.sock
Ensure the socket is mounted correctly

Advanced Usage

Custom Dockerfile

For custom builds, create a .dockerignore file:

.git
.github
.spec
lib/
bin/
*.log
.DS_Store

Multi-architecture Builds

Build for multiple architectures:

docker buildx build --platform linux/amd64,linux/arm64 -t mangrullo:latest .

Private Registry

Push to a private registry:

docker tag mangrullo:latest my-registry.com/mangrullo:latest
docker push my-registry.com/mangrullo:latest