# Domain Manager

Automatically manage DNS subdomains based on Docker container events.

## Overview

Domain Manager listens to Docker container events (create/destroy) and automatically adds or removes CNAME records for
configured domains. Supports multiple DNS providers including OVH and Cloudflare.

## Features

- **Automatic DNS Management**: Creates/deletes subdomain records when containers start/stop
- **Multiple Provider Support**: OVH and Cloudflare (easily extensible)
- **Docker Integration**: Listens to container events via Docker socket
- **Secret Management**: Supports Docker secrets and environment variables
- **Label-based Configuration**: Enable per-container via simple labels

## Quick Start

### Prerequisites

- Docker
- Python 3.13+ (for local development)
- DNS provider account (OVH or Cloudflare)

### Environment Setup

Create a `.env` file:

```env
# Provider selection (OVH or CLOUDFLARE)
DNM_PROVIDER=CLOUDFLARE

# Domain configuration
DNM_DOMAIN_NAME=example.com
DNM_TARGET=proxy.example.com

# Cloudflare (if using CLOUDFLARE)
DNM_CLOUDFLARE_API_TOKEN=your_api_token

# OVH (if using OVH)
DNM_OVH_APPLICATION_KEY=your_key
DNM_OVH_APPLICATION_SECRET=your_secret
DNM_OVH_CONSUMER_KEY=your_consumer_key

# Docker (optional, defaults to unix socket)
DNM_DOCKER_BASE_URL=unix://var/run/docker.sock

Run with Docker Compose

services:
  domain-manager:
    build: .
    environment:
      DNM_PROVIDER: ${DNM_PROVIDER}
      DNM_DOMAIN_NAME: ${DNM_DOMAIN_NAME}
      DNM_TARGET: ${DNM_TARGET}
      DNM_CLOUDFLARE_API_TOKEN_FILE: /run/secrets/cf_token
    secrets:
      - cf_token
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

secrets:
  cf_token:
    environment: DNM_CLOUDFLARE_API_TOKEN

Run Locally

# Install
pip install -r requirements.txt

# Start
python src/main.py

Container Labels

Enable DNS management for any container by adding labels:

labels:
  dnm.enabled: true
  dnm.fqdn: app.example.com

The service will:

• Create app.example.com CNAME → proxy.example.com on container creation
• Delete the record on container destruction

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Docker Events  │────▶│  Event Handler   │────▶│ SubdomainManager│
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                          │
                                                          ▼
                                              ┌─────────────────────┐
                                              │   DNS Provider      │
                                              │ (OVH / Cloudflare)  │
                                              └─────────────────────┘

Adding a New Provider

1. Create new provider class in src/providers/
2. Extend SubdomainProvider and implement required methods
3. Provider auto-registers via __init_subclass__

from src.providers.abstract import SubdomainProvider


class NewProvider(SubdomainProvider):
    keys = ('api_key',)  # Required env vars

    def authenticate(self):

    # Implement authentication

    def add_subdomain(self, subdomain: str):

    # Create DNS record

    def remove_subdomain(self, subdomain: str):

    # Delete DNS record

    def check_subdomain(self, subdomain: str) -> bool:
# Check if record exists

Configuration Reference

Variable	Description	Required
DNM_PROVIDER	Provider name (OVH/CLOUDFLARE)	Yes
DNM_DOMAIN_NAME	Base domain (e.g., example.com)	Yes
DNM_TARGET	CNAME target (e.g., proxy.example.com)	Yes
DNM_DOCKER_BASE_URL	Docker socket URL	No
DNM_OVH_APPLICATION_KEY	OVH API key	For OVH
DNM_OVH_APPLICATION_SECRET	OVH secret	For OVH
DNM_OVH_CONSUMER_KEY	OVH consumer key	For OVH
DNM_CLOUDFLARE_API_TOKEN	Cloudflare token	For Cloudflare

All variables support _FILE suffix for Docker secrets (e.g., DNM_CLOUDFLARE_API_TOKEN_FILE).

Development

# Clone
git clone https://github.com/arasemco/DomainManager.git

# Install dev dependencies
pip install -r requirements.txt

# Run tests
pytest

# Set debug logging
export LOG_LEVEL=DEBUG

License

Open source

Contact

Author: Aram SEMO
Email: aram.semo@asemo.pro