Publicando aplicações .NET como containers sem Dockerfile

Cenário da aplicação

Para exemplificar o processo, considerei uma aplicação .NET minimalista. Ela tem apenas o necessário para validar o empacotamento:

• Uma API com um único endpoint HTTP.
• Retorno da data e hora atual em UTC.
• Exposição da documentação OpenAPI.
• Uma interface simples de visualização com o Scalar UI.

O objetivo não é a complexidade da aplicação, mas sim demonstrar o fluxo de empacotamento e publicação. Veja como fica o Program.cs de um projeto chamado TimeApi:

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Gera o documento OpenAPI da API
builder.Services.AddOpenApi();

var app = builder.Build();

// Expõe o documento OpenAPI e a interface do Scalar
app.MapOpenApi();
app.MapScalarApiReference();

// Retorna a data e hora atual do servidor em UTC
app.MapGet("/time", () => new { utcNow = DateTime.UtcNow });

app.Run();

Ao executar a aplicação localmente com dotnet run, um simples GET /time retorna o horário atual do servidor. Dessa forma, confirmamos que a API está funcional antes de pensar em containers.

Se você ainda não domina esse estilo de API, o artigo sobre Minimal APIs no ASP.NET explica os fundamentos. Já a parte de documentação aparece em detalhes no guia de OpenAPI, Swagger e Scalar na prática.

Containers com Dockerfile na abordagem tradicional

Historicamente, empacotar aplicações .NET em containers sempre passou pela criação de um Dockerfile. Ferramentas como o Visual Studio facilitam esse processo com algumas opções prontas:

• O menu Add → Container Support.
• A escolha do sistema operacional, normalmente Linux.
• A geração automática de um Dockerfile.

O Dockerfile gerado normalmente define a imagem base do runtime do .NET e as portas HTTP e HTTPS. Além disso, ele descreve o processo de build e publish e o comando de inicialização da aplicação.

Um Dockerfile típico de várias etapas para a nossa API ficaria parecido com este:

# Etapa de build com o SDK
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish TimeApi.csproj -c Release -o /app/publish

# Etapa final apenas com o runtime do ASP.NET Core
FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY --from=build /app/publish .
EXPOSE 8080
ENTRYPOINT ["dotnet", "TimeApi.dll"]

Essa abordagem funciona bem, especialmente em soluções com múltiplos projetos. Contudo, ela adiciona um arquivo extra para manter e uma complexidade desnecessária para projetos simples.

Além disso, o Dockerfile vira mais um ponto de possível divergência entre ambientes. Basta alguém atualizar a versão do .NET no projeto e esquecer de atualizar a imagem base para o problema aparecer.

Containers sem Dockerfile com dotnet publish

O SDK do .NET passou a oferecer suporte nativo à geração de imagens diretamente no processo de publicação. Ou seja, o próprio dotnet publish compila a aplicação, empacota o resultado e cria uma imagem de container válida.

Tudo isso acontece sem Dockerfile. Segundo a documentação oficial sobre como conteinerizar um app .NET com dotnet publish, o SDK cria a imagem sozinho, sem depender do Docker para isso.

Na prática, o Docker ou o Podman só são necessários se você quiser rodar a imagem localmente. Por padrão, porém, o SDK envia a imagem gerada para o runtime de containers local, por isso o Docker precisa estar em execução nesse caso.

# Publica a API como imagem de container Linux x64
dotnet publish --os linux --arch x64 /t:PublishContainer

docker images

<PropertyGroup>
  <!-- Nome da imagem gerada -->
  <ContainerRepository>time-api</ContainerRepository>
  <!-- Tags aplicadas à imagem -->
  <ContainerImageTags>1.0.0;latest</ContainerImageTags>
  <!-- Variante Alpine da imagem base, menor que a padrão -->
  <ContainerFamily>alpine</ContainerFamily>
</PropertyGroup>

# Gera a imagem como arquivo tar.gz, sem precisar de um daemon em execução
dotnet publish --os linux --arch x64 /t:PublishContainer \
  -p ContainerArchiveOutputPath=./images/time-api.tar.gz

<PropertyGroup>
  <!-- Os RIDs do container precisam fazer parte de RuntimeIdentifiers -->
  <RuntimeIdentifiers>linux-x64;linux-arm64</RuntimeIdentifiers>
  <ContainerRuntimeIdentifiers>linux-x64;linux-arm64</ContainerRuntimeIdentifiers>
</PropertyGroup>

Executando a imagem localmente

Depois de criada, a imagem funciona exatamente como qualquer outro container Docker. Você mapeia as portas e escolhe entre o modo interativo e o modo detached:

# Executa o container em segundo plano, mapeando a porta 8080
docker run -d -p 8080:8080 --name time-api time-api

# Testa o endpoint exposto pela API
curl http://localhost:8080/time

Lembre-se de que, a partir do .NET 8, a aplicação escuta na porta 8080 dentro do container. Por isso, mapear a porta 80 do container resulta em conexão recusada.

Ao iniciar o container e acessar o endpoint, a aplicação responde corretamente, o que confirma o sucesso do empacotamento. Ferramentas como o Docker Desktop também facilitam a visualização do container em execução, das portas expostas e do status da aplicação.

Se você ainda não tem o Docker configurado, o guia de instalação, configuração e primeiros passos com Docker cobre esse passo a passo.

Enviando containers sem Dockerfile para um registry

Gerar a imagem localmente é apenas parte do fluxo. Para executá-la em servidores externos, você precisa publicá-la em um container registry.

Existem diversas opções no mercado:

• Docker Hub.
• Azure Container Registry.
• Amazon ECR.
• GitHub Container Registry (GHCR).

Neste fluxo, utilizei o GitHub Container Registry. Ele oferece armazenamento gratuito para imagens públicas, uma cota gratuita para imagens privadas e integração nativa com os repositórios do GitHub.

Vale destacar que os containers sem Dockerfile seguem o mesmo padrão de qualquer imagem. Portanto, o SDK publica em qualquer registry compatível com a API HTTP V2 do Docker Registry.

# Lê o token de uma variável de ambiente e envia pela entrada padrão
echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin

# Publica definindo o nome da imagem e a origem do código
dotnet publish --os linux --arch x64 /t:PublishContainer \
  -p ContainerRepository=USERNAME/time-api \
  -p RepositoryUrl=https://github.com/USERNAME/time-api \
  -p PublishRepositoryUrl=true

<ItemGroup>
  <!-- Vincula a imagem ao repositório no GitHub -->
  <ContainerLabel Include="org.opencontainers.image.source" Value="https://github.com/USERNAME/time-api" />
</ItemGroup>

# Associa a imagem local ao namespace do GHCR com uma versão
docker tag USERNAME/time-api:latest ghcr.io/USERNAME/time-api:1.0.0

# Envia a imagem para o registry
docker push ghcr.io/USERNAME/time-api:1.0.0

Execução a partir do registry

Em qualquer ambiente com Docker instalado, como uma VPS, o processo se resume a dois comandos. Primeiro você baixa a imagem publicada e, em seguida, inicia o container:

# Baixa a imagem publicada no GHCR
docker pull ghcr.io/USERNAME/time-api:1.0.0

# Inicia o container em segundo plano
docker run -d -p 8080:8080 ghcr.io/USERNAME/time-api:1.0.0

Se a imagem for privada, faça o docker login no servidor antes do pull. Nesse caso, um token apenas com read:packages já resolve, o que reduz o risco caso o servidor seja comprometido.

Mesmo removendo completamente a imagem local, o Docker consegue baixá-la do registry e executá-la normalmente. Isso comprova a portabilidade do modelo de containers sem Dockerfile.

Vantagens dos containers sem Dockerfile

Depois de percorrer o fluxo inteiro, fica mais fácil enxergar os ganhos. O primeiro deles é a imagem base, porque o SDK escolhe a imagem correta a partir do TargetFramework do projeto.

Ou seja, quando você atualiza a versão do .NET no csproj, a imagem base acompanha a mudança. Com isso, aquele descompasso clássico entre o projeto e o Dockerfile simplesmente deixa de existir.

Outro ganho está na segurança. Como vimos, os containers sem Dockerfile rodam por padrão com o usuário app, sem privilégios de root, o que reduz o impacto de uma eventual falha na aplicação.

Além disso, a configuração mora no mesmo lugar que o restante do projeto. Nome, tags, labels e variáveis de ambiente ficam no csproj, versionados junto com o código e revisados no mesmo pull request.

Por fim, o mesmo comando funciona na sua máquina e no pipeline de integração contínua. Assim, você gera containers sem Dockerfile com um único dotnet publish, sem scripts extras para manter.

Quando containers sem Dockerfile não bastam

A publicação de containers sem Dockerfile resolve a maioria dos cenários de APIs e serviços. No entanto, alguns casos ainda pedem um Dockerfile tradicional.

• Pacotes do sistema operacional: se a aplicação depende de bibliotecas nativas, você precisa de comandos RUN.
• Builds complexos: soluções com etapas de build fora do .NET, como compilação de front-end, ficam mais claras no Dockerfile.
• Padrões corporativos: algumas empresas exigem Dockerfiles revisados e imagens base próprias em todos os projetos.

Mesmo nesses casos, existe um meio-termo. Você pode criar uma imagem base customizada com as dependências e apontá-la na propriedade ContainerBaseImage, mantendo a publicação pelo SDK.

Conclusão

A possibilidade de publicar aplicações .NET como containers sem Dockerfile representa uma evolução significativa na experiência de desenvolvimento e distribuição. Com ela, você reduz a complexidade e mantém menos arquivos no repositório.

Além disso, o processo de publicação fica padronizado e integrado diretamente ao SDK do .NET. Para aplicações simples e médias, especialmente APIs e serviços, essa estratégia se mostra extremamente eficiente.

Em cenários mais complexos, o Dockerfile ainda pode ser necessário, mas deixa de ser um requisito padrão. Esse modelo também abre caminho para estratégias ainda mais interessantes, como a auto-hospedagem de aplicações .NET em VPSs, que aprofunda o controle sobre custos e infraestrutura.

FAQ

Preciso ter o Docker instalado para gerar a imagem?

Não para gerar, porque o SDK do .NET cria a imagem sozinho. O Docker ou o Podman só são necessários para executar a imagem localmente ou quando o destino é o runtime local.

Qual versão do .NET suporta containers sem Dockerfile?

O recurso surgiu no SDK 7.0.100 e ficou integrado ao SDK a partir do .NET 8. Nas versões atuais, basta usar o alvo PublishContainer no dotnet publish.

Por que minha API não responde na porta 80 dentro do container?

A partir do .NET 8, as imagens do ASP.NET Core escutam na porta 8080. Mapeie a porta 8080 do container ou defina a variável ASPNETCORE_HTTP_PORTS.

Como vincular a imagem ao repositório no GitHub?

Adicione o label org.opencontainers.image.source com a URL do repositório. Você pode fazer isso com PublishRepositoryUrl ou com um item ContainerLabel no csproj.

Consigo instalar pacotes do sistema na imagem gerada pelo SDK?

Não diretamente, porque o SDK não executa comandos RUN. A alternativa é usar uma imagem base customizada em ContainerBaseImage ou voltar ao Dockerfile.