Kurs vibe coding z Claude Code · Moduł 13: Klon Twitcha
Zamknięta skrzynia: kontener Next.js z Claude Code
W tej lekcji9
Klon działa u Ciebie. Bosman klonuje repozytorium na swoim laptopie, instaluje zależności i uruchamia build, a po chwili widzi błąd, którego Ty nigdy nie widziałeś: ma inną wersję Node.js i inny system. Serwer, na którym klon ma kiedyś działać, będzie miał jeszcze inne. Każda taka różnica to rafa, na którą statek wpada dopiero w obcym porcie. Potrzebujesz skrzyni, która dopływa wszędzie w tym samym stanie. W świecie programistów nazywa się ona kontener.
Trzy słowa na start. Obraz (image) to spakowany ładunek: system, Node.js, zależności i zbudowana aplikacja. Kontener to uruchomiony obraz, odgrodzony od reszty komputera. Dockerfile to przepis, według którego Docker buduje obraz krok po kroku. Dockera instalujesz sam, według strony docs.docker.com/get-docker. Dokumentacja Next.js radzi na Macu i Windowsie pracować na co dzień z npm run dev, bo działa szybciej, a kontener zostawić na produkcję: skrzynię pakujesz na drogę, nie do pracy przy stole nawigacyjnym.
Czego się nauczysz
- zamówić u Claude Code kontener, zaczynając od aktualnej dokumentacji, a nie od pamięci agenta;
- przeczytać wieloetapowy Dockerfile i wskazać, co trafia do końcowego obrazu;
- trzymać plik
.envpoza repozytorium i poza obrazem; - zamknąć niszczącą komendę Dockera regułą
denyi wiedzieć, gdzie kończy się jej ochrona; - powiedzieć, gdzie tryb
bypassPermissionsma sens, a gdzie nigdy.
Polecenie dla Claude Code
Agent zna Dockera z tekstów sprzed lat, a przykłady w sieci starzeją się szybciej niż obrazy Node.js. Dlatego pierwsze zdanie polecenia każe mu przeczytać aktualne źródło, a drugie wybrać i uzasadnić tryb budowania. Krok dotyka czterech plików, więc zaczynasz od planu, jak w lekcji 1_6. Komendy Dockera uruchomisz sam, z powodu, który poznasz niżej.
Polecenie dla Claude Code:
/plan Skonteneryzuj aplikację. Najpierw przeczytaj stronę
https://nextjs.org/docs/app/getting-started/deploying (sekcja Docker)
i przykład with-docker, do którego prowadzi, i napisz, jaki tryb
wyjścia budowania wybierasz i dlaczego. Potem: wieloetapowy Dockerfile
(zależności, build, uruchomienie) na obrazie aktualnego Node.js LTS,
.dockerignore i compose.yaml. Zmienne środowiskowe czytaj z pliku
.env, którego nie ma w repozytorium ani w obrazie.
Będzie gotowe, gdy: npm run build utworzy .next/standalone/server.js.
Komend docker nie uruchamiaj, zrobię to sam.W planie sprawdź jedną rzecz: tryb wyjścia budowania. Jeśli Claude go nie wymienia albo wybiera bez uzasadnienia, odpowiedz "No, keep planning" i zapytaj o niego wprost.
Co napisał Claude: tryb standalone
Pierwsza zmiana jest najmniejsza i najważniejsza. Otwórz w Cursorze next.config.ts, a zobaczysz nową linię na początku konfiguracji:
// next.config.ts
const nextConfig: NextConfig = {
output: "standalone",
// reszta konfiguracji bez zmian
};Z tą opcją npm run build zbiera w katalogu .next/standalone tylko pliki potrzebne do uruchomienia aplikacji i mały serwer server.js. U nas katalog miał 41 MB, a pełne node_modules 517 MB. Opcja nie zmienia wyglądu strony ani działania npm run dev. Bez niej build też przechodzi, ale katalogu .next/standalone po prostu nie ma: sprawdziliśmy to, a Dockerfile niżej nie miałby wtedy czego skopiować.
Co napisał Claude: Dockerfile etap po etapie
Otwórz Dockerfile. Każde FROM zaczyna nowy etap (stage), a słowo po AS nadaje mu nazwę. Końcowy obraz to tylko ostatni etap; wcześniejsze są jak warsztat w porcie, który zostaje na lądzie. Pierwsze dwa etapy:
FROM node:26-slim AS base
WORKDIR /app
FROM base AS deps
COPY package.json package-lock.json ./
RUN npm cibase wybiera obraz Node.js i katalog roboczy /app, a kolejne etapy dziedziczą oba. Tag 26-slim to aktualny Node.js LTS (stan na listopad 2026) w odchudzonym wariancie. Przykład Next.js wybiera slim zamiast alpine, bo slim ma standardową bibliotekę systemu Linux i lepiej znosi paczki npm z częściami natywnymi. deps kopiuje tylko dwa pliki z listą zależności i uruchamia npm ci, czyli instalację dokładnie według package-lock.json. Gdy zmienisz komponent, a nie zależności, Docker weźmie ten krok z pamięci podręcznej i nie zainstaluje wszystkiego od nowa.
Trzeci etap buduje aplikację:
FROM base AS builder
COPY /app/node_modules ./node_modules
COPY . .
RUN npm run buildCOPY --from=deps przenosi node_modules z poprzedniego etapu, a COPY . . cały kod projektu. To najcięższy etap: ma pełne zależności, kod źródłowy i wynik budowania. Do końcowego obrazu nie trafia z niego nic poza tym, co wskaże ostatni etap, a ten wygląda tak:
FROM base AS runner
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME=0.0.0.0
COPY /app/public ./public
COPY /app/.next/standalone ./
COPY /app/.next/static ./.next/static
EXPOSE 3000
CMD ["node", "server.js"]runner dostaje tylko wynik budowania. server.js z trybu standalone czyta port ze zmiennej PORT, a adres z HOSTNAME. Wartość 0.0.0.0 znaczy "słuchaj na wszystkich adresach kontenera", tak jak w przykładzie Next.js. EXPOSE tylko opisuje port, niczego nie otwiera. Najłatwiej przeoczyć linie z public i .next/static, bo katalog standalone ich nie zawiera. Uruchomiliśmy server.js bez nich: strona odpowiedziała 200, ale plik CSS i film rejsu dostały 404.
Co napisał Claude: .dockerignore i compose.yaml
COPY . . kopiuje cały folder projektu, czyli kontekst budowania, poza tym, co wyklucza .dockerignore. Otwórz ten plik i przeczytaj go od góry:
node_modules
.next
.git
.env
.env*.localnode_modules i .next i tak powstają w kontenerze od nowa, a .git to historia, której obraz nie potrzebuje. Najważniejsze są dwie ostatnie linie. Przykład Next.js ostrzega, że plik ze zmiennymi obecny w kontekście trafia przy trybie standalone do .next/standalone, a stamtąd do obrazu, gdzie przeczyta go każdy, kto obraz pobierze.
Teraz compose.yaml. Docker Compose to narzędzie, które jedną komendą buduje obraz i uruchamia kontener z portami i zmiennymi opisanymi w pliku:
services:
app:
build: .
ports:
- "3000:3000"
env_file: .envbuild: . buduje obraz z Dockerfile w tym folderze. "3000:3000" łączy port 3000 Twojego komputera z portem 3000 kontenera. env_file wczytuje zmienne z .env dopiero przy starcie kontenera, więc wartości nie ma ani w repozytorium (linia .env* w .gitignore z create-next-app), ani w obrazie. Klon nie ma jeszcze sekretów, więc utwórz pusty .env; bez niego docker compose config odpowiedział u nas env file ... not found. Starsza nazwa docker-compose.yml też działa, ale dokumentacja Dockera nazywa compose.yaml domyślną.
W pliku nie ma klucza version, który widzisz w starych poradnikach. Dokumentacja Compose mówi, że jest przestarzały i tylko informacyjny. Na pliku z version: '3.8' komenda docker compose config wypisała u nas ostrzeżenie, że atrybut jest przestarzały i zostanie zignorowany (is obsolete, it will be ignored).
Zamek na skrzyni: reguła deny dla Dockera
Docker ma komendy, które sprzątają za dużo. Według dokumentacji docker system prune -a usuwa wszystkie nieużywane kontenery, sieci, obrazy i pamięć podręczną budowania. Pyta o potwierdzenie, ale opcja -f to pytanie pomija. Jeśli na Twoim komputerze stoją obrazy innych projektów, po takim sprzątaniu ich nie ma. Regułę deny znasz z lekcji 8_4, gdzie zamknęła .env. Poproś Claude o regułę dla Dockera w .claude/settings.json, razem z regułami dla .env z tamtej lekcji:
{
"permissions": {
"deny": ["Bash(docker system prune *)", "Read(./.env)", "Read(./.env.*)"]
}
}Spacja przed gwiazdką sprawia, że reguła łapie docker system prune z dowolnymi opcjami. Dokumentacja Claude Code mówi, że reguły deny blokują w każdym trybie, także w auto i bypassPermissions. Sprawdź to prośbą "Uruchom docker system prune -a": Claude Code nie uruchomi komendy, a Claude zobaczy odmowę z powodu reguły. Gdy poprosisz ogólniej, na przykład "wyczyść nieużywane obrazy", Claude może sięgnąć po docker image prune -a, której ta reguła nie zna. Sprzątanie zostaje więc Twoją decyzją, we własnym terminalu.
Zamek ma jednak granice. Dokumentacja uprawnień mówi wprost, że reguła Bash dopasowuje tekst komendy, więc nie jest granicą bezpieczeństwa: ta sama komenda zapisana inaczej, na przykład w sh -c '...' albo z pełną ścieżką programu, reguły nie dotyka. Z Read(./.env) jest podobnie. Z lekcji 8_4 wiesz, że nie obejmuje komend, które czytają plik, nie nazywając go. U nas docker compose config wypisał wartość z .env otwartym tekstem, choć reguła stała na miejscu. Wynik komendy uruchomionej przez Claude trafia do rozmowy, i dlatego Dockera uruchamiasz sam. Twardą izolację daje dopiero sandbox (/sandbox), który ogranicza komendy na poziomie systemu.
Gdzie bypassPermissions ma sens
Tryb bypassPermissions z lekcji 0_4 zatwierdza bez pytania prawie wszystko. Dokumentacja Claude Code przeznacza go wyłącznie do odizolowanych środowisk: kontenerów i maszyn wirtualnych, w których Claude nie zaszkodzi Twojemu komputerowi. Uwaga na pomyłkę: kontener aplikacji, który właśnie zbudowałeś, to nie to miejsce, bo Claude Code w nim nie pracuje. Chodzi o kontener, w którym działa sam Claude Code, na przykład dev container, czyli środowisko deweloperskie opisane plikiem .devcontainer/devcontainer.json. Dokumentacja Claude Code ma do niego gotową konfigurację. Nawet tam Claude zmienia pliki projektu, które widzisz na swoim dysku, i sięga wszędzie, dokąd pozwala sieć kontenera, a reguły deny dalej działają. Na własnym komputerze, poza takim kontenerem, bypassPermissions nie włączasz nigdy.
Przegląd kapitana
- Sekrety poza skrzynią.
.envstoi w.dockerignore, agit statusgo nie pokazuje. - Lekki ładunek. W etapie
runnernie maCOPY --from=depsaniCOPY . ., za to sąpublici.next/static. - Aktualny Node.js. Tag obrazu to bieżący LTS ze strony nodejs.org, a nie wersja z poradnika sprzed lat, którą agent lubi wpisywać z pamięci.
- Compose bez balastu. Brak klucza
versioni brak haseł podenvironment.
Typowy błąd agenta to dane dostępowe wpisane prosto do pliku Compose, na przykład DATABASE_URL=postgresql://kapitan:tajne@db:5432/deck pod environment, albo pominięty output: "standalone", przez który etap runner nie ma czego skopiować. Sprawdzian robisz we własnym terminalu w Cursorze: npm run build i ls .next/standalone/server.js, potem docker compose config, które nie może wypisać ostrzeżeń, i docker compose up --build. Gdy kontener wstanie, otwórz localhost:3000: strona ma mieć style, a /channel/kapitan-redbeard ma grać rejs. Kontener zatrzymasz komendą docker compose down.
Następny krok
Gdy przegląd przejdzie, poproś o commit "Kontener: standalone, Dockerfile, compose i reguła deny". Potem jeden mały krok, który przykład Next.js robi dla bezpieczeństwa: aplikacja w kontenerze nie powinna działać jako root, czyli administrator systemu.
Polecenie dla Claude Code:
Uruchamiaj aplikację w etapie runner jako użytkownik node, tak jak
przykład with-docker z dokumentacji Next.js. Pokaż diff Dockerfile.W diffie szukaj trzech rzeczy z przykładu: linii USER node przed CMD, opcji --chown=node:node przy kopiowaniu plików do runner i katalogu .next należącego do tego użytkownika, bo serwer zapisuje tam pamięć podręczną stron. Obraz node ma takiego użytkownika gotowego, więc nikt go nie tworzy. Gdy proces nie jest rootem, błąd w aplikacji daje mniej władzy nad kontenerem. W edytorze poniżej czeka przegląd kapitana w miniaturze: wersja agenta pliku Compose i .dockerignore, a sprawdzarka wskaże version, hasło w pliku i brak .env.
Zapamiętaj: dobra skrzynia ma zamek, a dobry kapitan wie, które klucze oddaje agentowi, a które nosi przy sobie.
Kod do tej lekcji: App.tsx
// Przegląd kapitana w miniaturze: sprawdzarka pliku Compose i .dockerignore
import { useState } from 'react';
interface Finding {
ok: boolean;
title: string;
detail: string;
}
const AGENT_COMPOSE = [
"version: '3.8'",
'services:',
' app:',
' build: .',
' ports:',
' - "3000:3000"',
' environment:',
' - DATABASE_URL=postgresql://kapitan:tajne@db:5432/deck',
].join('\n');
const AGENT_IGNORE = ['node_modules', '.next', '.git'].join('\n');
const GOOD_COMPOSE = [
'services:',
' app:',
' build: .',
' ports:',
' - "3000:3000"',
' env_file: .env',
].join('\n');
const GOOD_IGNORE = ['node_modules', '.next', '.git', '.env', '.env*.local'].join('\n');
// Dane dostępowe w adresie (uzytkownik:haslo@) albo zmienna o nazwie sekretu z wpisaną wartością
const CREDENTIALS_IN_URL = /:\/\/[^\s:/@]+:[^\s@]+@/;
const SECRET_VALUE = /(PASSWORD|SECRET|TOKEN|API_KEY)\s*[:=]\s*\S+/i;
function lines(text: string): string[] {
return text.split('\n').map((line) => line.trim());
}
export function reviewCrate(compose: string, dockerignore: string): Finding[] {
const findings: Finding[] = [];
const hasVersion = /^\s*version\s*:/m.test(compose);
findings.push({
ok: !hasVersion,
title: 'Klucz version',
detail: hasVersion
? 'Przestarzały: Compose go ignoruje i wypisuje ostrzeżenie. Usuń tę linię.'
: 'Brak klucza version, tak jak zaleca dokumentacja Compose.',
});
const leaked = compose.split('\n').find((line) => CREDENTIALS_IN_URL.test(line) || SECRET_VALUE.test(line));
findings.push({
ok: !leaked,
title: 'Hasła w pliku',
detail: leaked
? 'Ta linia jedzie z repozytorium do każdego, kto je sklonuje: ' + leaked.trim() + '. Przenieś wartość do .env.'
: 'Plik nie zawiera haseł ani tokenów.',
});
const usesEnvFile = /^\s*env_file\s*:/m.test(compose);
findings.push({
ok: usesEnvFile,
title: 'Zmienne z .env',
detail: usesEnvFile
? 'env_file wczytuje zmienne przy starcie kontenera, więc wartości nie ma w repozytorium ani w obrazie.'
: 'Brak env_file: zmienne trzeba podać inaczej, a kusi wpisanie ich prosto do pliku.',
});
const ignored = lines(dockerignore);
const ignoresEnv = ignored.includes('.env') || ignored.includes('.env*');
findings.push({
ok: ignoresEnv,
title: '.env w .dockerignore',
detail: ignoresEnv
? 'COPY . . pominie .env, więc plik nie trafi do obrazu.'
: 'COPY . . skopiuje .env do kontekstu, a tryb standalone przeniesie go do obrazu.',
});
const port = compose.match(/-\s*"(\d+):(\d+)"/);
findings.push({
ok: Boolean(port),
title: 'Port',
detail: port
? 'Port ' + port[1] + ' Twojego komputera prowadzi do portu ' + port[2] + ' w kontenerze.'
: 'Brak mapowania portu w cudzysłowie, na przykład "3000:3000".',
});
return findings;
}
export default function App() {
const [compose, setCompose] = useState(AGENT_COMPOSE);
const [dockerignore, setDockerignore] = useState(AGENT_IGNORE);
const findings = reviewCrate(compose, dockerignore);
const problems = findings.filter((f) => !f.ok).length;
return (
<div className="min-h-screen space-y-4 bg-zinc-950 p-4 text-zinc-100">
<h1 className="text-xl font-bold">Przegląd kapitana: skrzynia</h1>
<div className="flex flex-wrap gap-2">
<button
type="button"
onClick={() => {
setCompose(AGENT_COMPOSE);
setDockerignore(AGENT_IGNORE);
}}
className="rounded bg-zinc-700 px-3 py-2 text-sm"
>
Wersja agenta
</button>
<button
type="button"
onClick={() => {
setCompose(GOOD_COMPOSE);
setDockerignore(GOOD_IGNORE);
}}
className="rounded bg-purple-600 px-3 py-2 text-sm font-semibold"
>
Wersja po przeglądzie
</button>
</div>
<div className="grid gap-3 sm:grid-cols-2">
<label className="block text-sm">
compose.yaml
<textarea
value={compose}
onChange={(e) => setCompose(e.target.value)}
rows={9}
spellCheck={false}
className="mt-1 block w-full rounded bg-zinc-900 p-2 font-mono text-xs"
/>
</label>
<label className="block text-sm">
.dockerignore
<textarea
value={dockerignore}
onChange={(e) => setDockerignore(e.target.value)}
rows={9}
spellCheck={false}
className="mt-1 block w-full rounded bg-zinc-900 p-2 font-mono text-xs"
/>
</label>
</div>
<p role="status" className={problems ? 'font-semibold text-amber-400' : 'font-semibold text-emerald-400'}>
{problems ? 'Do poprawy: ' + problems : 'Skrzynia gotowa do drogi'}
</p>
<ul className="space-y-2 text-sm">
{findings.map((f) => (
<li key={f.title} className="rounded border border-zinc-800 p-2">
<strong className={f.ok ? 'text-emerald-400' : 'text-red-400'}>{f.ok ? 'OK' : 'Popraw'}</strong> {f.title}
<p className="text-zinc-400">{f.detail}</p>
</li>
))}
</ul>
</div>
);
}Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Po co konteneryzujemy aplikację Next.js w Dockerze?
2. Który etap Dockerfile z lekcji ma pełne node_modules i kod źródłowy, a który dostaje tylko wynik budowania?
Zadania praktyczne w grze
- Układanie w pionie
Uporządkuj etapy (stages) Dockerfile od góry pliku:
- Układanie w poziomie
Ułóż mapowanie portu w compose.yaml (jedna linia): "3000:3000"