Начало работы

Добро пожаловать в Caddy! Этот учебник рассмотрит основы использования Caddy и поможет вам ознакомиться с ним на высоком уровне.

Цели:

• 🔲 Запустить демона
• 🔲 Попробовать API
• 🔲 Предоставить Caddy конфигурацию
• 🔲 Протестировать конфигурацию
• 🔲 Создать Caddyfile
• 🔲 Использовать адаптер конфигурации
• 🔲 Начать с начальной конфигурации
• 🔲 Сравнить JSON и Caddyfile
• 🔲 Сравнить API и файлы конфигурации
• 🔲 Запустить в фоновом режиме
• 🔲 Перезагрузка конфигурации без простоев

Предварительные условия:

• Базовые навыки работы с терминалом/командной строкой
• Базовые навыки работы с текстовым редактором
• caddy и curl в вашей переменной окружения PATH

Если вы установили Caddy из менеджера пакетов, Caddy может уже работать в качестве службы. В таком случае, пожалуйста, остановите службу перед выполнением этого учебника.

Давайте начнем с запуска:

caddy

Упс; без подкоманды, команда caddy только отображает справку. Вы можете использовать её в любое время, когда забудете, что нужно сделать.

Чтобы запустить Caddy в качестве демона, используйте подкоманду run:

caddy run

Это блокирует выполнение навсегда, но что он делает? На данный момент... ничего. По умолчанию конфигурация Caddy ("config") пустая. Мы можем проверить это, используя административный API в другом терминале:

curl localhost:2019/config/

Мы можем сделать Caddy полезным, предоставив ему конфигурацию. Это можно сделать многими способами, но мы начнём с отправки POST-запроса на конечную точку /load с помощью curl в следующем разделе.

Ваша первая конфигурация

Чтобы подготовиться к нашему запросу, нам нужна конфигурация. В основе своей конфигурация Caddy — это просто документ JSON.

Сохраните его в файле JSON (например, caddy.json):

{
	"apps": {
		"http": {
			"servers": {
				"example": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				}
			}
		}
	}
}

Затем загрузите его:

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

Мы можем убедиться, что Caddy применил нашу новую конфигурацию, выполнив другой GET-запрос:

curl localhost:2019/config/

Проверьте, что это работает, перейдя по ссылке localhost:2015 в вашем браузере или используйте curl:

curl localhost:2015
Hello, world!

Если вы видите Hello, world!, значит всё работает! Всегда полезно убедиться, что ваша конфигурация работает так, как ожидается, особенно перед развертыванием в рабочей среде.

Ваш первый Caddyfile

Это довольно много работы только для Hello World.

Другой способ настроить Caddy — использовать Caddyfile. Та же конфигурация, которую мы написали в JSON выше, может быть выражена просто как:

:2015respond "Hello, world!"

Сохраните его в файл с именем Caddyfile (без расширения) в текущем каталоге.

Остановите Caddy, если он уже запущен (Ctrl+C), затем выполните:

caddy adapt

Или если вы сохранили Caddyfile в другом месте или назвали его иначе, чем Caddyfile:

caddy adapt --config /path/to/Caddyfile

Вы увидите вывод JSON! Что здесь произошло?

Мы только что использовали адаптер конфигурации для преобразования нашего Caddyfile в родную структуру JSON Caddy.

Хотя мы могли бы взять этот вывод и сделать ещё один API-запрос, мы можем пропустить все эти шаги, потому что команда caddy может сделать это за нас. Если в текущем каталоге есть файл с именем Caddyfile и нет другой указанной конфигурации, Caddy загрузит Caddyfile, адаптирует его для нас и сразу же запустит.

Теперь, когда в текущей папке есть Caddyfile, давайте снова выполним caddy run:

caddy run

Или если ваш Caddyfile находится в другом месте:

caddy run --config /path/to/Caddyfile

(Если он называется чем-то другим, что не начинается с «Caddyfile», вам нужно указать --adapter caddyfile.)

Теперь вы можете попробовать загрузить свой сайт снова, и вы увидите, что он работает!

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

• Файл с именем Caddyfile в текущем каталоге
• Флаг --config (необязательно с флагом --adapter)
• Флаг --resume (если ранее была загружена конфигурация)

JSON против Caddyfile

Теперь вы знаете, что Caddyfile просто преобразуется в JSON для вас.

Caddyfile кажется проще, чем JSON, но всегда ли стоит его использовать? У каждого подхода есть плюсы и минусы. Ответ зависит от ваших требований и сценария использования.

Вам нужно будет решить, что лучше подходит для вашего сценария использования.

Важно отметить, что и JSON, и Caddyfile (и любой другой поддерживаемый адаптер конфигурации) могут использоваться с API Caddy. Однако вы получите полный функционал Caddy и API-возможности, если используете JSON. Если вы используете адаптер конфигурации, единственный способ загрузить или изменить конфигурацию с помощью API — это конечная точка /load.

API против файлов конфигурации

Вам также нужно будет решить, основан ли ваш рабочий процесс на API или командной строке. (Вы можете использовать API и файлы конфигурации на одном сервере, но мы этого не рекомендуем: лучше иметь один источник правды.)

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

Но большинство людей будут использовать комбинации JSON+API или Caddyfile+CLI.

Как видите, Caddy хорошо подходит для самых разных сценариев использования и развертываний!

Запуск, остановка, выполнение

Поскольку Caddy — это сервер, он работает бесконечно. Это означает, что ваш терминал не разблокируется после выполнения caddy run до тех пор, пока процесс не будет завершён (обычно с помощью Ctrl+C).

Хотя caddy run наиболее распространён и обычно рекомендуется (особенно при создании системной службы!), вы можете альтернативно использовать caddy start для запуска Caddy и выполнения его в фоновом режиме:

caddy start

Это позволит вам снова использовать ваш терминал, что удобно в некоторых интерактивных бесклавишных средах.

Затем вам нужно будет остановить процесс самостоятельно, так как Ctrl+C не остановит его за вас:

caddy stop

Или используйте конечную точку /stop API.

Перезагрузка конфигурации

Ваш сервер может выполнять перезагрузки/изменения конфигурации без простоев.

Все API-конечные точки, которые загружают или изменяют конфигурацию, выполняются плавно без простоев.

Однако при использовании командной строки может быть соблазнительно использовать Ctrl+C для остановки сервера, а затем перезапустить его, чтобы захватить новую конфигурацию. Не делайте этого: остановка и перезапуск сервера ортогональны изменениям конфигурации и приведут к простоям.

Вместо этого используйте команду caddy reload для плавного изменения конфигурации:

caddy reload

На самом деле это просто использует API под капотом. Это загрузит и, при необходимости, адаптирует ваш файл конфигурации к JSON, а затем плавно замещает активную конфигурацию без простоев.

Если при загрузке новой конфигурации возникнут ошибки, Caddy вернётся к последней рабочей конфигурации.