Inception - Reproducible VirtualBox + Docker Infrastructure

A reproducible Infrastructure as Code (IaC) solution that runs Docker containers inside VirtualBox using Vagrant for consistent development environments.

🏗️ Architecture

This project provides a fully reproducible infrastructure stack:

• Host Machine: Your Linux system with VirtualBox
• Virtual Machine: Ubuntu 22.04 LTS managed by Vagrant
• Containers: Docker containers running your application stack
• Automation: Makefile commands for easy management

📋 Prerequisites

Required Software

• VirtualBox: For virtualization (uses your OS installation)
• Vagrant: For VM provisioning (auto-installed by setup script)
• Git: For version control

System Requirements

• RAM: 8GB+ recommended (VM uses 4GB)
• Disk Space: 20GB+ free space
• CPU: 2+ cores recommended

🚀 Quick Start

1. Clone and Setup

git clone <your-repo-url>
cd Inception
make setup  # Validates infrastructure requirements

2. Start Infrastructure

make vm-up    # Creates and starts VirtualBox VM
make vm-ssh   # Connect to the VM

3. Deploy Containers (inside VM)

# Inside the VM
cd /home/vagrant/inception
cp .env.template .env  # Edit as needed
make build            # Build Docker images
make up              # Start containers

4. Access Your Application

• Web: http://localhost:8080
• HTTPS: https://localhost:8443
• Database: localhost:3306

🛠️ Available Commands

Infrastructure Management

Command	Description
make setup	Validate and setup infrastructure requirements
make vm-up	Start and provision the VirtualBox VM
make vm-down	Stop the VirtualBox VM
make vm-ssh	SSH into the VirtualBox VM
make vm-status	Show VM status
make vm-destroy	Destroy the VM completely
make vm-provision	Re-run VM provisioning
make vm-info	Show VM connection information

Docker Management (Run inside VM)

Command	Description
make build	Build Docker containers
make up	Start Docker containers
make down	Stop Docker containers
make logs	Show container logs
make clean	Clean containers and images
make fclean	Full clean (includes VM destruction)
make re	Rebuild everything from scratch

Quick Actions

Command	Description
make deploy	Deploy full stack (VM + containers)
make dev-shell	Open development shell in VM

📁 Project Structure

Inception/
├── Vagrantfile              # VirtualBox VM configuration
├── setup-infra.sh          # Infrastructure validation script
├── Makefile                # Automation commands
├── README.md               # This file
└── srcs/                   # Docker application source
    ├── docker-compose.yml  # Container orchestration
    ├── .env.template       # Environment variables template
    └── requirements/       # Docker build contexts
        ├── nginx/          # Web server container
        ├── wordpress/      # Application container
        └── mariadb/        # Database container

🔧 Configuration

Environment Variables

Copy and customize the environment file:

cp srcs/.env.template srcs/.env
# Edit srcs/.env with your specific configuration

VM Configuration

The VirtualBox VM is configured with:

• OS: Ubuntu 22.04 LTS
• RAM: 4GB
• CPUs: 2 cores
• Network: Private network (192.168.56.10)
• Ports: 80→8080, 443→8443, 3306→3306

Docker Volumes

Persistent data is stored in:

• /home/vagrant/inception/data/wordpress - WordPress files
• /home/vagrant/inception/data/mariadb - Database files

🔄 Reproducibility Features

Infrastructure as Code

• Vagrantfile: Defines VM configuration
• Provisioning Scripts: Automated software installation
• Docker Compose: Container orchestration
• Environment Templates: Consistent configuration

Version Control Ready

• All configuration files are committed to Git
• No manual setup steps required
• Consistent environments across team members
• Easy rollback to previous configurations

Isolation Benefits

• Complete isolation from host system
• No Docker installation required on host
• No port conflicts with host services
• Easy cleanup and reset

🐛 Troubleshooting

VM Issues

# Check VM status
make vm-status

# Restart VM
make vm-down && make vm-up

# Re-provision VM
make vm-provision

# Complete reset
make vm-destroy && make vm-up

Docker Issues

# Inside VM - restart containers
make down && make up

# Rebuild containers
make clean && make build && make up

# Check logs
make logs

Network Issues

# Check VM network
vagrant ssh -c "ip addr show"

# Test port forwarding
curl http://localhost:8080

🔒 Security Considerations

• Change default passwords in .env file
• Use proper SSL certificates for production
• Restrict VM network access as needed
• Keep VirtualBox and Vagrant updated

🤝 Contributing

1. Make infrastructure changes in appropriate files
2. Test with make vm-destroy && make deploy
3. Update documentation as needed
4. Commit all configuration files

📚 Additional Resources