Vagrant: Ambientes de Desenvolvimento Reproduzíveis

Vagrant é uma ferramenta para criar e gerenciar ambientes de máquinas virtuais em um único fluxo de trabalho. Se você já passou horas configurando um ambiente de desenvolvimento só para ouvir “funciona na minha máquina” de um colega de equipe, o Vagrant resolve exatamente esse problema. Você define todo o ambiente em um único arquivo — o Vagrantfile — e qualquer pessoa da equipe pode subir uma configuração idêntica com um único comando.

Este guia aborda a instalação do Vagrant, configuração do Vagrantfile, estratégias de provisionamento, redes, configurações multi-máquina e fluxos de trabalho que mantêm os ambientes de desenvolvimento consistentes em toda a equipe.

Pré-requisitos

• Processador 64-bit com virtualização por hardware habilitada (VT-x/AMD-V)
• Pelo menos 8 GB de RAM (4 GB para o host, 4 GB para as VMs)
• VirtualBox instalado (ou outro provider suportado)
• Experiência básica com linha de comando
• Git instalado (para compartilhar Vagrantfiles)

Instalando o Vagrant e Criando sua Primeira VM

Instale o Vagrant pela página oficial de downloads. Evite as versões dos gerenciadores de pacotes — costumam estar desatualizadas.

# Verificar instalação
vagrant --version

# Inicializar novo projeto com Ubuntu 22.04
mkdir my-project && cd my-project
vagrant init ubuntu/jammy64

# Iniciar a VM
vagrant up

# Conectar via SSH
vagrant ssh

O primeiro vagrant up baixa a imagem da box (um template de VM pré-construído) e cria a máquina virtual. Execuções subsequentes iniciam em segundos porque a imagem fica em cache localmente.

Comandos Essenciais do Vagrant

vagrant up          # Criar e iniciar a VM
vagrant ssh         # SSH para a VM em execução
vagrant halt        # Desligar a VM de forma segura
vagrant reload      # Reiniciar a VM (aplica alterações do Vagrantfile)
vagrant destroy     # Excluir a VM completamente
vagrant status      # Verificar estado da VM
vagrant provision   # Executar scripts de provisionamento novamente
vagrant snapshot save <name>   # Salvar estado da VM
vagrant snapshot restore <name> # Restaurar para estado salvo

Mergulho Fundo na Configuração do Vagrantfile

O Vagrantfile é código Ruby que define a configuração da sua VM. Aqui está um exemplo pronto para produção:

Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  config.vm.hostname = "dev-server"

  # Configuração de rede
  config.vm.network "private_network", ip: "192.168.56.10"
  config.vm.network "forwarded_port", guest: 80, host: 8080
  config.vm.network "forwarded_port", guest: 3000, host: 3000

  # Pasta sincronizada (host -> guest)
  config.vm.synced_folder "./src", "/var/www/app",
    owner: "www-data", group: "www-data"

  # Configurações específicas do provider
  config.vm.provider "virtualbox" do |vb|
    vb.memory = "2048"
    vb.cpus = 2
    vb.name = "dev-server"
    # Habilitar virtualização aninhada
    vb.customize ["modifyvm", :id, "--nested-hw-virt", "on"]
  end

  # Provisionamento com shell
  config.vm.provision "shell", inline: <<-SHELL
    apt-get update
    apt-get install -y nginx nodejs npm
    systemctl enable nginx
  SHELL
end

Opções de Rede

O Vagrant suporta três modos de rede:

Modo	Caso de Uso	Acesso
Forwarded Port	Expor portas específicas do guest para o host	localhost:8080 → guest:80
Private Network	Comunicação VM-a-VM em rede isolada do host	192.168.56.10 a partir do host e outras VMs
Public Network	Bridge para a rede física	VM obtém um IP da LAN, acessível por outras máquinas

Para desenvolvimento, as redes privadas são a escolha mais segura. Elas permitem comunicação entre VMs sem expor serviços para a rede mais ampla.

Estratégias de Provisionamento

O Vagrant suporta múltiplos métodos de provisionamento. Escolha com base nas ferramentas da sua equipe:

Provisioner Shell (Simples)

config.vm.provision "shell", path: "scripts/setup.sh"

Provisioner Ansible (Recomendado para Equipes)

config.vm.provision "ansible" do |ansible|
  ansible.playbook = "provisioning/playbook.yml"
  ansible.inventory_path = "provisioning/inventory"
  ansible.become = true
end

Provisioner Docker

config.vm.provision "docker" do |d|
  d.pull_images "nginx"
  d.pull_images "postgres:15"
  d.run "nginx", args: "-p 80:80"
end

Cenário real: Você tem uma equipe de 8 desenvolvedores trabalhando em uma aplicação web que requer PostgreSQL, Redis, Nginx e Node.js. Em vez de cada desenvolvedor instalar tudo manualmente (e acabar com versões diferentes), você cria um Vagrantfile com provisionamento Ansible. Um novo desenvolvedor clona o repositório, executa vagrant up e tem um ambiente funcional em 10 minutos. Quando você atualiza o PostgreSQL do 14 para o 15, basta atualizar o playbook — e todos recebem a mudança no próximo vagrant provision.

Ambientes Multi-Máquina

O Vagrant brilha na simulação de arquiteturas de produção localmente. Defina múltiplas VMs em um único Vagrantfile:

Vagrant.configure("2") do |config|
  # Servidor web
  config.vm.define "web" do |web|
    web.vm.box = "ubuntu/jammy64"
    web.vm.hostname = "web-server"
    web.vm.network "private_network", ip: "192.168.56.10"
    web.vm.provider "virtualbox" do |vb|
      vb.memory = "1024"
    end
    web.vm.provision "shell", inline: <<-SHELL
      apt-get update && apt-get install -y nginx
    SHELL
  end

  # Servidor de banco de dados
  config.vm.define "db" do |db|
    db.vm.box = "ubuntu/jammy64"
    db.vm.hostname = "db-server"
    db.vm.network "private_network", ip: "192.168.56.11"
    db.vm.provider "virtualbox" do |vb|
      vb.memory = "2048"
    end
    db.vm.provision "shell", inline: <<-SHELL
      apt-get update && apt-get install -y postgresql
    SHELL
  end

  # Servidor de cache
  config.vm.define "cache" do |cache|
    cache.vm.box = "ubuntu/jammy64"
    cache.vm.hostname = "cache-server"
    cache.vm.network "private_network", ip: "192.168.56.12"
    cache.vm.provision "shell", inline: <<-SHELL
      apt-get update && apt-get install -y redis-server
      sed -i 's/bind 127.0.0.1/bind 0.0.0.0/' /etc/redis/redis.conf
      systemctl restart redis
    SHELL
  end
end

Inicie máquinas específicas ou todas de uma vez:

vagrant up web      # Iniciar apenas o servidor web
vagrant up          # Iniciar todas as máquinas
vagrant ssh db      # SSH para o servidor de banco de dados

Vagrant vs Alternativas: Comparação

Recurso	Vagrant	Docker	Multipass	Nix/devenv
Isolamento	VM completa (SO completo)	Container (kernel compartilhado)	VM leve	Nível de processo
Tempo de Inicialização	30-120 segundos	1-5 segundos	10-30 segundos	Instantâneo
Uso de Recursos	Alto (SO completo por VM)	Baixo (kernel compartilhado)	Médio	Mínimo
Multi-SO	Sim (qualquer SO em qualquer host)	Apenas containers Linux*	Apenas Ubuntu	Linux/macOS
Provisionamento	Shell, Ansible, Chef, Puppet	Dockerfile	Cloud-init	Expressões Nix
Simulação de Rede	Excelente (multi-máquina)	Bom (redes Docker)	Básico	N/A
Paridade com Produção	Alta	Muito alta	Média	Baixa
Curva de Aprendizado	Baixa	Média	Baixa	Alta

*O Docker Desktop executa uma VM Linux no macOS/Windows, então os containers ainda são Linux.

Quando escolher Vagrant: Testes com SO completo, arquiteturas multi-máquina, desenvolvimento cross-platform Windows/Linux ou quando sua produção roda em VMs e não em containers.

Armadilhas e Casos Especiais

• Desempenho das pastas sincronizadas no macOS/Windows: As pastas compartilhadas do VirtualBox são notoriamente lentas para bases de código grandes. Use NFS (type: "nfs") no macOS/Linux ou SMB no Windows. Para melhor desempenho, use o tipo rsync com vagrant rsync-auto.

• Fixar versão da box: Sempre fixe a versão da sua box no Vagrantfile (config.vm.box_version = "20231215.0.0"). Boxes sem versão fixada se atualizam automaticamente e podem quebrar os scripts de provisionamento.

• Alocação de memória: O VirtualBox reserva memória na inicialização, não sob demanda. Se você alocar 4 GB para uma VM que fica ociosa com 512 MB, ainda perde 4 GB do host. Dimensione as VMs de forma conservadora.

• Conflitos de porta: Se a porta 8080 já estiver em uso no host, vagrant up falha. Use auto_correct: true nas portas redirecionadas para deixar o Vagrant escolher uma porta disponível automaticamente.

• Vagrant e WSL2: Executar o Vagrant dentro do WSL2 requer configuração extra. Defina VAGRANT_WSL_ENABLE_WINDOWS_ACCESS=1 e certifique-se de que o VirtualBox está instalado no Windows, não dentro do WSL.

• Exportações NFS obsoletas: No macOS, um vagrant destroy mal-sucedido pode deixar exportações NFS obsoletas em /etc/exports. Limpe com sudo sed -i '' '/# VAGRANT/d' /etc/exports.

Solução de Problemas

Problema	Causa	Solução
vagrant up trava em “Waiting for machine to boot”	VT-x/AMD-V desabilitado na BIOS	Habilitar virtualização nas configurações da BIOS
Timeout na conexão SSH	Configuração de rede incorreta	Verificar config.vm.network, tentar vagrant reload
Pasta sincronizada não atualiza	VirtualBox Guest Additions desatualizado	Instalar o plugin vagrant-vbguest: vagrant plugin install vagrant-vbguest
”The box could not be found”	Nome da box com erro de digitação ou box privada	Verificar o nome da box no Vagrant Cloud
Provisionamento falha no meio da execução	Erro no script ou dependência ausente	Corrigir o script e executar vagrant provision (scripts idempotentes ajudam)

Resumo

• Vagrant cria ambientes de desenvolvimento reproduzíveis definidos em um único Vagrantfile, eliminando os problemas de “funciona na minha máquina”
• Provisionamento com shell scripts, Ansible ou Docker automatiza toda a instalação de software dentro das VMs
• Configurações multi-máquina simulam arquiteturas de produção localmente com servidores web, banco de dados e cache separados
• Redes privadas fornecem comunicação segura entre VMs sem expor serviços externamente
• Fixe as versões das boxes e use pastas sincronizadas via NFS para evitar as duas frustrações mais comuns com o Vagrant
• Escolha o Vagrant em vez do Docker quando precisar de isolamento completo de SO, testes multi-SO ou paridade com produção baseada em VMs

Artigos Relacionados

• Docker Compose: A Practical Guide for System Administrators
• How to Install Docker on Ubuntu 22.04 and 24.04
• Introduction to Terraform: Infrastructure as Code for Beginners
• Ansible: Automate Server Configuration from Scratch
• Kubernetes Fundamentals: Deploy Your First Cluster