Generator Caddyfile

Generator pliku Caddyfile

Caddy to serwer WWW i reverse proxy znany z prostoty. Automatycznie uzyskuje i odnawia certyfikaty TLS, więc konfiguracja HTTPS sprowadza się do podania domeny.

Najważniejsze dyrektywy

Przykład

Blok example.com { reverse_proxy localhost:3000 } wystarczy, by udostępnić aplikację pod domeną przez HTTPS. Caddy sam zadba o certyfikat.

Automatyczny HTTPS

Caddy domyślnie używa Let's Encrypt. Warunkiem jest publicznie dostępna domena wskazująca na serwer oraz otwarte porty 80 i 443 do walidacji.

Jak działa generator Caddyfile

Generator Caddyfile tworzy tekst pliku konfiguracyjnego, a nie instaluje niczego na serwerze. Caddy nie używa plików XML ani JSON — jego konfiguracją jest właśnie Caddyfile, czyli bloki adresowe i dyrektywy w ich wnętrzu. Narzędzie zbiera od Ciebie kilka informacji (adres domeny, adres aplikacji, opcje takie jak kompresja, logi czy przekierowanie) i składa z nich gotowy plik do wklejenia. Nie łączy się z Twoją maszyną, nie sprawdza DNS i nie uruchamia Caddy — wynikiem jest czysty tekst.

Pierwszy wiersz bloku to adres, na przykład example.com. Caddy dopasowuje go do nagłówka Host żądania oraz do nazwy hosta w TLS, a wszystko wewnątrz bloku dotyczy wyłącznie tego adresu. reverse_proxy wskazuje, dokąd przekazać ruch (host i port aplikacji), encode włącza kompresję odpowiedzi, log zapisuje żądania do pliku, a redir wysyła przekierowanie. Ważne: Caddy wykonuje dyrektywy w ustalonej, wewnętrznej kolejności, a nie w takiej, w jakiej zapiszesz je w pliku. Dlatego w prostym Caddyfile kolejność wierszy rzadko zmienia efekt — o zachowaniu decyduje zestaw dyrektyw.

Warstwa TLS działa poza blokiem. Dla każdego adresu z nazwą hosta Caddy domyślnie włącza automatyczne zarządzanie certyfikatami i korzysta z Let's Encrypt. Walidacja wymaga publicznie dostępnej domeny wskazującej na serwer oraz otwartych portów 80 i 443. Po uzyskaniu certyfikatu Caddy sam go odnawia, więc w wygenerowanym pliku nie ma ani ścieżek do kluczy, ani dat ważności. To dlatego poprawny Caddyfile jest tak krótki — cała obsługa TLS siedzi w serwerze, nie w konfiguracji.

Przykład: od pustej konfiguracji do działającego HTTPS

1. Przyjmij założenia: aplikacja nasłuchuje na localhost:3000, a domena to example.com.
2. Wpisz w generatorze domenę example.com oraz adres aplikacji localhost:3000. Powstaje blok example.com z dyrektywą reverse_proxy — jeden blok i jedna dyrektywa.
3. Włącz kompresję odpowiedzi. Dochodzi encode z gzip i zstd, czyli razem dwie dyrektywy w bloku.
4. Włącz logi dostępu do pliku. Dochodzi log, razem trzy dyrektywy.
5. Dodaj przekierowanie z wariantu www. Powstaje drugi blok dla www.example.com z dyrektywą redir. Plik ma więc dwa bloki i cztery dyrektywy łącznie, obsługujące dwie nazwy hosta.
6. Zapisz plik i uruchom caddy validate --config Caddyfile. Brak komunikatu o błędzie oznacza poprawną składnię. Po starcie Caddy otwiera porty 80 i 443 i pobiera certyfikat dla obu nazw — bez ręcznego wpisywania kluczy w pliku.

Tabela referencyjna: co decyduje o zachowaniu Caddy

Praktyczne wskazówki

• Najpierw walidacja, potem restart — caddy validate --config Caddyfile wychwyci literówkę w dyrektywie, zanim zrestartujesz usługę i zerwiesz ruch na działającej stronie.
• Trzymaj adres aplikacji w jednym miejscu — jeśli reverse_proxy wskazuje localhost:3000, zmiana portu aplikacji wymaga poprawki tylko w tym jednym miejscu w pliku.
• Wybierz jeden wariant kanoniczny — przekierowanie ustawiaj zawsze w jedną stronę (na przykład www na adres bez www), inaczej łatwo o pętlę przekierowań.
• Kompresję włączaj świadomie — encode gzip zstd daje zysk przy odpowiedziach tekstowych; dla plików już skompresowanych, jak obrazy czy archiwa, nie zmienia wiele.
• Zadbaj o rotację logów — Caddy dopisuje wpisy do pliku, więc bez rotacji po stronie systemu plik rośnie bez ograniczeń.

Czego narzędzie nie uwzględnia

• Stanu DNS i serwera — generator tworzy wyłącznie tekst pliku. Nie sprawdzi, czy domena wskazuje na właściwy adres ani czy porty 80 i 443 są otwarte, a bez tego automatyczny TLS nie zadziała.
• Otoczenia sieciowego — firewall, NAT, CDN lub dodatkowe proxy przed Caddy mogą wymagać ustawień, których narzędzie nie zna i nie dopisze za Ciebie.
• Realnego zachowania aplikacji — narzędzie nie wie, ile instancji aplikacji masz ani czy odpowiadają poprawnie, więc nie dobierze limitów czasu, polityki ponowień ani liczby upstreamów.
• Zaawansowanych konstrukcji Caddyfile — snippety, importy, własne matchery i konfiguracja przez API wykraczają poza prosty generator; takie elementy dopisujesz ręcznie i samodzielnie weryfikujesz.

Najczęstsze pytania