Vagrant Operations Guide¶

This guide outlines the common Vagrant operations for managing Ubuntu Docker development environments.

🚀 Getting Started¶

`Makefile` Commands¶

Makefile

.PHONY: all clean test \
	vagrant-up vagrant-ssh \
	vagrant-package-ubuntu2404 \
	vagrant-ssh-config \
	vagrant-status \
	vagrant-add-box vagrant-list-boxes \


# Placeholder targets to satisfy checkmake
all: vagrant-up
	@echo "✅ Environment fully provisioned"

clean:
	@echo "🧹 Destroying Vagrant environment..."
	vagrant destroy -f

test: vagrant-up
	@echo "🔧 Validate Vagrantfile..."
	vagrant validate

# Vagrant Operations Makefile
# For Ubuntu Docker Development Environment

# Start the Vagrant environment with provisioning
vagrant-up:
	@echo "🚀 Starting Vagrant environment with provisioning..."
	vagrant up --color --provision

# Connect to the Vagrant VM via SSH
vagrant-ssh:
	@echo "🔑 Connecting to Vagrant VM via SSH..."
	vagrant ssh

# Display SSH configuration for the VM
vagrant-ssh-config:
	@echo "📋 Displaying SSH configuration..."
	vagrant ssh-config

# Check status of all Vagrant VMs
vagrant-status:
	@echo "📊 Checking Vagrant VM status..."
	vagrant status

# Package Ubuntu 24.04 Docker VM
vagrant-package-ubuntu2404:
	@echo "📦 Packaging vbox-docker-ubuntu2404 VM..."
	vagrant package --base vbox-docker-ubuntu2404 \
			--output vbox-docker-ubuntu2404 \
			--vagrantfile "./Vagrantfile"

# Add packaged box to Vagrant
vagrant-add-box:
	@echo "➕ Adding packaged box to Vagrant..."
	vagrant box add --name vbox-docker-ubuntu2404 ./vbox-docker-ubuntu2404

# List all Vagrant boxes with details
vagrant-list-boxes:
	@echo "📋 Listing all Vagrant boxes..."
	vagrant box list -i

bash scripts `base_provision.sh`¶

Bash

#!/bin/bash
#
# Development Environment Setup Script for Ubuntu 24.04 (Noble)
# For use with Vagrant
# Following official Docker installation guide:
# https://docs.docker.com/engine/install/ubuntu/

# Error handling
set -e
trap 'echo "Error occurred at line $LINENO. Command: $BASH_COMMAND"' ERR

# Log function
log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"
}

log "Beginning setup for Ubuntu 24.04 development environment"

# Update and upgrade system
log "Updating package repositories"
sudo apt-get update
log "Upgrading existing packages"
sudo DEBIAN_FRONTEND=noninteractive apt-get upgrade -y

# Install development tools
log "Installing development tools and libraries"
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
    linux-headers-$(uname -r) \
    build-essential \
    dkms \
    tree \
    gcc \
    make \
    automake \
    cmake \
    libssl-dev \
    libnghttp2-dev

# Install Docker prerequisites
log "Installing Docker prerequisites"
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
    ca-certificates \
    curl \
    gnupg

# Add Docker's official GPG key (official method)
log "Adding Docker's official GPG key"
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
    -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

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

# Update apt repositories with Docker repo
log "Updating package lists with Docker repository"
sudo apt-get update

# Install Docker packages (official method)
log "Installing Docker Engine and related tools"
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
    docker-ce \
    docker-ce-cli \
    containerd.io \
    docker-buildx-plugin \
    docker-compose-plugin

# Configure Docker for Vagrant user
log "Configuring Docker user permissions"
sudo groupadd docker 2>/dev/null || true

# In Vagrant, use 'vagrant' user, otherwise use current user
if id vagrant &>/dev/null; then
    DOCKER_USER="vagrant"
else
    DOCKER_USER=$USER
fi

log "Adding user '$DOCKER_USER' to docker group"
sudo usermod -aG docker $DOCKER_USER

# Start and enable Docker service
log "Enabling and starting Docker service"
sudo systemctl enable docker
sudo systemctl start docker

# Verify Docker installation
log "Verifying Docker installation"
if sudo docker run --rm hello-world > /dev/null 2>&1; then
    log "Docker installation verified successfully"
else
    log "WARNING: Docker verification failed."
    log "Please check Docker installation manually."
fi

log "Installation complete!"
log "You may need to log out and back in for Docker group changes to" \
    " take effect."
log "Alternatively, run 'newgrp docker' to apply group changes"
log "in current session."

Base Vagrantfile `Vagrantfile`¶

Ruby

# -*- mode: ruby -*-
# vi: set ft=ruby :

# All Vagrant configuration is done below. The "2" in Vagrant.configure
# configures the configuration version (we support older styles for
# backwards compatibility). Please don't change it unless you know what
# you're doing.
Vagrant.configure("2") do |config|
    # Specify the base box to use - Ubuntu 24.04 from alvistack provider
    config.vm.box = "alvistack/ubuntu-24.04"
    # Pin to a specific box version for consistency and reproducibility
    config.vm.box_version = "20250313.1.1"
    # Disable automatic key insertion - useful for consistent multi-VM environments
    config.ssh.insert_key = false
    # Prevent Vagrant from checking for box updates to speed up startup
    config.vm.box_check_update = false

    # Configure VirtualBox-specific settings
    config.vm.provider "virtualbox" do |v|
      # Set a descriptive VM name in the VirtualBox GUI
      v.name = 'vbox-docker-ubuntu2404'
      # Skip guest additions check to speed up boot time
      v.check_guest_additions = false
    end

    # Run initial system update
    config.vm.provision "shell",
      inline: "sudo apt-get update"

    # Execute the main provisioning script
    config.vm.provision "shell",
      path: "./scripts/base_provision.sh",
      privileged: true  # Run as root (sudo)

  end

go to `base_vm` directory¶

Bash

cd base_vm

Start the Vagrant Environment¶

Launch the VM with provisioning enabled and colored output:

Bash

vagrant up --color --provisionv

First Run

The first run will take longer as it downloads the base box and runs all provisioning scripts.

Connect to the VM¶

SSH into the running Vagrant VM:

Bash

vagrant ssh

📊 VM Management¶

Check VM Status¶

View the status of all Vagrant VMs in the current directory:

Bash

vagrant status

View SSH Configuration¶

Display the SSH configuration for connecting to the VM:

Bash

vagrant ssh-config

External SSH Clients

You can use this configuration with external SSH clients like PuTTY or in your SSH config file.

📦 Packaging & Distribution¶

Package Ubuntu 24.04 Docker VM¶

Package the Ubuntu 24.04 version of the Docker VM:

Bash

vagrant package --base vbox-docker-ubuntu2404 \
    --output vbox-docker-ubuntu2404 \
    --vagrantfile "./base.Vagrantfile"

VM Must Exist

Ensure the VM exists in VirtualBox with the exact name specified in the --base parameter.

Add Box to Vagrant¶

Add the packaged box to your local Vagrant box repository:

Bash

vagrant box add --name vbox-docker-ubuntu2404 ./vbox-docker-ubuntu2404

List Available Boxes¶

View all Vagrant boxes with detailed information:

Bash

vagrant box list -i

🔄 Base Box Creation Workflow¶

Step-by-Step Commands

Follow these commands sequentially to create and manage your Vagrant base box:

Navigate to base VM directory
Bash
```
cd base_vm
```
Initialize and provision VM
Bash
```
vagrant up --color --provision
```

Package VM for distribution

Bash

vagrant package --base vbox-docker-ubuntu2404 \
    --output vbox-docker-ubuntu2404 \
    --vagrantfile "./Vagrantfile"

Add to local box repository

Bash

vagrant box add --name vbox-docker-ubuntu2404 ./vbox-docker-ubuntu2404

Verify installation
Bash
```
vagrant box list -i
```

Box Creation

This workflow creates a reusable base box that can be shared across your development team.

Vagrant Operations Guide¶

🚀 Getting Started¶

Makefile Commands¶

bash scripts base_provision.sh¶

Base Vagrantfile Vagrantfile¶

go to base_vm directory¶

Start the Vagrant Environment¶

Connect to the VM¶

📊 VM Management¶

Check VM Status¶

View SSH Configuration¶

📦 Packaging & Distribution¶

Package Ubuntu 24.04 Docker VM¶

Add Box to Vagrant¶

List Available Boxes¶

🔄 Base Box Creation Workflow¶

`Makefile` Commands¶

bash scripts `base_provision.sh`¶

Base Vagrantfile `Vagrantfile`¶

go to `base_vm` directory¶