buque/docs/DOCKER_SETUP.md

Docker and Docker Compose Setup Guide

This guide will help you install Docker and Docker Compose on various operating systems.

Linux

Ubuntu/Debian

# Update package index
sudo apt-get update

# Install prerequisites
sudo apt-get 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

# Set up the stable 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-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

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

# Apply new group membership (or logout and login)
newgrp docker

# Verify installation
docker --version
docker compose version

Fedora/CentOS/RHEL

# Install prerequisites
sudo dnf -y install dnf-plugins-core

# Add Docker repository
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

# Install Docker
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

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

# Verify installation
docker --version
docker compose version

Arch Linux

# Install Docker
sudo pacman -S docker docker-compose

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

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

# Verify installation
docker --version
docker compose version

macOS

Using Homebrew

# Install Docker Desktop
brew install --cask docker

# Start Docker Desktop from Applications
# Or use: open -a Docker

# Verify installation
docker --version
docker compose version

Manual Installation

1. Download Docker Desktop for Mac from https://www.docker.com/products/docker-desktop
2. Open the .dmg file and drag Docker to Applications
3. Launch Docker from Applications
4. Docker icon will appear in the menu bar when running

Windows

Using WSL2 (Recommended)

1. Enable WSL2:

   wsl --install
   

2. Download and install Docker Desktop for Windows from https://www.docker.com/products/docker-desktop

3. During installation, ensure "Use WSL 2 instead of Hyper-V" is selected

4. After installation, open Docker Desktop settings:

   • Go to Settings > General
   • Ensure "Use the WSL 2 based engine" is checked
   • Go to Settings > Resources > WSL Integration
   • Enable integration with your WSL distributions

5. Verify installation in WSL:

   docker --version
   docker compose version
   

Verification

After installation, verify Docker is working:

# Check Docker version
docker --version

# Check Docker Compose version
docker compose version

# Run a test container
docker run hello-world

# Check Docker is running
docker ps

Post-Installation Steps

Linux: Run Docker without sudo

# Create docker group (usually already exists)
sudo groupadd docker

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

# Apply changes
newgrp docker

# Verify
docker run hello-world

Configure Docker to start on boot

# Linux (systemd)
sudo systemctl enable docker

# Check status
sudo systemctl status docker

Troubleshooting

Permission Denied Error

If you get "permission denied" when running Docker:

# Make sure your user is in the docker group
groups $USER

# If docker is not listed:
sudo usermod -aG docker $USER
newgrp docker

Docker Daemon Not Running

# Linux
sudo systemctl start docker
sudo systemctl status docker

# If it fails to start, check logs:
sudo journalctl -u docker.service

Docker Compose Command Not Found

If docker compose doesn't work but docker-compose does:

# Install Docker Compose plugin
sudo apt-get install docker-compose-plugin

# Or use docker-compose (standalone)
sudo apt-get install docker-compose

Buque supports both docker compose (V2) and docker-compose (V1).

Resources

• Docker Documentation
• Docker Compose Documentation
• Docker Desktop
• WSL2 Installation Guide

Next Steps

Once Docker is installed, you can:

1. Install Buque:

   cd buque
   ./install.sh
   

2. Initialize Buque:

   buque init
   

3. Start managing your containers:

   buque env add myapp /path/to/myapp
   buque up myapp