Provision development environment

In the last tutorial, you set up your first Vagrant environment. In this tutorial, you will expand it by adding provisioning scripts to your Vagrantfile. These scripts will automate the setup of your environment, including installing software, configuring settings, and preparing the Terramino demo application—a containerized app that mimics real-world development workflows.

Provisioning ensures consistent configurations by automating repetitive setup tasks. It saves time, reduces errors, and provides a reliable foundation for development.

Update your Vagrantfile

First, create a script named install-dependencies.sh to install Docker and dependencies for the Terramino demo application.

# Install dependencies for Terramino demo app

# Update package list
apt-get update

# Install required packages
apt-get install -y ca-certificates curl gnupg git

# Add Docker's official GPG key
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker packages
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add vagrant user to docker group
usermod -aG docker vagrant

# Clone Terramino repository if it doesn't exist
if [ ! -d "/home/vagrant/terramino-go/.git" ]; then
  cd /home/vagrant
  rm -rf terramino-go
  git clone https://github.com/hashicorp-education/terramino-go.git
  cd terramino-go
  git checkout containerized
fi

# Create reload script
cat > /usr/local/bin/reload-terramino << 'EOF'
#!/bin/bash
cd /home/vagrant/terramino-go
docker compose down
docker compose build --no-cache
docker compose up -d
EOF

chmod +x /usr/local/bin/reload-terramino

# Add aliases
echo 'alias play="docker compose -f /home/vagrant/terramino-go/docker-compose.yml exec -it backend ./terramino-cli"' >> /home/vagrant/.bashrc
echo 'alias reload="sudo /usr/local/bin/reload-terramino"' >> /home/vagrant/.bashrc
# Source the updated bashrc
echo "source /home/vagrant/.bashrc" >> /home/vagrant/.bash_profile

Then, make the script executable.

$ chmod +x install-dependencies.sh

Update your Vagrantfile to include provisioning scripts. These scripts will set up Docker, install dependencies, and prepare the Terramino demo application. Replace your existing Vagrantfile with the following configuration.

Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp-education/ubuntu-24-04"
  config.vm.box_version = "0.1.0"

  # Install Docker and dependencies
  config.vm.provision "shell", name: "install-dependencies", path: "install-dependencies.sh"

  # Start Terramino (can be rerun with vagrant provision --provision-with start-terramino)
  config.vm.provision "shell", name: "start-terramino", inline: <<-SHELL
    cd /home/vagrant/terramino-go
    docker compose up -d
  SHELL

  # Restart Terramino (can be rerun with vagrant provision --provision-with restart-terramino)
  # For quick changes that doesn't require rebuilding (e.g. frontend changes)
  config.vm.provision "shell", name: "restart-terramino", run: "never", inline: <<-SHELL
    docker compose restart
  SHELL

  # Reload Terramino (can be rerun with vagrant provision --provision-with reload-terramino)
  # For changes that require rebuilding (e.g. backend changes)
  config.vm.provision "shell", name: "reload-terramino", run: "never", inline: <<-SHELL
    /usr/local/bin/reload-terramino
  SHELL
end

This Vagrantfile includes four provisioning scripts:

1. The install-dependencies script sets up Docker, installs required tools, and clones the Terramino repository.
2. The start-terramino script launches the Terramino demo application.
3. The restart-terramino script restarts the application without rebuilding it. This is useful if you are making frontend changes. This script includes the run: “never" option, meaning it will not run automatically during vagrant up or vagrant provision. Instead, you must explicitly run it using the --provisioning-with flag.
4. The reload-terramino script rebuilds and restarts the application. This is useful for backend changes. Like restart-terramino, it also requires explicit targeting.

We recommend making your provisioning scripts idempotent so they can run multiple times without errors or inconsistencies. For example, the install-dependencies script checks whether the Terramino directory exists before cloning it, avoiding redundant actions.

Run provisioning scripts

Recreate your virtual machine and apply all provisioning scripts. This command initializes the environment and executes all provisioning scripts defined in your Vagrantfile.

$ vagrant up

If the virtual machine already exists and you run vagrant up again, Vagrant will start the machine without running the provisioning scripts. If you modify your provisioning scripts or need to reapply them, use vagrant provision or --provision. This re-runs all provisioning scripts in your Vagrantfile to apply updates or fixes.

1. If the machine is already running, apply the provisioning scripts with vagrant provision.

   $ vagrant provision
   

2. If you want to force provisioning when you start the machine, apply the --provision flag.

   $ vagrant up --provision
   

Test the environment

Once Vagrant finishes provisioning the environment, connect to the virtual machine.

$ vagrant ssh

Inside the virtual machine, verify the Terramino backend is running.

$ curl localhost:8080
Terramino - HashiCorp Demo App
https://developer.hashicorp.com/

Use the play command to play the game.

$ play

Terramino will display the instructions. Press Enter to start the game and follow the instructions to interact with the app.

Terramino CLI
Controls:
← →   : Move left/right
↑     : Rotate
↓     : Soft drop
Space : Hard drop
q     : Quit

Press Enter to start...

Once you are done testing the demo application on the guest machine, exit the guest machine.

$ exit

Next steps

You have provisioned your Vagrant environment and tested the Terramino application. Vagrant also integrates with tools like Ansible, Chef, and Puppet for more complex setups. These integrations let you use common workflows in your environments in your Vagrant environments, ensuring your development environment is similar to your production one.

Continue to the next tutorial to learn how to sync the Vagrant environment with your host machine to share networking and folders between the machines.

For more information on topics covered in this tutorial, refer to the following documentation:

• Vagrant provisioning and cloud-init.
• Integration with third party tools like Ansible, Chef, and Puppet.