Boot2Docker Deployment and Usage Guide

DEPRECATION WARNING: Boot2Docker is officially deprecated and unmaintained. It is recommended that users transition to Docker Desktop (with WSL2 backend for Windows 10 Home). This guide is provided for legacy maintenance only.

1. Prerequisites

System Requirements

• Hypervisor: VirtualBox, VMware, Parallels, or XenServer
• Management Tool: Docker Machine (included in Docker Toolbox)
• Network: Ability to forward TCP port 2376 (Docker TLS port)
• Storage: ~45MB for ISO download; additional virtual disk for persistence

Required Tools

• Docker Toolbox (includes Docker Machine, Boot2Docker VM, and VirtualBox)
• Or standalone Boot2Docker ISO for manual VM creation
• SSH client (for manual VM access)

2. Installation

Method A: Docker Toolbox (Recommended for Legacy Use)

Installs Docker Machine, Boot2Docker VM, and necessary tools:

1. Download Docker Toolbox from Docker documentation
2. Run the installer (includes VirtualBox and Docker Machine)
3. Create the default VM:

   docker-machine create --driver virtualbox default
   

Method B: Manual ISO Installation

For custom VM configurations or non-VirtualBox hypervisors:

1. Download the latest ISO from GitHub Releases
2. Create a new VM in your hypervisor with:
   • Type: Linux (64-bit)
   • RAM: Minimum 1GB recommended
   • Boot: Attach downloaded ISO
   • Storage: Add virtual disk (auto-mounted as boot2docker-data for persistence)
3. Boot the VM

Verification

docker-machine ls
docker-machine env default

The VM should show Running and Docker should be available on port 2376.

3. Configuration

Docker Daemon Customization

Edit /var/lib/boot2docker/profile on the persistent partition to customize daemon options:

docker-machine ssh default -t sudo vi /var/lib/boot2docker/profile

Add options such as:

EXTRA_ARGS="--default-ulimit core=-1"

Restart to apply:

docker-machine restart default

Secure Registry Certificates

Place certificates in /var/lib/boot2docker/certs/ (auto-loaded at boot) or manually:

docker-machine scp certfile default:ca.crt
docker-machine ssh default
sudo mv ~/ca.crt /etc/docker/certs.d/hostname/ca.crt
exit
docker-machine restart

Insecure Registry Configuration

For registries without HTTPS (Docker 1.3.1+):

docker-machine ssh default "echo $'EXTRA_ARGS=\"--insecure-registry <YOUR_INSECURE_HOST>\"' | sudo tee -a /var/lib/boot2docker/profile && sudo /etc/init.d/docker restart"

VPN Configuration (Cisco AnyConnect, etc.)

If encountering i/o timeout errors behind VPNs:

1. Open VirtualBox > Settings > Network > Adapter 1 (NAT) > Port Forwarding
2. Add rule:
   • Protocol: TCP
   • Host IP: 127.0.0.1
   • Host Port: 5555
   • Guest Port: 2376
3. Set environment variable:

   export DOCKER_HOST=tcp://127.0.0.1:5555
   

4. Build & Run

Building from Source

Clone the repository and build the ISO (requires Docker):

git clone https://github.com/boot2docker/boot2docker.git
cd boot2docker
# Build the ISO (requires Docker on host)
docker build -t boot2docker .
# Or use make if available
make

The resulting ISO will be available in the build output directory.

Running the VM

Via Docker Machine:

# Start VM
docker-machine start default

# Configure shell
eval $(docker-machine env default)

# Verify Docker connectivity
docker ps

Manual VM Management:

• Start: Use hypervisor GUI or VBoxManage startvm boot2docker-vm
• SSH Access:

  docker-machine ssh default
  

  Or manually (credentials):
  • User: docker
  • Password: tcuser

Boot Log Inspection: View startup logs at /boot.log (non-persistent between boots).

5. Deployment

Migration Path (Recommended)

Deploy new environments using Docker Desktop instead. For Windows 10 Home, use the WSL2 backend.

Legacy VM Provisioning

For maintaining existing Boot2Docker deployments:

1. Distribute ISO: Host the ISO on internal infrastructure for air-gapped environments
2. Automated Provisioning:

   docker-machine create \
     --driver virtualbox \
     --virtualbox-boot2docker-url http://internal-server/boot2docker.iso \
     production-vm
   

3. Persistence: Ensure virtual disks are backed up; they contain /var/lib/docker and SSH keys

Production Warning

Do not use Boot2Docker for production workloads. This tool is designed and tuned for development only.

6. Troubleshooting

VPN/Network Timeouts

Symptom: dial tcp 192.168.59.103:2376: i/o timeout Solution: Configure port forwarding (see Configuration section) or disable VPN split tunneling for VM subnet.

Registry Authentication Failures

Symptom: x509: certificate signed by unknown authority Solution: Copy CA certificate to /var/lib/boot2docker/certs/ and restart, or use insecure registry flag for internal testing.

Data Loss on Reboot

Symptom: Containers/images disappear after restart Solution: Ensure virtual disk is properly attached and formatted with label boot2docker-data. Only /var/lib/docker and /var/lib/boot2docker persist.

SSH Connection Issues

Symptom: Cannot access VM Solution:

• Default credentials: docker / tcuser
• Regenerate certificates: docker-machine regenerate-certs default
• Check VirtualBox network adapter is set to NAT or Bridged (not Host-Only if VPN is active)

Docker Daemon Won't Start

Symptom: Cannot connect to the Docker daemon Solution: Check /var/lib/boot2docker/profile for syntax errors in EXTRA_ARGS. Verify disk space on persistence partition.