Caddy в Docker: быстрое развёртывание с HTTPS и собственным Caddyfile

Быстрые ссылки

• Выбор тега образа
• Запуск простого сервера
• Настройка HTTPS
• Добавление собственного Caddyfile
• Создание Docker-образов для сайтов
• Резюме

Caddy — современный веб‑сервер, спроектированный для производительности и безопасности памяти. Он написан на Go, не требует внешних зависимостей, умеет рендерить статические сайты с Markdown и автоматически настраивает HTTPS.

Caddy ориентирован на простоту управления: полезные функции включены по умолчанию. Его часто легче настраивать и поддерживать по сравнению с Apache или NGINX. В этой статье показано, как быстро поднять собственный сервер, используя официальный Docker‑образ Caddy.

Выбор тега образа

Официальный образ Caddy доступен в нескольких вариантах. На момент написания все варианты делят одну основную версию Caddy — v2.4. Можно указывать:

2.4.x

(заменив

x

на конкретный патч),

2.4

или

2

чтобы зафиксировать патч, минор или мажор.

Caddy работает на Linux и Windows‑хостах Docker. Доступны образы для Alpine Linux, Windows Server Core 1809 и Windows Server Core 2016 LTSC. Простое указание тега, например

caddy:2

выберет подходящий образ для вашей платформы. Для явного выбора можно использовать вариации вроде

2.4-alpine

или

2.4.6-windowsservercore-1809

Важно: для продакшен‑окружения рекомендую фиксировать версию на минор или патч, а не на latest.

Запуск простого сервера

Образ Caddy готов к запуску «из коробки». По умолчанию он обслуживает контент из каталога /usr/share/caddy. Вы можете положить файлы в контейнер, смонтировав каталог хоста в этот путь.

Кроме того, у Caddy есть отдельные каталоги для конфигурации и данных. Их стоит смонтировать как Docker‑тома. Каталог

/config

опционален, но рекомендован: там хранятся файлы конфигурации (они преобразуются в API‑вызовы). Каталог

/data

критичен: он содержит TLS‑сертификаты, приватные ключи и окончательную конфигурацию, сформированную API. Если вы не сохраните /data, при пересоздании контейнера Caddy заново создаст сертификаты и состояние.

Пример простого запуска:

docker run -d -p 80:80 \
  -v ./my-website:/usr/share/caddy/ \
  -v caddy-config:/config \
  -v caddy_data:/data \
  caddy:2

По умолчанию Caddy слушает порт 80 для HTTP. В примере выше порт 80 контейнера проброшен на порт 80 хоста. После запуска посетите http://localhost. Если в смонтированном каталоге есть index.html, вы увидите его; иначе — страницу приветствия Caddy.

Важно: если вы используете SELinux или специальные политики безопасности, проверьте права и контекст тома. На Windows пути и права отличаются — используйте Windows‑совместимые тома и образы.

Настройка HTTPS

Одно из главных преимуществ Caddy — автоматический TLS. Чтобы включить HTTPS, пробросьте порт 443 и укажите домен для которого нужно получить сертификат.

Пример запуска с HTTPS:

docker run -d -p 80:80 -p 443:443 \
  -v ./my-website:/usr/share/caddy/ \
  -v caddy-config:/config \
  -v caddy_data:/data \
  caddy:2 caddy file-server --domain example.com

Команда после имени образа передаётся в entrypoint контейнера. Здесь caddy file-server ... запускается как foreground‑процесс. Флаг --domain задаёт домен, для которого Caddy попытается автоматически получить сертификат (Let’s Encrypt или другой ACME‑провайдер по умолчанию).

Перед запуском убедитесь, что у вас есть A‑запись в DNS, указывающая на IP вашего Docker‑хоста (или запись типа A/AAAA для соответствующего адреса). Без корректной DNS‑записи автоматическое получение сертификата не сработает.

Примечание: в тестовых средах, где DNS не настроен, можно использовать самоподписанные сертификаты, ACME‑staging или указать управляющий режим --agree/--email. Для локальной разработки проще запускать Caddy без автоматического получения сертификата и использовать прокси/сетевые инструменты.

Важно: /data нужно монтировать как персистентный том. Там хранятся сертификаты — потеря тома приведёт к повторной генерации сертификатов и возможным ограничениям со стороны провайдера ACME.

Добавление собственного Caddyfile

Caddy использует файл конфигурации под названием Caddyfile для маршрутизации и настроек сервера. В образе Docker Caddy ищет файл в /etc/caddy/Caddyfile. Смонтируйте свой файл на этот путь, чтобы переопределить поведение по умолчанию.

Пример запуска с собственным Caddyfile:

docker run -d -p 80:80 -p 443:443 \
  -v ./Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  caddy:2

Простой пример Caddyfile для example.com с включённым HTTPS:

{
    email example@example.com
}

example.com {
    respond "It works!"
}

Коротко о блоках:

• Глобический блок { ... } задаёт параметры, применимые ко всем сайтам, например email для ACME.
• Блок для домена example.com { ... } описывает правила обработки запросов для этого сайта.

Caddyfile легко читать и править вручную. Если вам нужна более детальная конфигурация — изучите документацию Caddy по маршрутам, обработчикам и matchers.

Совет по отладке: можно запускать контейнер в интерактивном режиме или включать более подробные логи в Caddyfile, чтобы быстро найти проблемы в конфигурации.

Создание Docker‑образов для ваших сайтов

Запуск контейнера напрямую из базового образа удобен для тестов. В продакшене лучше собирать специализированные образы, в которые уже включён сайт и конфигурация. Это упрощает развёртывание и делает образы переносимыми.

Пример Dockerfile, который включает Caddyfile и копирует статические файлы в образ:

FROM caddy:2.4

WORKDIR /my-site

COPY Caddyfile /etc/caddy/Caddyfile

COPY *.html ./

COPY *.css css/

COPY *.js js/

Сборка и запуск образа:

docker build -t my-site:latest .

docker run -p 80:80 -p 443:443 -v caddy_data:/data my-site:latest

Этот подход уменьшает зависимость от монтируемых директорий и упрощает CI/CD: образ содержит весь статический контент и конфигурацию.

Добавление дополнительных модулей

Если нужно расширить функциональность Caddy, используйте xcaddy и builder‑образ. Лучший способ — многопроходная сборка (multi‑stage build). Пример, который добавляет модуль replace-response для изменения частей ответа:

FROM caddy:2.4-builder AS caddy-build

RUN xcaddy build --with github.com/caddyserver/replace-response

FROM caddy:2.4

COPY --from=caddy-build /usr/bin/caddy /usr/bin/caddy

WORKDIR /my-site

COPY Caddyfile /etc/caddy/Caddyfile

COPY *.html ./

COPY *.css css/

COPY *.js js/

Первый этап собирает бинарь Caddy с нужными модулями. Второй этап использует стандартный базовый образ и заменяет бинарь на кастомный. Результат — образ с дополнительными модулями и привычной структурой.

Совет: добавляйте только те модули, которые действительно нужны, чтобы не увеличивать поверхность атаки и размер образа.

Docker Compose: пример для удобного управления

Для удобства в локальной разработке и в продакшене удобно использовать docker‑compose. Простой пример docker-compose.yml:

version: '3.7'

services:
  caddy:
    image: caddy:2
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./site:/usr/share/caddy
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

Такой файл делает запуск и обновление контейнера предсказуемым и совместимым с CI/CD.

Отладка и распространённые проблемы

• Проблема: Caddy не получает сертификат. Проверьте DNS A/AAAA‑запись домена. Убедитесь, что порты 80/443 доступны и трафик не блокируется firewall’ом.
• Проблема: сертификаты теряются после перезапуска. Убедитесь, что /data смонтирован в персистентный том.
• Проблема: SELinux не даёт доступ к монтированным файлам. Используйте :Z или :z флаги или настройте контексты SELinux.

Короткие тесты при деплое:

• curl -I http://example.com
• curl -I https://example.com
• docker logs

Безопасность и эксплуатация

Несколько практических рекомендаций:

• Персистентность: всегда монтируйте /data в том. Это критично для TLS.
• Правила доступа: держите приватные ключи в безопасных томах с ограниченным доступом.
• Обновления: своевременно обновляйте образ Caddy. В CI собирайте и тестируйте образы на тестовом окружении.
• Мониторинг: собирайте логи и метрики (либо через встроенные обработчики, либо через внешние решения).

К жестким требованиям к безопасности относятся ограничение привилегий контейнера и контроль исходящего трафика для ACME‑запросов.

Когда Caddy может не подойти (контрпримеры)

• Наличие сложных legacy‑конфигураций Apache, которые тяжело перенести на Caddy. Иногда проще оставить NGINX/Apache.
• Требования к специфическим модульным расширениям, которые не поддержуются в экосистеме Caddy.
• Организации с жёсткой политикой использования определённых HTTP‑стеков и процессов управления сертификатами.

Если вы попадаете в одну из этих ситуаций, рассмотрите проксирование трафика через Caddy к существующему стеку или гибридный подход.

Краткая методология развёртывания (мини‑метод)

1. Выберите базовый образ и зафиксируйте версию.
2. Подготовьте Caddyfile и тестовый набор страниц.
3. Соберите образ локально и прогоните тесты (curl, TLS‑проверки).
4. Настройте персистентные тома для /data и опционально /config.
5. Разверните в staging и проверьте ACME‑workflow.
6. Перенесите в продакшен и включите мониторинг.

Роли и чек‑листы

• Разработчик:
  • Подготовить статический контент и Caddyfile.
  • Собрать образ и написать тесты (smoke tests).
• DevOps/Инженер по платформе:
  • Настроить Docker/Compose/Kubernetes манифесты.
  • Организовать персистентные тома для /data и бэкапы.
  • Настроить политики безопасности (SELinux, права томов).
• SRE/Оператор:
  • Мониторить логи и метрики.
  • Реагировать на проблемы с ACME и истечением сертификатов.

Критерии приёмки

• Сервер отвечает на HTTP‑и HTTPS‑запросы для целевого домена.
• TLS‑сертификат выдан и хранится в /data (проверить наличие файлов).
• Подготовлен образ с включённым Caddyfile и статическим контентом.
• CI собирает образ и выполняет тесты успешного старта.

Пример плейбука для инцидента: потеря сертификатов

1. Проверить доступность тома /data и его содержимое.
2. Если том пуст — восстановить из бэкапа.
3. Если бэкапа нет — проверить логи ACME для причин отказа.
4. При необходимости — переключиться на staging ACME провайдер или временно включить самоподписанный сертификат.
5. После восстановления перезапустить контейнер и проверить HTTPS‑доступ.

Совместимость и миграция

• Linux контейнеры: подходят образы alpine и обычные linux/amd64.
• Windows: используйте образы с пометкой windowsservercore соответствующей версии.
• При миграции с NGINX/Apache: начните с проксирования трафика через Caddy, постепенно переводя маршруты и тестируя поведение.

Дополнительные ресурсы и советы по локализации

• Документация Caddy по Caddyfile и API — основной источник для продвинутых сценариев.
• Для CI используйте многослойную сборку и кэширование слоёв, чтобы ускорять сборку образов.
• Для приватных сетей и корпоративных прокси убедитесь, что контейнер имеет доступ к ACME‑точкам.

Часто задаваемые вопросы

Можно ли использовать Caddy без доступа в интернет?

Да — в локальной разработке вы можете запускать Caddy без автоматического ACME. Для HTTPS используйте самоподписанные сертификаты или внутренний CA.

Как обновить Caddy в образе с кастомным бинарём?

Соберите новый кастомный бинарь через xcaddy и замените /usr/bin/caddy в вашем финальном образе, затем пересоберите образ сайта.

Нужно ли монтировать /config?

Не обязательно, но полезно. /config хранит исходную конфигурацию. /data — обязательный для сохранения состояния и сертификатов.

Резюме

Caddy — удобный инструмент для быстрого развёртывания статических сайтов и проксирования трафика, особенно когда важна автоматизация TLS. Docker‑образ Caddy легко расширять: от простого смонтированного каталога до полноценных образов с кастомными модулями через xcaddy.

Использование Docker упрощает тестирование и CI/CD. Для стабильной работы важно: монтировать /data в персистентный том, фиксировать версии образов и контролировать доступы к ключам. В большинстве случаев Caddy сокращает время настройки HTTPS и облегчает управление конфигурацией в контейнеризованных средах.

Важное: перед развёртыванием в продакшен проверьте DNS, брандмауэр и права доступа томов, а также протестируйте обновление сертификатов в staging окружении.

Если нужно, могу подготовить готовый docker-compose.yml с расширенной конфигурацией для Kubernetes, примеры Caddyfile для проксирования нескольких сервисов или шаблон CI/CD для сборки и публикации образов.