Docker-образ для .NET 5 Web API

Одно из главных преимуществ Docker — возможность запускать проекты без сложной локальной настройки окружения. Это руководство покажет, как приготовить Docker-образ для .NET 5 Web API, чтобы вы могли запускать бэкенд на любой машине с Docker и обращаться к API из фронтенда или мобильного приложения.

Что вы получите

• Рабочий .NET 5 Web API проект.
• Корректный Dockerfile для сборки образа.
• Команды для сборки и запуска контейнера.
• Практические советы по безопасности, отладке и CI/CD.

Предпосылки

• .NET 5 SDK и/или Runtime установлен(ы) локально (если планируете запускать проект без Docker).
• Docker Engine установлен и запущен.
• Базовые навыки командной строки (Windows PowerShell, macOS Terminal, Linux shell).

Совет: если .NET 5 не установлен, скачайте его с официального сайта .NET для вашей ОС.

Создание .NET 5 Web API

Docker и .NET 5 — кроссплатформенные и открытые, поэтому шаги одинаковы для macOS, Windows и Linux.

Создайте проект ASP.NET Web API через dotnet CLI командой:

dotnet new webapi -o aspdockerapi

Эта команда создаст проект с именем “aspdockerapi” и подготовит контроллер с образцом данных (WeatherForecast).

Перейдите в корневую папку проекта:

cd aspdockerapi

Запустите приложение локально (без Docker) для проверки:

dotnet run

По умолчанию приложение будет доступно на порту 5001 (HTTPS). Откройте https://localhost:5001/weatherforecast — вы увидите JSON с тестовыми данными.

Подготовка Dockerfile

Docker собирает образы по инструкциям из файла с именем Dockerfile (без расширения). Создайте пустой Dockerfile в корне проекта:

touch Dockerfile

После этого структура папок проекта должна выглядеть примерно так:

Скопируйте в Dockerfile следующий код (обратите внимание на имена проекта и dll):

FROM mcr.microsoft.com/dotnet/aspnet:5.0-focal AS base
WORKDIR /app
EXPOSE 80

FROM mcr.microsoft.com/dotnet/sdk:5.0-focal AS build
WORKDIR /src
COPY ["aspdockerapi.csproj", "./"]
RUN dotnet restore "./aspdockerapi.csproj"
COPY . .
WORKDIR "/src/."
RUN dotnet build "aspdockerapi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "aspdockerapi.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "aspdockerapi.dll"]

Важно: если ваш проект называется иначе, замените все встретившиеся имена файлов (aspdockerapi.csproj, aspdockerapi.dll) на корректные.

Разбор инструкций Dockerfile

Ниже — краткие определения ключевых директив, используемых в примере Dockerfile.

• FROM — указывает базовый образ, на котором строится слой. Здесь используется официальный образ .NET 5 от Microsoft.
• WORKDIR — задаёт рабочую директорию внутри контейнера. Она создаётся автоматически при необходимости.
• COPY — копирует файлы/папки из контекста сборки в образ.
• RUN — выполняет команду в процессе сборки образа; часто используется для восстановления зависимостей и компиляции.
• EXPOSE — документирует, какой порт контейнера предназначен для входящих подключений (фактическое проброс портов делается при запуске).
• ENTRYPOINT — указывает команду, которая будет выполнена при старте контейнера (запуск приложения).

Пояснение: RUN используется на этапе сборки образа, CMD/ENTRYPOINT — при запуске контейнера. В нашем Dockerfile ENTRYPOINT запускает готовую сборку приложения.

Сборка Docker-образа

Чтобы собрать образ из Dockerfile, выполните команду в корне проекта (там, где лежит Dockerfile):

docker build -t dockerwebapi -f Dockerfile .

Флаг -t задаёт тег (имя) образа — в примере dockerwebapi. После успешной сборки проверьте локальные образы:

docker images

Вы должны увидеть в списке образ с именем dockerwebapi:

Если Docker не установлен, следуйте официальному руководству по установке Docker для вашей ОС.

Запуск контейнера

Запустите контейнер и пробросьте порт 80 контейнера на локальный 8080:

docker run -ti --rm -p 8080:80 dockerwebapi

Опции:

• -ti — интерактивный терминал (полезно для отладки).
• –rm — автоматически удаляет контейнер после остановки.
• -p 8080:80 — пробрасывает локальный порт 8080 на порт 80 внутри контейнера.

Откройте http://localhost:8080/WeatherForecast — вы увидите тот же JSON, но уже обслуживаемый контейнером.

Отладка и логирование

• Просмотр логов контейнера: docker logs .
• Запустить контейнер в интерактивном режиме с шеллом (если образ содержит shell):

docker run -it --rm --entrypoint /bin/bash dockerwebapi

• Используйте переменные окружения (ENV) через -e при запуске: docker run -e ASPNETCORE_ENVIRONMENT=Development …

Советы по безопасности и боевой эксплуатации

Важно: по умолчанию контейнеры запускаются с root-пользователем в образе. Для продакшена рекомендуется запускать приложение от непривилегированного пользователя и минимизировать базовый образ.

Рекомендации:

• Используйте многоступенчатую сборку (как в примере) — это уменьшает размер финального образа и исключает лишние инструменты.
• Сканируйте образы на уязвимости (Trivy, Anchore, Clair).
• Либо создайте непользовательского пользователя в Dockerfile и переключитесь на него перед запуском приложения.
• Минимизируйте число открытых портов и используйте сетевые политики в оркестраторе.
• Подписывайте образы и используйте приватные реестры с авторизацией для продакшен-образов.

CI/CD: пример мини-методологии

1. Сборка и тесты: на CI выполняются dotnet restore, dotnet build, dotnet test.
2. Сборка Docker-образа в CI с тегом, основанном на CI-номере или SHA.
3. Сканирование образа на уязвимости.
4. Публикация образа в реестр (Docker Hub, ACR, ECR, GCR).
5. Деплой в staging, smoke tests, затем в production через оркестратор (Kubernetes, Docker Swarm).

Пример fragment для GitHub Actions (схематично):

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup .NET
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: '5.0.x'
      - run: dotnet restore
      - run: dotnet build --configuration Release
      - run: dotnet test --no-build --verbosity normal
      - name: Build Docker image
        run: docker build -t myregistry/dockerwebapi:${{ github.sha }} .
      - name: Scan image
        run: trivy image myregistry/dockerwebapi:${{ github.sha }}
      - name: Push image
        run: |
          echo ${{ secrets.REGISTRY_PASSWORD }} | docker login -u ${{ secrets.REGISTRY_USER }} --password-stdin myregistry
          docker push myregistry/dockerwebapi:${{ github.sha }}

Когда Docker не лучший выбор

• Если проект требует полного виртуализованного окружения (включая разные ядра или гипервизорные функции), лучше использовать виртуальные машины.
• Для простых одноразовых скриптов, которые выполняются локально и не нуждаются в переносимости, Docker может добавить лишнюю сложность.
• Если ваша команда не готова поддерживать жизненный цикл образов (обновление, сканирование, реестр), внедрение Docker может создать операционные риски.

Миграция на более новые версии .NET

.NET 5 достиг конца срока поддержки (EOL) — планируйте миграцию на поддерживаемые LTS-версии (.NET 6, .NET 7/8 в зависимости от потребностей). Шаги миграции:

1. Обновите SDK локально и CI-конфигурацию.
2. Исправьте устаревшие API и warnings.
3. Проведите тесты и обновите Dockerfile-образы на mcr.microsoft.com/dotnet/aspnet:6.0 или более новые.

Чек-листы по ролям

Разработчик:

• Проверил запуск локально dotnet run
• Добавил Dockerfile и протестировал локальный образ
• Обновил README с командами сборки и запуска

DevOps/Системный инженер:

• Настроил CI для сборки и сканирования образов
• Настроил приватный реестр и политику тэгирования
• Обеспечил управление секретами и доступом

QA:

• Прогнали smoke-тесты против контейнера
• Проверили логирование и метрики
• Проверили поведение при рестартах/обновлениях

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

• Образ успешно собирается на CI и размещается в реестре.
• Контейнер запускается и отвечает на /WeatherForecast.
• Сканирование не выявляет критических уязвимостей.
• Документация содержит команды для локальной сборки, запуска и отладки.

Короткий глоссарий

• Контейнер: изолированный процесс, запущенный из образа.
• Образ: статический файл с артефактами и слоями для запуска контейнера.
• Реестр: хранилище образов (Docker Hub, ACR, ECR).

Резюме

Это руководство дало вам пошаговый путь от создания .NET 5 Web API до упаковки приложения в Docker-образ и запуска контейнера локально. Включены рекомендации по безопасности, практики CI/CD и контрольные списки для разных ролей в команде.

Важное: планируйте миграцию на поддерживаемые версии .NET и внедряйте сканирование образов как часть процесса доставки.