Chapter 2: Installation and Environment Setup

Learning Objectives

By the end of this chapter, you will be able to: - Identify system requirements for ContainerLab - Install Docker and ContainerLab on different operating systems - Configure the development environment - Troubleshoot common installation issues - Verify the installation and run basic tests

System Requirements

Minimum Requirements

Component Requirement
Operating System Linux (Ubuntu 18.04+, CentOS 7+, RHEL 7+), macOS 10.15+, Windows 10/11 with WSL2
CPU 2 cores (4+ recommended)
RAM 4GB (8GB+ recommended)
Storage 20GB free space (50GB+ recommended)
Network Internet connection for image downloads

Platform-Specific Considerations

macOS

  • Docker Desktop required
  • Good performance with Apple Silicon
  • Some limitations with nested virtualization
  • Resource sharing considerations

Windows

  • WSL2 required for optimal performance
  • Docker Desktop with WSL2 backend
  • Additional complexity in setup
  • Potential performance overhead

Prerequisites Installation

Installing Docker

Linux (Ubuntu/Debian)

# Update package index
sudo apt update

# Install required packages
sudo apt install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

# Add user to docker group
sudo usermod -aG docker $USER

# Start and enable Docker service
sudo systemctl start docker
sudo systemctl enable docker

Linux (CentOS/RHEL)

# Install required packages
sudo yum install -y yum-utils

# Add Docker repository
sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

# Install Docker Engine
sudo yum install -y docker-ce docker-ce-cli containerd.io

# Start and enable Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group
sudo usermod -aG docker $USER

macOS

# Install Docker Desktop using Homebrew
brew install --cask docker

# Or download from Docker website
# https://docs.docker.com/desktop/mac/install/

# Start Docker Desktop application
open /Applications/Docker.app

Windows (WSL2)

# Enable WSL2 feature
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Restart computer and set WSL2 as default
wsl --set-default-version 2

# Install Ubuntu from Microsoft Store
# Then install Docker Desktop for Windows with WSL2 backend

Verify Docker Installation

# Check Docker version
docker --version

# Test Docker functionality
docker run hello-world

# Check Docker system info
docker system info

ContainerLab Installation

Method 2: Package Manager Installation

Using Homebrew (macOS/Linux)

# Add ContainerLab tap
brew tap srl-labs/containerlab

# Install ContainerLab
brew install containerlab

Using APT (Ubuntu/Debian)

# Add repository key
curl -sL https://containerlab.dev/setup | sudo bash

# Install ContainerLab
sudo apt update
sudo apt install containerlab

Method 3: Container Installation

# Create alias for containerized version
alias containerlab='docker run --rm -it --privileged \
    --network host \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /etc/hosts:/etc/hosts \
    -v $(pwd):$(pwd) \
    -w $(pwd) \
    ghcr.io/srl-labs/containerlab'

Environment Configuration

Setting Up Working Directory

# Create ContainerLab workspace
mkdir -p ~/containerlab-labs
cd ~/containerlab-labs

# Create directory structure
mkdir -p {topologies,configs,scripts,docs}

# Set up environment variables
echo 'export CLAB_WORKDIR=~/containerlab-labs' >> ~/.bashrc
echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc
source ~/.bashrc

Configure Docker for ContainerLab

Increase Docker Resources

# Edit Docker daemon configuration
sudo nano /etc/docker/daemon.json

Add the following configuration:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 64000,
      "Soft": 64000
    }
  }
}

Restart Docker:

sudo systemctl restart docker

Network Configuration

Enable IP Forwarding

# Temporary enable
sudo sysctl net.ipv4.ip_forward=1
sudo sysctl net.ipv6.conf.all.forwarding=1

# Permanent enable
echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf
echo 'net.ipv6.conf.all.forwarding=1' | sudo tee -a /etc/sysctl.conf

Configure Bridge Networks

# Load bridge module
sudo modprobe bridge
echo 'bridge' | sudo tee -a /etc/modules

# Configure bridge settings
echo 'net.bridge.bridge-nf-call-iptables=0' | sudo tee -a /etc/sysctl.conf
echo 'net.bridge.bridge-nf-call-ip6tables=0' | sudo tee -a /etc/sysctl.conf

Verification and Testing

Verify ContainerLab Installation

# Check ContainerLab version
containerlab version

# Display help information
containerlab help

# Check available commands
containerlab --help

Expected output:

                           _                   _       _
                 _        (_)                 | |     | |
 ____ ___  ____ | |_  ____ _ ____   ____  ____| | ____| |__
|  _ \/ _ \|  _ \|  _)/ _  | |  _ \ / _  )/ ___) |/ _  |  _ \
| |_| | |_| | | | |_( ( | | | | | ( (/ /| |   | ( ( | | |_) )
|  __/ \___/|_| |_|\__)_||_|_|_| |_|\____)_|   |_|\_||_|____/
|_|

    version: 0.47.0
     commit: 8c54dd96
       date: 2023-11-15T10:30:45Z
     source: https://github.com/srl-labs/containerlab
 rel. notes: https://containerlab.dev/rn/0.47/

Create First Test Lab

Create a simple test topology:

# Create test topology file
cat > test-lab.yml << EOF
name: test-lab
topology:
  nodes:
    alpine1:
      kind: linux
      image: alpine:latest
    alpine2:
      kind: linux
      image: alpine:latest
  links:
    - endpoints: ["alpine1:eth1", "alpine2:eth1"]
EOF

Deploy and test the lab:

# Deploy the lab
containerlab deploy -t test-lab.yml

# Check lab status
containerlab inspect -t test-lab.yml

# Connect to a container
docker exec -it clab-test-lab-alpine1 sh

# Test connectivity (from within alpine1)
ping alpine2

# Exit container
exit

# Destroy the lab
containerlab destroy -t test-lab.yml

Troubleshooting Common Issues

Issue 1: Permission Denied

Problem: permission denied while trying to connect to the Docker daemon socket

Solution:

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and log back in, or run:
newgrp docker

# Verify group membership
groups $USER

Issue 2: ContainerLab Command Not Found

Problem: containerlab: command not found

Solution:

# Check if binary exists
ls -la /usr/local/bin/containerlab

# Add to PATH if needed
echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc
source ~/.bashrc

# Or create symlink
sudo ln -s /usr/local/bin/containerlab /usr/bin/containerlab

Issue 3: Docker Image Pull Failures

Problem: Cannot pull container images

Solution:

# Check Docker daemon status
sudo systemctl status docker

# Test Docker connectivity
docker run hello-world

# Check DNS resolution
nslookup registry-1.docker.io

# Configure Docker proxy if needed
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

Issue 4: Insufficient Resources

Problem: Containers fail to start due to resource constraints

Solution:

# Check system resources
free -h
df -h

# Monitor Docker resource usage
docker system df
docker stats

# Clean up unused resources
docker system prune -a

Issue 5: Network Connectivity Issues

Problem: Containers cannot communicate

Solution:

# Check IP forwarding
sysctl net.ipv4.ip_forward

# Verify bridge configuration
brctl show

# Check iptables rules
sudo iptables -L

# Reset Docker networks if needed
docker network prune

Development Environment Setup

Text Editor Configuration

VS Code Extensions

# Install useful extensions
code --install-extension ms-vscode.vscode-yaml
code --install-extension redhat.vscode-yaml
code --install-extension ms-python.python
code --install-extension ms-vscode.vscode-json

Vim Configuration

# Add YAML syntax highlighting
echo 'syntax on' >> ~/.vimrc
echo 'set tabstop=2' >> ~/.vimrc
echo 'set shiftwidth=2' >> ~/.vimrc
echo 'set expandtab' >> ~/.vimrc

Shell Aliases and Functions

# Add useful aliases
cat >> ~/.bashrc << 'EOF'
# ContainerLab aliases
alias clab='containerlab'
alias clab-deploy='containerlab deploy -t'
alias clab-destroy='containerlab destroy -t'
alias clab-inspect='containerlab inspect -t'

# Docker aliases
alias dps='docker ps'
alias dimg='docker images'
alias dlog='docker logs'

# ContainerLab functions
clab-connect() {
    docker exec -it "clab-$1-$2" bash 2>/dev/null || docker exec -it "clab-$1-$2" sh
}

clab-logs() {
    docker logs "clab-$1-$2"
}
EOF

source ~/.bashrc

Performance Optimization

System Tuning

# Increase file descriptor limits
echo '* soft nofile 65536' | sudo tee -a /etc/security/limits.conf
echo '* hard nofile 65536' | sudo tee -a /etc/security/limits.conf

# Optimize kernel parameters
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf
echo 'fs.file-max=2097152' | sudo tee -a /etc/sysctl.conf

# Apply changes
sudo sysctl -p

Docker Optimization

# Configure Docker storage driver
sudo nano /etc/docker/daemon.json

Add storage driver configuration:

{
  "storage-driver": "overlay2",
  "storage-opts": [
    "overlay2.override_kernel_check=true"
  ]
}

Installation Verification Checklist

Before proceeding to the next chapter, verify:

  • Docker is installed and running
  • ContainerLab is installed and accessible
  • User has proper permissions
  • Test lab deploys successfully
  • Network connectivity works between containers
  • Development environment is configured
  • System resources are adequate

Summary

Proper installation and environment setup are crucial for a smooth ContainerLab experience. This chapter covered the complete setup process across different operating systems, common troubleshooting scenarios, and performance optimization techniques. With your environment properly configured, you’re ready to start creating and managing network topologies.

In the next chapter, we’ll explore basic ContainerLab operations and learn how to create your first meaningful network lab.

Review Questions

  1. What are the minimum system requirements for running ContainerLab?
  2. Why is Docker required for ContainerLab operation?
  3. How do you verify that ContainerLab is properly installed?
  4. What are common causes of permission denied errors?
  5. How can you optimize system performance for ContainerLab?

Hands-on Exercises

Exercise 1: Installation Verification

  1. Install Docker and ContainerLab on your system
  2. Create and deploy the test lab from this chapter
  3. Verify connectivity between containers
  4. Document any issues encountered and their solutions

Exercise 2: Environment Customization

  1. Set up shell aliases for common ContainerLab commands
  2. Configure your preferred text editor for YAML editing
  3. Create a workspace directory structure
  4. Test the customizations with a simple lab deployment

Exercise 3: Troubleshooting Practice

  1. Intentionally break your Docker installation
  2. Practice the troubleshooting steps from this chapter
  3. Document the resolution process
  4. Restore full functionality

Additional Resources