Установка NGINX в Docker

Обзор: запуск NGINX внутри Docker и структура проекта

Quick Links

Setting Up NGINX Inside Docker

Важно: этот подход оптимален для статических сайтов и одностраничных приложений (SPA). Для CMS с базой данных (например, WordPress) используйте внешнюю БД и специализированные образы.

Введение — зачем запускать NGINX в Docker

Docker позволяет упаковать приложение и все его зависимости в единый образ, который одинаково работает в локальной среде, тесте и продакшне. Контейнер по умолчанию «чистый»: нужно скопировать код, установить зависимости и выполнить сборку. Для NGINX часто проще взять официальный образ и разворачивать собранные артефакты в нём.

Если вы разворачиваете CMS (WordPress, Drupal), контейнеры не предназначены для персистентного хранения данных — используйте внешние базы и тома. Для WordPress существует готовый официальный Docker‑образ.

Для демонстрации возьмём пример с Vue.js, но та же схема применима к React, Svelte или статическому сайту.

Шаблон проекта: структура файлов Vue.js и Dockerfile

Структура и ключевые файлы

На корне проекта создайте файл с именем:

Dockerfile

Это конфигурация сборки образа. Принцип: в первом шаге («build-stage») собираем приложение с помощью node, во втором — используем nginx для отдачи статических файлов.

Пример Dockerfile (multi‑stage build):

FROM node:latest as build-stage

WORKDIR /src

COPY package*.json ./

RUN npm install

COPY ./ .

RUN npm run build

FROM nginx as production-stage

RUN mkdir /src

COPY --from=build-stage /src/dist /src

COPY nginx.conf /etc/nginx/nginx.conf

Пояснения по Dockerfile:

FROM node:latest as build-stage — скачивает образ node и помечает этап сборки как build-stage.
WORKDIR /src — рабочая директория внутри контейнера.
COPY package*.json ./ и RUN npm install — устанавливает зависимости до копирования всего кода (ускоряет кэширование слоёв).
RUN npm run build — генерирует production‑сборку (в Vue обычно появляется каталог dist).
FROM nginx as production-stage — берём официальный nginx как минимальный веб‑сервер.
COPY –from=build-stage /src/dist /src — копируем артефакты сборки во второй образ.
COPY nginx.conf /etc/nginx/nginx.conf — подставляем свою конфигурацию nginx.

.dockerignore

Создайте файл .dockerignore, чтобы исключить node_modules и локальные артефакты сборки:

/node_modules
/dist

Это уменьшит контекст сборки и ускорит процесс.

Пример nginx.conf для SPA

Ниже — пример минимальной конфигурации для раздачи статических файлов и корректной обработки маршрутизации в SPA (fallback на index.html):

user nginx;

worker_processes 1;

error_log /var/log/nginx/error.log warn;

pid /var/run/nginx.pid;

events {

worker_connections 1024;

}

http {

include /etc/nginx/mime.types;

default_type application/octet-stream;

log_format main '$remote_addr - $remote_user [$time_local] "$request" '

'$status $body_bytes_sent "$http_referer" '

'"$http_user_agent" "$http_x_forwarded_for"';

access_log /var/log/nginx/access.log main;

sendfile on;

keepalive_timeout 65;

server {

listen 80;

server_name localhost;

location / {

root /src;

index index.html;

try_files $uri $uri/ /index.html;

}

error_page 500 502 503 504 /50x.html;

location = /50x.html {

root /usr/share/nginx/html;

}

}

}

Ключевой момент: try_files $uri $uri/ /index.html — это стандартный приём для SPA, чтобы маршрутизация на клиенте работала при прямом обращении к URL.

HTTPS и сертификаты

Самый простой путь настроить HTTPS — получить сертификат через Let’s Encrypt (certbot) на хосте и скопировать файлы сертификата в образ перед деплоем. Типичный путь к сертификатам: /etc/letsencrypt/live/example.com/fullchain.pem и privkey.pem. Сертификаты Let’s Encrypt действуют 90 дней — нужна регулярная автоматическая продление и перезагрузка nginx.

Рекомендации по автоматизации:

Выполняйте получение/обновление сертификатов на хосте (outside of container), затем монтируйте их в контейнер через томы или копируйте в процессе CI.
Используйте подход “sidecar” или отдельный контейнер для certbot с общим томом, чтобы обновления происходили без остановки основного сервиса.
Для крупного окружения применяйте ACME‑клиенты, интегрированные с оркестраторами (Kubernetes Ingress, AWS ALB + ACM, Traefik).

Примечание: хранение приватных ключей внутри неизолированных образов повышает риск компрометации, лучше монтировать секреты как том или использовать secret‑менеджер.

Сборка и локальная проверка

Сборка образа:

docker build . -t my-app

Запуск локально (привязка порта 8080 на хосте к 80 в контейнере):

docker run -d -p 8080:80 my-app

После этого на http://localhost:8080 должен открываться ваш сайт.

Деплой в продакшн и CI/CD

После получения образа вы можете запушить его в реестр (Docker Hub, ECR, GCR) и развернуть на платформе контейнерного оркестратора (AWS ECS, Kubernetes, Docker Swarm). Рекомендации для продакшна:

Пропишите healthcheck и readiness probe (в Kubernetes liveness/readiness) для корректного rolling update.
Используйте immutable‑теги (sha256 digest) для предсказуемого развёртывания.
Настройте логирование в stdout/stderr и собирайте логи централизованно (ELK, Loki).
Параметризуйте конфигурацию с помощью переменных окружения и шаблонов (envsubst, confd, consul-template) при необходимости.

Когда этот подход не подходит — ограничения и контрпример

Динамические приложения с интенсивной серверной логикой (PHP/WordPress, Python/Django) обычно требуют отдельного runtime и персистентного хранилища: лучше использовать специализированные образы и отдельные сервисы БД.
Если приложение хранит пользовательские файлы в контейнере — данные пропадут при пересоздании контейнера. Решение: использовать тома или внешние хранилища (S3, NFS).

Альтернативные подходы

Traefik или nginx‑ingress (в Kubernetes) для автоматического получения и обновления сертификатов через ACME.
Использовать CDN (Cloudflare, AWS CloudFront) перед NGINX для кеширования и HTTPS‑терминации.
Static site hosts (Netlify, Vercel) для простых статических сайтов — не требует управления контейнерами.

Ментальные модели и чек‑листы по ролям

Разделим основные обязанности:

Разработчик:
- Настроить сборку (npm run build), проверить dist локально.
- Создать Dockerfile и .dockerignore.
- Проверить try_files в nginx.conf для SPA.
DevOps/Инженер по релизам:
- Настроить CI сборку образа и push в реестр.
- Настроить процесс получения/обновления сертификатов.
- Настроить мониторинг и провижнинг ресурсов (CPU, RAM).
QA:
- Проверить статические ресурсы, fallback на index.html.
- Проверить корректность заголовков (Cache-Control, Content-Type).
- Проверить поведение при отсутствии сертификата/при просрочке.

Тесты и критерии приёмки

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

Собираемый образ запускается и возвращает 200 на /.
При обращении по несуществующему URL SPA возвращает index.html и статус 200.
HTTP→HTTPS редирект (если настроено) корректно работает.
При обновлении образа происходит без простоев (rolling update) и здоровые поды остаются доступны.

Минимальные тесты:

smoke test: запрос корня сайта.
routing test: запрос вложенного пути /some/path должен вернуть HTML страницы.
asset test: запрос статического файла (например, /app.js) должен вернуть корректный mime‑type.

Безопасность и приватность (коротко)

Не храните приватные ключи сертификатов в незашифрованных образах. Монтируйте их как том или используйте секреты оркестратора.
Разрешения файлов: ключи должны быть доступны только для процесса nginx.
Отключите ненужные модули и минимизируйте поверхность атаки: используйте минимальные базовые образы.

Шаблоны и сниппеты (шпаргалка)

Docker build и run:

docker build . -t my-app:latest
docker tag my-app:latest registry.example.com/my-app:2025-11-01
docker push registry.example.com/my-app:2025-11-01

Пример команды для запуска с томом сертификатов:

docker run -d -p 443:443 -v /etc/letsencrypt/live/example.com:/etc/letsencrypt:ro my-app

SOP (коротко):

Локальная сборка → CI → тесты → пуш в реестр → деплой в стейдж → smoke → деплой в прод.

Подводные камни и советы

Кэширование npm install: используйте отдельный слой в Dockerfile и COPY package*.json перед копированием кода.
Размер образа: multi‑stage сборка значительно уменьшает размер продакшн‑образа.
Обновления nginx: если вы меняете конфигурацию и сертификаты, не забывайте перезапустить nginx внутри контейнера или использовать reload при orchestration.

Краткое резюме

Multi‑stage Dockerfile (node → nginx) — стандартный и эффективный способ раздавать статические сайты.
Обязательно добавьте .dockerignore, настройте try_files для SPA и автоматизируйте работу с сертификатами.
Для динамических приложений рассматривайте более сложную архитектуру с отдельными сервисами и персистентными томами.

Список основных шагов:

Настроить сборку приложения (npm run build).
Описать multi‑stage Dockerfile: сборка в node, продакшн на nginx.
Добавить .dockerignore и nginx.conf.
Собрать образ, протестировать локально, залить в реестр и настроить CI/CD.

1‑line glossary:

Контейнер: изолированная среда выполнения приложения.
Образ (image): снапшот файловой системы и конфигурации контейнера.
Multi‑stage build: приём, позволяющий собирать артефакты в одном образе и копировать только нужное в итоговый образ.