Installing Docker¶

Docker is required to run APHIDS CLI. This guide covers Docker installation on all supported platforms.

Why Docker?¶

APHIDS uses Docker to provide:

Isolated Environment: Security tools run in containers, not on your host
Consistency: Same environment across all platforms
Pre-configured Tools: All security tools pre-installed and ready
Easy Updates: Pull new container versions with one command
Security: Contained execution limits potential damage

Installation by Platform¶

Choose your operating system:

Ubuntu/DebianCentOS/RHELmacOSWindows (WSL2)

Ubuntu/Debian Installation¶

Method 1: Official Docker Repository (Recommended)¶

# Remove old versions (if any)
sudo apt remove docker docker-engine docker.io containerd runc

# Update package index
sudo apt update

# Install prerequisites
sudo apt install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.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 docker-compose-plugin

# Verify installation
sudo docker run hello-world

Method 2: Convenience Script¶

# Download and run Docker's convenience script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Verify installation
sudo docker run hello-world

Post-Installation Steps¶

# Add your user to the docker group (run Docker without sudo)
sudo usermod -aG docker $USER

# Apply group changes (or log out and back in)
newgrp docker

# Verify you can run Docker without sudo
docker run hello-world

# Enable Docker to start on boot
sudo systemctl enable docker.service
sudo systemctl enable containerd.service

CentOS/RHEL Installation¶

Remove Old Versions¶

sudo yum remove docker \
                docker-client \
                docker-client-latest \
                docker-common \
                docker-latest \
                docker-latest-logrotate \
                docker-logrotate \
                docker-engine

Install Using Repository¶

# 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 docker-compose-plugin

# Start Docker
sudo systemctl start docker

# Verify installation
sudo docker run hello-world

Post-Installation Steps¶

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

# Apply group changes
newgrp docker

# Enable Docker to start on boot
sudo systemctl enable docker.service
sudo systemctl enable containerd.service

macOS Installation¶

Method 1: Docker Desktop (Recommended)¶

Download Docker Desktop
Visit Docker Desktop for Mac
Download the appropriate version:
- Intel Chip: Docker Desktop for Mac (Intel)
- Apple Silicon: Docker Desktop for Mac (Apple Silicon)
Install Docker Desktop
Open the downloaded .dmg file
Drag Docker to Applications folder
Launch Docker from Applications
Follow the installation wizard
Configure Docker Desktop
Open Docker Desktop preferences
Recommended settings:
- CPUs: 4 or more
- Memory: 8 GB or more
- Disk: 20 GB or more

Verify Installation

docker --version
docker run hello-world

Method 2: Homebrew¶

# Install Docker via Homebrew
brew install --cask docker

# Launch Docker Desktop
open /Applications/Docker.app

# Verify installation
docker --version
docker run hello-world

Troubleshooting macOS¶

If Docker Desktop fails to start:

# Reset Docker Desktop
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/.docker

# Restart Docker Desktop

Windows with WSL2 Installation¶

Prerequisites¶

Windows 10 version 2004+ or Windows 11
WSL2 installed and configured
Ubuntu or Debian distribution in WSL2

Method 1: Docker Desktop (Recommended)¶

Download Docker Desktop
Visit Docker Desktop for Windows
Download Docker Desktop installer
Install Docker Desktop
Run the installer
Ensure "Use WSL 2 instead of Hyper-V" is checked
Complete installation
Restart your computer
Configure WSL2 Integration
Open Docker Desktop
Go to Settings → Resources → WSL Integration
Enable integration with your Ubuntu/Debian distribution
Click "Apply & Restart"

Verify in WSL2

# Open Ubuntu/Debian terminal
docker --version
docker run hello-world

Method 2: Docker Engine in WSL2 (Advanced)¶

Install Docker directly in WSL2 without Docker Desktop:

# In your WSL2 terminal (Ubuntu/Debian)

# Update packages
sudo apt update

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

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

# Start Docker service
sudo service docker start

# Verify installation
docker run hello-world

Auto-start Docker in WSL2¶

Add to your ~/.bashrc or ~/.zshrc:

# Start Docker daemon if not running
if ! pgrep -x dockerd > /dev/null; then
    sudo service docker start
fi

Verify Docker Installation¶

After installation, verify Docker is working correctly:

Check Docker Version¶

docker --version

Expected output:

Docker version 24.0.7, build afdd53b

Check Docker Info¶

docker info

Should display system information without errors.

Run Test Container¶

docker run hello-world

Expected output:

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

Check Docker Compose¶

docker compose version

Expected output:

Docker Compose version v2.23.0

Docker Configuration¶

Resource Allocation¶

Configure Docker resources based on your usage:

Docker Desktop (macOS/Windows)¶

Open Docker Desktop
Go to Settings → Resources
Configure:
CPUs: 4+ recommended
Memory: 8 GB+ recommended
Disk: 20 GB+ recommended
Swap: 2 GB recommended

Linux¶

Docker on Linux uses host resources directly. No configuration needed.

Storage Driver¶

Check your storage driver:

docker info | grep "Storage Driver"

Recommended drivers: - Linux: overlay2 - macOS: overlay2 - Windows: overlay2

Network Configuration¶

Verify Docker networks:

docker network ls

Should show default networks:

NETWORK ID     NAME      DRIVER    SCOPE
xxxxxxxxxxxx   bridge    bridge    local
xxxxxxxxxxxx   host      host      local
xxxxxxxxxxxx   none      null      local

Post-Installation Best Practices¶

1. Run Docker Without sudo (Linux)¶

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

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

# Test
docker run hello-world

2. Enable Docker on Boot¶

# Linux
sudo systemctl enable docker.service
sudo systemctl enable containerd.service

# macOS/Windows
# Docker Desktop starts automatically

3. Configure Docker Daemon¶

Create or edit /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2"
}

Restart Docker:

sudo systemctl restart docker

4. Set Up Docker Logging¶

# View Docker logs
sudo journalctl -u docker.service

# Follow Docker logs
sudo journalctl -fu docker.service

Troubleshooting¶

Docker Daemon Not Running¶

# Check Docker status
sudo systemctl status docker

# Start Docker
sudo systemctl start docker

# If it fails, check logs
sudo journalctl -u docker.service -n 50

Permission Denied¶

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

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

Cannot Connect to Docker Daemon¶

# Check if Docker is running
ps aux | grep docker

# Start Docker
sudo systemctl start docker

# On macOS/Windows, ensure Docker Desktop is running

Port Already in Use¶

# Find what's using the port
sudo lsof -i :PORT_NUMBER

# Stop the conflicting service or use a different port

Disk Space Issues¶

# Check Docker disk usage
docker system df

# Clean up unused resources
docker system prune -a

# Remove specific items
docker image prune -a
docker container prune
docker volume prune
docker network prune

WSL2 Integration Issues (Windows)¶

# Restart WSL
wsl --shutdown

# Restart Docker Desktop

# Re-enable WSL integration in Docker Desktop settings

Performance Optimization¶

Linux¶

# Use overlay2 storage driver (usually default)
# Enable user namespaces for better security
echo "user.max_user_namespaces=15000" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

macOS¶

Allocate more resources in Docker Desktop
Use VirtioFS for better file sharing performance
Store projects in Docker volumes, not bind mounts

Windows (WSL2)¶

Store projects in WSL2 filesystem (/home/user/), not Windows (/mnt/c/)
Allocate sufficient resources to WSL2 in .wslconfig
Use Docker volumes instead of bind mounts when possible

Security Considerations¶

1. Keep Docker Updated¶

# Check for updates regularly
sudo apt update && sudo apt upgrade docker-ce

# Or use Docker Desktop's built-in updater

2. Use Official Images¶

# Always pull from official sources
docker pull ghcr.io/darksidesecurity/aphids:latest

3. Scan Images for Vulnerabilities¶

# Use Docker Scout (built-in)
docker scout cves IMAGE_NAME

4. Limit Container Resources¶

# Run containers with resource limits
docker run --memory="4g" --cpus="2" IMAGE_NAME

Next Steps¶

Docker is now installed and configured! Proceed to:

Installing APHIDS CLI - Install the CLI tool
Pulling the Container - Download the APHIDS container
Verification - Verify your complete installation

Docker installed successfully?

Install APHIDS CLI →