Dockerfile Ubuntu: Guia do Iniciante para Desenvolvedores

1. Introdução

O que são Docker e Dockerfile?

Nos últimos anos, o Docker ganhou rapidamente popularidade como forma de simplificar a configuração de ambientes de desenvolvimento e a implantação de aplicações. O Docker tem a capacidade única de empacotar uma aplicação e suas dependências em um único “contêiner”, que pode ser executado no mesmo ambiente em qualquer lugar
Para construir esse contêiner Docker, é necessário um plano chamado “Dockerfile”. Um Dockerfile é um arquivo de texto que especifica a imagem base do SO, o software a ser instalado, as definições de variáveis de ambiente e muito mais. Os desenvolvedores podem usar esse arquivo para construir automaticamente ambientes personalizados.

Motivos para Escolher o Ubuntu como Base

Ao criar um Dockerfile, o primeiro passo é especificar a imagem base do SO. Entre as várias opções, Ubuntu é particularmente popular. Ubuntu é uma distribuição Linux baseada em Debian conhecida pela sua facilidade de uso e pela flexibilidade de construir ambientes diversos graças ao seu extenso repositório de pacotes.
Um Dockerfile baseado em Ubuntu oferece as seguintes vantagens:

• Abundante documentação oficial e da comunidade, resultando em uma curva de aprendizado menor.
• Muitos pacotes e ferramentas podem ser instalados facilmente usando o APT (Advanced Package Tool).
• Imagens mínimas leves (como ubuntu:20.04, ubuntu:24.04) são fornecidas oficialmente.

Propósito e Público‑Alvo deste Artigo

Neste artigo, focaremos na palavra‑chave “Dockerfile Ubuntu” e forneceremos uma explicação de fácil compreensão para iniciantes sobre como criar Dockerfiles baseados em Ubuntu.
Especificamente, abordaremos de abrangente tudo, desde a estrutura básica de um Dockerfile até as etapas para realmente construir um ambiente Ubuntu, exemplos de instalação de ambientes de aplicação como Python e erros comuns com suas soluções.
Este artigo é recomendado para:

• Quem deseja criar um ambiente usando Dockerfile pela primeira vez.
• Quem quer criar um ambiente de desenvolvimento reproduzível no Ubuntu.
• Quem deseja aprofundar seus conhecimentos, inclusive como solucionar problemas.

2. Estrutura Básica de um Dockerfile

O que é um Dockerfile? Entendendo seu Papel

Um Dockerfile é como uma receita para criar uma imagem Docker. Especificamente, é um arquivo de texto que descreve qual SO base usar, quais softwares instalar e quais configurações aplicar.
Ao executar o comando docker build usando esse arquivo, você pode construir facilmente ambientes de desenvolvimento e execução de aplicações altamente reproduzíveis.
Benefícios de usar Dockerfile:

• Automação da configuração do ambiente (não é necessário reproduzir passos manuais).
• Elimina inconsistências de ambiente ao desenvolver com múltiplos membros da equipe.
• Fácil de integrar em pipelines CI/CD.

Instruções Básicas (Diretivas) Mais Usadas em Dockerfile

Um Dockerfile contém várias instruções (diretivas), sendo as seguintes as mais representativas. Combina‑as adequadamente para criar um Dockerfile baseado em Ubuntu.

Exemplo Minimalista de um Dockerfile Baseado em Ubuntu

Abaixo está um exemplo muito básico de um Dockerfile baseado em Ubuntu.

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y
    curl
    vim

CMD ["/bin/bash"]

Este Dockerfile está configurado para usar Ubuntu 24.04 como base, instalar duas utilidades (curl e vim) e, por fim, iniciar o shell bash.

Sobre a Seleção de Tags do Ubuntu

Imagens Docker do Ubuntu estão disponíveis no repositório oficial do Docker Hub. Enquanto especificar ubuntu:latest usará a versão mais recente, é recomendado fixar explicitamente uma versão.
Por exemplo:

• ubuntu:22.04 (LTS: Long Term Support, enfatiza estabilidade)
• ubuntu:24.04 (Candidato LTS mais recente, enfatiza recursos)

Considere se deve priorizar estabilidade ou novos recursos dependendo do seu objetivo.

3. Prática: Criando um Dockerfile Baseado em Ubuntu

Instalando Pacotes Necessários para o Ambiente Ubuntu

Quando você constrói um ambiente Ubuntu usando Dockerfile, frequentemente precisará instalar pacotes adicionais. Por exemplo, as seguintes utilidades são comumente usadas para configurar um ambiente de desenvolvimento:

• curl : Para buscar arquivos e verificar APIs.
• vim : Um editor de texto simples.
• git : Uma ferramenta de controle de versão.
• build-essential : Uma coleção de ferramentas básicas necessárias para compilar programas C/C++.

Para instalar esses pacotes em um Dockerfile, use a instrução RUN.

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y
    curl
    vim
    git
    build-essential

Ao executar apt-get update primeiro, você garante que as listas de pacotes mais recentes sejam obtidas antes da instalação.

Configurando Instalação Não Interativa

No Ubuntu, o apt-get install pode exigir entrada do usuário, mas operações interativas não são possíveis durante o processo de build do Docker. Portanto, é recomendado definir a variável de ambiente da seguinte forma para realizar a instalação em modo não interativo.

ENV DEBIAN_FRONTEND=noninteractive

Isso pulará prompts como “Configurações Regionais” que aparecem durante a configuração de pacotes, permitindo que a instalação prossiga de forma suave.

Reduzindo o Tamanho da Imagem Removendo Cache Desnecessário

Ao usar o APT, arquivos temporários baixados (cache) podem permanecer na imagem, tornando a imagem Docker final maior. Você pode reduzir o tamanho da imagem excluindo esse cache da seguinte forma:

RUN apt-get update && apt-get install -y
    curl
    vim
    && rm -rf /var/lib/apt/lists/*

Ao combinar múltiplos comandos em uma única declaração RUN como esta, você também pode evitar a criação de camadas desnecessárias.

Melhores Práticas: Organizando Seu Dockerfile

Em ambientes de desenvolvimento reais, as seguintes melhores práticas para escrever Dockerfiles são recomendadas:

• Combine instruções RUN o máximo possível para reduzir o número de camadas.
• Defina versões e configurações explicitamente usando ENV.
• Use comentários para declarar claramente o propósito de cada operação.
• Use rm e --no-install-recommends para evitar deixar arquivos desnecessários.

Exemplo:

RUN apt-get update && apt-get install -y --no-install-recommends
    curl
    git
    && rm -rf /var/lib/apt/lists/*

Fazendo isso, você pode construir um Dockerfile mais leve e manutenível.

4. Construindo e Verificando a Imagem Docker

Construindo uma Imagem Docker a Partir de um Dockerfile

Depois de escrever seu Dockerfile, o próximo passo é construir a imagem Docker. Isso é feito usando o comando docker build. Execute o seguinte comando no diretório onde seu Dockerfile está localizado:

docker build -t my-ubuntu-image .

• A opção -t é usada para dar um nome (tag) à imagem. Neste exemplo, estamos nomeando-a como my-ubuntu-image.
• O . refere-se ao diretório atual onde o Dockerfile está localizado.

Ao executar este comando, o Docker lerá sequencialmente as instruções no Dockerfile e construirá uma nova imagem de acordo.

Verificando a Imagem Docker Construída

Após a criação da imagem ser concluída, você pode verificá-la com o seguinte comando:

docker images

Isso exibirá uma lista de imagens Docker que existem localmente, e você pode verificar as seguintes informações:

• REPOSITORY (nome da imagem)
• TAG (tag)
• IMAGE ID (identificador único)
• CREATED (data e hora de criação)
• SIZE (tamanho)

Exemplo:

REPOSITORY         TAG       IMAGE ID       CREATED         SIZE
my-ubuntu-image    latest    abcd1234abcd    5 minutes ago   189MB

Isso confirma que a imagem que você criou foi registrada com sucesso.

Iniciando um Contêiner Docker e Verificando a Operação

Para verificar se a imagem criada funciona corretamente, vamos iniciar um contêiner Docker. Use o seguinte comando:

docker run -it my-ubuntu-image

• Especificar a opção -it permite iniciar um terminal em modo interativo.
• Se iniciar com sucesso, um prompt bash dentro do contêiner aparecerá, e você estará em um estado como se tivesse feito login em um ambiente Ubuntu.

Dentro do contêiner, você pode executar comandos como os seguintes para verificar se as ferramentas instaladas estão funcionando corretamente:

curl --version
vim --version

Se não houver problemas, o Dockerfile foi escrito com sucesso.

Limpando Imagens e Contêineres Desnecessários

À medida que você repete builds e experimentos, imagens e contêineres Docker desnecessários podem se acumular localmente. Recomenda‑se limpá‑los periodicamente usando comandos como os seguintes:

• Excluindo contêineres parados:

  docker container prune
  

• Excluindo imagens não utilizadas:

  docker image prune
  

• Excluindo todos os dados não utilizados (Cuidado!):

  docker system prune
  

Essas operações ajudam a economizar espaço em disco e prevenir problemas.

5. Aplicação: Construindo um Ambiente Python

Tornando o Python Utilizável em um Dockerfile Baseado em Ubuntu

Ao adicionar um ambiente de execução Python ao construir um ambiente Ubuntu usando Dockerfile, você pode suportar uma ampla gama de usos, como desenvolvimento, testes e aprendizado de máquina. Embora o Ubuntu possa ter o Python pré‑instalado, é prática comum construí‑lo explicitamente do ponto de vista de versionamento e gerenciamento de pacotes.

Como Instalar Python Usando apt

A maneira mais simples é instalar o Python usando pacotes APT. Veja um exemplo:

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y
    python3
    python3-pip
    && rm -rf /var/lib/apt/lists/*

Com esse método, você pode usar a versão estável do Python instalada no sistema (geralmente Python 3.10 ou 3.12, etc.). Além disso, pode adicionar pacotes Python usando o comando pip.

Gerenciando Versões do Python com pyenv

Se quiser usar uma versão específica do Python ou alternar entre várias versões, usar pyenv é conveniente.
Abaixo está um exemplo de uso do pyenv para instalar o Python 3.11.6 em um Dockerfile:

FROM ubuntu:24.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y
    git
    curl
    make
    build-essential
    libssl-dev
    zlib1g-dev
    libbz2-dev
    libreadline-dev
    libsqlite3-dev
    wget
    llvm
    libncurses5-dev
    libncursesw5-dev
    xz-utils
    tk-dev
    libffi-dev
    liblzma-dev
    && rm -rf /var/lib/apt/lists/*

# Install pyenv
RUN git clone [https://github.com/pyenv/pyenv.git](https://github.com/pyenv/pyenv.git) ~/.pyenv

ENV PYENV_ROOT="$HOME/.pyenv"
ENV PATH="$PYENV_ROOT/bin:$PATH"

RUN echo 'eval "$(pyenv init --path)"' >> ~/.bashrc

# Install a specific Python version
RUN pyenv install 3.11.6 && pyenv global 3.11.6

Isso permite construir e gerenciar seu ambiente Python de forma mais flexível.

Gerenciamento de Pacotes com requirements.txt

Em projetos reais, você costuma precisar de várias bibliotecas Python. O requirements.txt é usado para gerenciar essas dependências.
Primeiro, prepare um arquivo requirements.txt na raiz do seu projeto:

flask==2.3.2
requests>=2.25.1
pandas

Em seguida, descreva‑o no Dockerfile da seguinte forma:

COPY requirements.txt /app/requirements.txt
WORKDIR /app

RUN pip install --no-cache-dir -r requirements.txt

Isso permite instalar todas as bibliotecas necessárias de uma só vez, aumentando a reprodutibilidade do seu ambiente de desenvolvimento.

Boas Práticas

• Ao usar Python, criar um ambiente virtual com virtualenv ou venv pode ajudar a evitar conflitos de dependências.
• Você pode reduzir o tamanho da sua imagem Docker excluindo o cache (--no-cache-dir).
• Instalar a versão mais recente do pip com pip install --upgrade pip antes de instalar pacotes Python pode prevenir erros.

6. Problemas Comuns e Soluções

Erros de Permissão

Exemplo:

Permission denied

Isso ocorre quando o arquivo copiado não possui permissões de execução ou quando o proprietário do arquivo/usuário executando não é apropriado.

Soluções:

• Torne o arquivo executável:

  RUN chmod +x script.sh
  

• Altere o usuário se necessário:

  RUN chown root:root /path/to/file
  

Pacote Não Encontrado ou Não Pode Ser Instalado

Exemplo:

E: Unable to locate package xxx

Este erro ocorre quando apt-get update não foi executado ou quando o nome do pacote especificado está incorreto.

Soluções:

• Sempre execute apt-get update antes de install :

  RUN apt-get update && apt-get install -y curl
  

• Verifique o nome do pacote quanto a erros de digitação e certifique-se de que está correto.

Erros Relacionados à Rede

Exemplo:

Temporary failure resolving 'deb.debian.org'

Esse tipo de erro ocorre quando a resolução de DNS falha durante o processo de build.

Soluções:

• Reiniciar o daemon do Docker pode resolver o problema:

  sudo systemctl restart docker
  

• Revise as configurações de DNS do Docker (adicione especificações de DNS a /etc/docker/daemon.json ):

  {
    "dns": ["8.8.8.8", "8.8.4.4"]
  }
  

Build Permanece em um Estado Antigo Devido a Efeitos de Cache

O Docker usa um cache camada por camada para velocidade. Como resultado, mesmo se você modificar o Dockerfile, ele pode não ser construído como pretendido porque as camadas em cache estão sendo reutilizadas.

Solução:

• Reconstrua sem usar o cache:

  docker build --no-cache -t my-image .
  

Comando de Inicialização no Contêiner Falha ao Executar ou Sai Imediatamente

Causas:

• O comando especificado em CMD ou ENTRYPOINT está encontrando um erro.
• Mesmo se você especificar ["/bin/bash"] em CMD , ele sairá imediatamente se não for executado de forma interativa.

Soluções:

• Inicie o contêiner para depuração e verifique:

  docker run -it my-image /bin/bash
  

• Entenda a diferença entre CMD e ENTRYPOINT e use-os adequadamente para o seu propósito.

Ao experimentar esses problemas, suas habilidades de design de Dockerfile definitivamente melhorarão. Quando você encontrar um problema, leia calmamente a mensagem de erro e rastreie cuidadosamente qual camada ou instrução é a causa.

7. Conclusão

Reconfirmando Pontos Chave para Criar Dockerfiles Baseados em Ubuntu

Neste artigo, explicamos passo a passo, desde métodos básicos até aplicados, sobre como construir um ambiente Ubuntu usando Dockerfile. Vamos reiterar os pontos importantes aqui.

• Entender a estrutura básica de um Dockerfile é o primeiro passo. Você pode automatizar a configuração do ambiente combinando instruções como FROM , RUN , CMD , e ENV .
• Ubuntu é uma imagem base estável e altamente flexível. Seu repositório de pacotes rico, grande base de usuários e a disponibilidade de versões LTS a tornam adequada como base para ambientes de desenvolvimento.
• Você pode instalar ferramentas e bibliotecas necessárias através de gerenciamento de pacotes prático . Saber como usar apt-get , remover cache e realizar instalações não interativas são fundamentais.
• Construir ambientes práticos como Python também é possível com Dockerfile. Ferramentas como pyenv , pip , e requirements.txt permitem criar ambientes de desenvolvimento altamente reproduzíveis.
• Habilidades de solução de problemas levam diretamente a uma operação estável. Entender armadilhas comuns como permissões, problemas de rede e cache de build pode melhorar significativamente a eficiência de desenvolvimento.

Próximos Passos para Aprender Dockerfile

Ser capaz de lidar com Dockerfiles permite suportar uma ampla gama de usos, não apenas no desenvolvimento, mas também em testes e implantação em ambientes de produção. Para aprendizado futuro, seria benéfico prosseguir para os seguintes tópicos:

• Gerenciar configurações multi-contêiner usando Docker Compose .
• Integração com ferramentas CI/CD (GitHub Actions, GitLab CI, etc.) .
• Interoperação com ferramentas de orquestração de contêineres como Kubernetes .

8. FAQ (Perguntas Frequentes)

Q1. Qual versão do Ubuntu devo escolher no meu Dockerfile?

A1. Basicamente, se você priorizar estabilidade e suporte de longo prazo, é comum escolher uma versão LTS (Long Term Support). Por exemplo, ubuntu:22.04 e ubuntu:20.04 são usadas em muitos ambientes de desenvolvimento e podem ser usadas com confiança devido ao seu período de suporte de 5 anos. Por outro lado, se você quiser usar os pacotes e versões de linguagem mais recentes, você pode escolher uma versão mais nova como ubuntu:24.04, mas recomendamos testá-la previamente.

Q2. Por que eu recebo “Package not found” ao usar apt-get install?

A2. A razão mais comum é que você não executou apt-get update previamente. Se você tentar instalar sem atualizar a lista de pacotes, você receberá um erro porque o pacote correspondente não pode ser encontrado na lista desatualizada. Exemplo de uso correto:

RUN apt-get update && apt-get install -y curl

Além disso, tenha cuidado com erros de digitação nos nomes de pacotes e nomes de pacotes depreciados (por exemplo, python3 em vez de python).

Q3. Como eu defino variáveis de ambiente em um Dockerfile?

A3. Você define variáveis de ambiente usando a instrução ENV. Essa variável de ambiente será válida tanto durante a construção quanto no tempo de execução do contêiner. Exemplo:

ENV DEBIAN_FRONTEND=noninteractive

Essa é uma configuração típica usada para suprimir prompts interativos durante a instalação do APT. Ela também é usada para definir configurações de aplicativos e chaves de API dentro do Dockerfile.

Q4. Qual é a diferença entre CMD e ENTRYPOINT em um Dockerfile?

A4. Ambas especificam comandos a serem executados quando o contêiner inicia, mas há diferenças em seu uso e comportamento.

Exemplo:

CMD ["python3", "app.py"]
# vs
ENTRYPOINT ["python3"]
CMD ["app.py"]

No último caso, você pode passar o CMD como um argumento na forma de docker run my-image another_script.py.

Q5. Eu editei meu Dockerfile, mas as mudanças não são refletidas. Por quê?

A5. O Docker usa cache durante o processo de construção, então mesmo se você fizer pequenas mudanças no Dockerfile, camadas em cache podem ainda ser usadas. Solução:

docker build --no-cache -t my-image .

Isso executará uma nova construção sem usar o cache, e todas as mudanças serão refletidas.