Plik .env porządkuje konfigurację Docker Compose, ale nie szyfruje haseł i nie przekazuje automatycznie wszystkich zmiennych do kontenera. To rozróżnienie wyjaśnia wiele sytuacji, w których aplikacja widzi pustą wartość albo nadal korzysta ze starego ustawienia.
W tym poradniku rozdzielimy trzy rzeczy: podstawianie wartości do pliku Compose, środowisko procesu w kontenerze i przechowywanie sekretów. Przykład używa wyłącznie jawnych danych demonstracyjnych. Możesz sprawdzić jego działanie bez uruchamiania bazy i bez wystawiania portów.
Do czego służy Docker Compose .env
Compose odczytuje plik YAML i przygotowuje na jego podstawie konfigurację usług. Zapis ${APP_MODE} oznacza, że przed utworzeniem kontenera trzeba podstawić wartość zmiennej. Źródłem może być środowisko powłoki albo plik wskazany opcją --env-file.
Samo umieszczenie APP_MODE=demo w .env nie sprawia jeszcze, że aplikacja odczyta tę wartość. Musisz przekazać ją przez environment, przez env_file usługi albo wykorzystać w innym polu konfiguracji. Jeśli dopiero poznajesz strukturę YAML, zacznij od poradnika Docker Compose.
| Mechanizm | Co robi | Czego nie zapewnia |
|---|---|---|
.env lub --env-file |
Dostarcza wartości do podstawiania w Compose | Nie jest automatycznym eksportem całego pliku do kontenera |
environment |
Ustawia wskazane zmienne procesu usługi | Nie chroni wartości przed osobą mającą dostęp administracyjny |
env_file przy usłudze |
Wczytuje zmienne do środowiska kontenera | Nie jest tym samym co opcja CLI --env-file |
secrets |
Udostępnia wybranym usługom pliki z sekretami | W lokalnym Compose nie szyfruje źródłowego pliku na dysku |
W przykładach używam jawnego --env-file .env. Dzięki temu nie trzeba zgadywać, który plik został znaleziony przy uruchomieniu polecenia z innego katalogu.
Przygotuj mały projekt demonstracyjny
Utwórz osobny katalog roboczy. Nie kopiuj tych plików do działającej aplikacji bez dostosowania nazw i ustawień.
1. Zapisz wartości do podstawienia
Plik .env:
APP_MODE=demo
IMAGE_TAG=3.22
ONLY_FOR_COMPOSE=not-exported
Plik runtime.env:
MESSAGE=hello-from-runtime
APP_MODE=from-runtime
Oba pliki są zwykłym tekstem. Nazwa z kropką może ukrywać plik w domyślnym widoku menedżera plików, ale nie stanowi zabezpieczenia.
2. Zapisz compose.yaml
services:
demo:
image: alpine:${IMAGE_TAG:?Set IMAGE_TAG in .env}
network_mode: none
read_only: true
mem_limit: 64m
cpus: 0.25
env_file:
- runtime.env
environment:
APP_MODE: ${APP_MODE:?Set APP_MODE in .env}
command:
- sh
- -c
- 'printf "mode=%s message=%s hidden=%s\n" "$$APP_MODE" "$$MESSAGE" "$${ONLY_FOR_COMPOSE-unset}"'
Podwójny dolar powstrzymuje podstawienie przez Compose. Wartość odczyta dopiero powłoka wewnątrz kontenera. Bez tego część polecenia mogłaby zostać przetworzona wcześniej, na komputerze uruchamiającym Compose.
Zapis ${APP_MODE:?komunikat} zatrzymuje przygotowanie projektu, gdy zmienna jest pusta lub nieustawiona. To lepsze zachowanie dla wymaganej konfiguracji niż cichy start z błędnymi parametrami. Dla opcjonalnego ustawienia można zastosować ${APP_MODE:-demo}, które daje wartość domyślną również przy pustej zmiennej.
3. Sprawdź wynik
W katalogu projektu uruchom:
docker compose --env-file .env -p tt-env-demo config --quiet
docker compose --env-file .env -p tt-env-demo run --rm demo
Oczekiwany wynik procesu:
mode=demo message=hello-from-runtime hidden=unset
APP_MODE pochodzi z environment, dlatego nadpisuje wartość z runtime.env. MESSAGE dociera przez env_file. ONLY_FOR_COMPOSE pozostaje poza środowiskiem kontenera, bo nie przekazaliśmy jej do usługi.
Obraz Alpine może wymagać pobrania przez silnik Dockera. Sam uruchomiony kontener nie ma sieci. Zestawienie codziennych poleceń znajdziesz w ściądze Dockera.
Dlaczego terminal może nadpisać plik .env
Są dwa osobne etapy ustalania wartości. Najpierw Compose wykonuje interpolację YAML, a później składa środowisko kontenera. Mieszanie tych etapów prowadzi do mylącego przekonania, że istnieje jeden prosty ranking wszystkich plików i opcji.
W powłoce Bash sprawdź:
APP_MODE=from-shell docker compose --env-file .env -p tt-env-demo run --rm demo
Teraz mode powinno wynosić from-shell, ponieważ przy podstawianiu ${APP_MODE} środowisko powłoki ma pierwszeństwo przed plikiem. To ustawienie dotyczy jednego wywołania polecenia. Składnia przypisania na początku wiersza jest składnią Bash, a nie PowerShell.
Możesz też nadpisać wartość bezpośrednio dla jednorazowego kontenera:
docker compose --env-file .env -p tt-env-demo run --rm -e APP_MODE=from-cli demo
Przy diagnozowaniu problemu sprawdzaj więc kolejno: skąd pochodzi podstawiana wartość, gdzie jest przekazywana do kontenera i czy polecenie uruchomieniowe jej nie nadpisuje. Nie dopisuj tej samej zmiennej do kolejnych plików na próbę.
Jak trzymać konfigurację w repozytorium
Do repozytorium dodaj .env.example z nazwami ustawień i bezpiecznymi przykładami. Właściwe wartości produkcyjne przechowuj poza historią kodu. Przykładowy .gitignore może zawierać:
.env
.env.*
!.env.example
runtime.env
secrets/
To reguła ignorowania nowych plików, nie sposób usunięcia sekretu z istniejącej historii. Jeśli hasło trafiło do commita, samo dopisanie .gitignore nie rozwiązuje problemu. Unieważnij ujawniony sekret i zastąp go nowym. Historię repozytorium uporządkuj osobno, uwzględniając kopie i współpracowników.
Na Linuksie ogranicz dostęp do plików zawierających wrażliwe wartości:
chmod 600 .env runtime.env
Pliki nadal musi móc odczytać użytkownik uruchamiający Compose. Tryb 600 nie chroni przed rootem ani przed wyciekiem przez kopię zapasową. Znaczenie uprawnień możesz sprawdzić w kalkulatorze chmod, a polecenia kontroli plików w ściądze Linuksa.
Kiedy zamiast zmiennej użyć secrets
Hasło do bazy i klucz API nie są tym samym rodzajem ustawień co poziom logowania. Jeśli aplikacja potrafi czytać sekret z pliku, udostępnij go tylko usłudze, która go potrzebuje:
services:
app:
image: twoj-obraz:konkretna-wersja
secrets:
- api_token
secrets:
api_token:
file: ./secrets/api_token.txt
To fragment do dostosowania, nie gotowy obraz do pobrania. Sekret będzie dostępny dla tej usługi jako plik /run/secrets/api_token. Program musi go sam odczytać. Sufiks _FILE, spotykany w niektórych obrazach, jest konwencją konkretnej aplikacji, a nie uniwersalną funkcją każdej zmiennej Dockera.
Lokalny Compose korzystający z pliku nie zmienia go w zaszyfrowany sejf. Pilnuj praw źródła, kopii i dostępu do hosta. Oddziel również sekrety uruchomieniowe od danych aplikacji: wolumen przechowujący dane rozwiązuje problem trwałości, a nie zarządzania hasłami.
Zmieniony plik, a aplikacja nadal widzi starą wartość
docker compose restart restartuje istniejący kontener. Nie tworzy go ponownie z nowym środowiskiem. Dla działającej usługi po walidacji konfiguracji zastosuj docker compose up -d app, używając tego samego pliku i nazwy projektu co podczas wdrożenia.
Gdy aplikacja nadal zachowuje stare ustawienie, sprawdź, czy nie zapisała go we własnej bazie. Przykładem programu z ustawieniami utrwalanymi przez panel jest Open WebUI z Ollamą. Zmiana środowiska nie zawsze oznacza zmianę wartości zapisanej przez aplikację.
Uważaj też na diagnostykę. docker compose config bez --quiet może wypisać rozwiązane wartości. docker inspect pokazuje środowisko kontenera. Nie wklejaj całego wyniku do zgłoszenia ani czatu. W przykładzie demonstracyjnym dane są jawne; dla projektu produkcyjnego sprawdzaj konkretne niewrażliwe pola.
Najczęstsze pytania
Czy plik .env jest bezpiecznym miejscem na hasła?
Jest plikiem tekstowym. Może być elementem kontrolowanego wdrożenia, ale sam nie zapewnia szyfrowania ani ochrony przed administratorem hosta. Jeśli aplikacja obsługuje pliki sekretów, rozważ taki sposób przekazania haseł.
Czym różni się -env-file od env_file?
Opcja --env-file dostarcza Compose wartości do interpolacji i konfiguracji jego działania. Pole env_file przy konkretnej usłudze ustawia środowisko kontenera. Ten sam format zapisu nie oznacza identycznej funkcji.
Dlaczego zmienna z .env nie istnieje w kontenerze?
Sprawdź, czy przekazano ją przez environment lub env_file. Sama obecność zmiennej w pliku odczytywanym przez Compose nie eksportuje jej automatycznie do procesu aplikacji.
Jak zapisać znak dolara w command?
W pliku Compose użyj $$, gdy znak ma dotrzeć do dalszego etapu bez interpolacji przez Compose. Jeśli potem polecenie wykonuje powłoka, ona może rozwinąć zmienną. Znaczenie zależy więc również od samego programu uruchamiającego polecenie.
Czy restart wystarczy po zmianie .env?
Nie, jeśli zmieniasz środowisko kontenera. Zastosuj konfigurację przez up -d dla właściwej usługi i sprawdź efekt. W aplikacji przechowującej ustawienia w bazie może być potrzebna dodatkowa zmiana w jej panelu.
Źródła
- Docker Docs: źródła wartości do interpolacji.
- Docker Docs: environment i env_file.
- Docker Docs: pierwszeństwo zmiennych.
- Docker Docs: składnia interpolacji i znak dolara.
- Docker Docs: secrets w Compose.
- Docker Docs: walidacja konfiguracji.
- Docker Docs: zakres działania restart.
- Projekt Git: reguły gitignore.
Data publikacji: 24.10.2026.

Dyskusja