Complete Ahab Tutorial

From zero to deployed service in 30 minutes

30 minutes Beginner friendly Learn by doing

About This Tutorial

This tutorial is part of the Ahab Website - one of three teaching tools designed for different learning contexts:

This Website

Conceptual learning & discovery

Technical Docs

Implementation & commands

Interactive GUI

Hands-on practice

After completing this tutorial, try the Interactive GUI for hands-on practice!

Make commands = Secure boilerplate you can trust. Every command follows security best practices. See exactly what runs. Find a problem? Tell us - everyone benefits.

STOP: Install Prerequisites First

Before running make install, you MUST have Git, Vagrant, and a virtualization provider installed.

Install Prerequisites Now →

Quick Start (Already Have Prerequisites?)

Four Commands to Your First Deployment

0
brew install git vagrant

Install prerequisites (macOS)

1
git clone https://github.com/waltdundore/ahab.git && cd ahab

Get the code

2
make install

Create workstation VM (5-10 min)

3
make install apache

Deploy web server (2-3 min)

Then visit http://localhost:8080 to see your server!

New to this? Keep reading for detailed setup instructions.

Why We Use Make Commands

Make Commands = Secure, Tested Boilerplate

Instead of memorizing complex commands with security flags, we use simple make commands that:

  • Follow security best practices - Non-root containers, read-only mounts, input validation
  • Are tested and validated - Every command passes NASA Power of 10 standards
  • Are transparent - Open the Makefile, see exactly what runs
  • Improve together - Find a problem? Tell us. Everyone benefits from the fix.

❌ Without Make (Complex & Error-Prone)

# You'd have to remember:
vagrant up --no-destroy-on-error
vagrant ssh -c "sudo chown -R vagrant:vagrant /home/vagrant/ahab"
vagrant ssh -c "cd /home/vagrant/ahab && docker run --rm \
  -v \$(pwd):/workspace -w /workspace \
  --user 1000:1000 --read-only \
  --cap-drop=ALL --security-opt=no-new-privileges:true \
  python:3.11-slim bash -c 'pip install -q PyYAML && \
  python3 scripts/generate-compose.py apache'"
vagrant ssh -c "cd /home/vagrant/ahab/generated && docker-compose up -d"

# Easy to forget security flags!
# Easy to make mistakes!
# Hard to maintain!

✅ With Make (Simple & Secure)

# Just type:
make install apache

# That's it!
# Security built in
# Tested and validated
# Easy to remember

See What Runs (Transparency)

Every Make command is just a wrapper around tested, secure commands. Want to see what make install apache does?

Click to see the Makefile code 
install:
    @echo "Creating workstation VM..."
    @vagrant up --no-destroy-on-error || exit 1
    @echo "Fixing permissions..."
    @vagrant ssh -c "sudo chown -R vagrant:vagrant /home/vagrant/ahab"
    @if [ -n "$(MODULES)" ]; then \
        echo "Deploying modules: $(MODULES)"; \
        vagrant ssh -c "cd /home/vagrant/ahab && \
            docker run --rm \
                -v \$(pwd):/workspace \
                -w /workspace \
                python:3.11-slim \
                bash -c 'pip install -q PyYAML && \
                    python3 scripts/generate-compose.py $(MODULES)'"; \
        vagrant ssh -c "cd /home/vagrant/ahab/generated && \
            docker-compose up -d"; \
    fi
    @echo "✅ Ready"

See? Nothing hidden. All the security flags are there. You can inspect, modify, or improve it.

We Want Your Feedback

Found a security issue? See a better way? Please tell us!

  • Open an issue on GitHub
  • Submit a pull request with improvements
  • Share your concerns in GitHub Issues

When you improve Ahab, everyone benefits. That's the power of open source.

What is Ahab?

Ahab (Automated Host Administration & Build) is infrastructure automation software that makes deploying and managing services simple.

Why Should You Care?

Simple Commands

Deploy a web server with one command: make install apache

Learn Useful Skills

Docker, Ansible, and Linux are widely used in the industry

Safe to Experiment

Everything runs in virtual machines - can't break your computer

Free for Education

Free for schools, non-profits, and students

What You'll Learn

  • How to install and configure Ahab
  • How to deploy your first service (Apache web server)
  • How to verify everything is working
  • How to troubleshoot common issues
  • How to deploy additional services

Prerequisites

What You Need

Computer

Mac, Linux, or Windows with at least 8GB RAM

Basic Terminal Skills

Comfortable typing commands (we'll teach you)

30 Minutes

Time to complete this tutorial

Internet Connection

To download software and images

Alpha Software Warning: Ahab is currently in alpha testing. It's great for learning and experimentation, but not ready for production use in schools yet. We're transparent about this!

Installation

Critical: You MUST install these three tools before running make install. Without them, Ahab will not work.

Step 1: Install Prerequisites

Ahab requires exactly three tools: Git, Vagrant, and a virtualization provider. All are free.

macOS Installation

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install git
brew install --cask vagrant
# Virtualization provider (choose one):
brew install --cask virtualbox     # Most common
# OR: brew install --cask vmware-fusion  # Alternative

Homebrew is a package manager for macOS

You may need to allow your virtualization provider in System Preferences → Security & Privacy

Linux Installation

Ubuntu/Debian
# Update package list
sudo apt update

# Install Git
sudo apt install -y git

# Install virtualization provider (choose one):
sudo apt install -y virtualbox     # Most common
# OR: sudo apt install -y qemu-kvm libvirt-daemon-system  # Alternative

# Install Vagrant
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install -y vagrant
Fedora
# Install Git
sudo dnf install -y git

# Install virtualization provider (choose one):
sudo dnf install -y VirtualBox     # Most common
# OR: sudo dnf install -y qemu-kvm libvirt  # Alternative

# Install Vagrant
sudo dnf install -y vagrant

On Fedora, you may need to enable the RPM Fusion repository for VirtualBox, or use the built-in libvirt/KVM

Windows Installation

  1. Download and install Git for Windows
  2. Download and install a virtualization provider:
  3. Download and install Vagrant
  4. Restart your computer after installation

Use Git Bash or PowerShell for commands

Step 2: Verify Installation (REQUIRED)

Do NOT skip this step! Run these commands to verify everything is installed correctly: 
# Check Git
git --version
# Should show: git version 2.x.x

# Check Vagrant
vagrant --version
# Should show: Vagrant 2.x.x

# Check virtualization provider
VBoxManage --version        # For VirtualBox
# OR: vmrun -T ws list      # For VMware
# Should show version info
All three commands show version numbers? Perfect! You're ready to continue.

If Any Command Fails

  • Command not found: That tool isn't installed. Go back and install it.
  • Permission denied: You may need to restart your terminal or computer.
  • Virtualization issues: Check System Preferences → Security & Privacy (macOS) or enable virtualization in BIOS.

Don't proceed until all three commands work! make install will fail without them.

Step 3: Clone Ahab Repository

# Clone the repository
git clone https://github.com/waltdundore/ahab.git

# Enter the directory
cd ahab

# Verify you're in the right place
ls -la
# You should see: Makefile, README.md, playbooks/, etc.

Your First Deployment

Step 1: Create Workstation VM

This creates a virtual machine with all the tools you need:

make install
What's happening? This command:
  • Downloads a Fedora Linux image (~500MB)
  • Creates a virtual machine
  • Installs Git, Ansible, and Docker
  • Takes 5-10 minutes on first run

First run takes 5-10 minutes. Perfect time for a coffee break!

Step 2: Verify Installation

Make sure everything worked:

make test
All tests passing? Great! You're ready to deploy services.

Step 2.5: Choose Your Operating System (Optional)

Ahab supports three Linux distributions. Fedora is the default, but you can choose:

# Option 1: Use default (Fedora 43)
# No action needed - just proceed to Step 3

# Option 2: Choose Debian 13
echo "DEFAULT_OS=debian" > ahab.conf

# Option 3: Choose Ubuntu 24.04 LTS
echo "DEFAULT_OS=ubuntu" > ahab.conf
Which OS should I choose?
  • Fedora 43 (default) - Latest features, DNF package manager, SELinux security
  • Debian 13 - Rock-solid stability, APT package manager, AppArmor security
  • Ubuntu 24.04 LTS - Long-term support, APT package manager, AppArmor security

All three work great! Choose based on what you want to learn or what your school uses.

Step 3: Deploy Apache Web Server

Now let's deploy your first service:

make install apache
What's happening? This command:
  • Ensures the workstation VM is running (with your chosen OS)
  • Deploys Apache web server in a Docker container
  • Configures port forwarding (VM port 80 → your computer port 8080)
  • Takes 2-3 minutes

Step 4: Test Your Web Server

Open your web browser and visit:

http://localhost:8080
See the Ahab welcome page? Congratulations! You just deployed your first service!

Troubleshooting

Can't connect to localhost:8080?
  • Check if VM is running: vagrant status
  • Check if Apache is running: make ssh then docker ps
  • Try a different port if 8080 is in use
  • Check firewall settings
VM won't start?
  • Ensure your virtualization provider is running
  • Check if virtualization is enabled in BIOS
  • Try: make clean then make install
Installation hangs or times out?
  • Check your internet connection
  • Vagrant downloads can be slow - be patient
  • If it hangs for more than 15 minutes, press Ctrl+C and try again

Command Reference

All Ahab commands use make for simplicity and security. Here's what each command does and what runs behind the scenes.

Core Commands

make install 5-10 min first run

Creates a Fedora workstation VM with Docker, Ansible, and security hardening.

What runs behind the scenes 
# 1. Create VM with Vagrant
vagrant up --no-destroy-on-error

# 2. Fix permissions (security)
vagrant ssh -c "sudo chown -R vagrant:vagrant /home/vagrant/ahab"

# 3. Ansible provisions:
#    - Install Docker (rootless mode)
#    - Install Ansible
#    - Configure SELinux
#    - Set up firewall
#    - Security hardening

Why use this? Handles all the security configuration automatically. Manual setup would take hours and you'd likely miss security steps.

make install apache 2-3 min

Creates workstation + deploys Apache web server in a secure Docker container.

What runs behind the scenes 
# 1. Ensure workstation exists (runs make install if needed)
vagrant up --no-destroy-on-error

# 2. Generate docker-compose.yml with security flags
docker run --rm \
    -v $(pwd):/workspace \
    -w /workspace \
    --user 1000:1000 \              # Non-root user
    --read-only \                   # Read-only filesystem
    --cap-drop=ALL \                # Drop all capabilities
    --security-opt=no-new-privileges:true \
    python:3.11-slim \
    bash -c 'pip install -q PyYAML && \
        python3 scripts/generate-compose.py apache'

# 3. Deploy with docker-compose
cd generated && docker-compose up -d

Why use this? All those security flags (non-root, read-only, capability dropping) are easy to forget. Make command ensures they're always applied.

make test 1-2 min

Runs NASA Power of 10 validation and integration tests.

What runs behind the scenes 
# 1. Validate NASA Power of 10 standards
bash scripts/validate-nasa-standards.sh
# Checks:
#   - No unbounded loops
#   - All return values checked
#   - Functions ≤ 60 lines
#   - No recursion
#   - Assertions enabled

# 2. Run integration tests
bash tests/integration/test-apache-simple.sh
# Verifies:
#   - Services deploy correctly
#   - Ports are accessible
#   - Security configurations applied

# 3. Record test status
bash scripts/record-test-pass.sh

Why use this? Ensures code quality and security standards. If tests pass, you know the system is working correctly.

make ssh instant

SSH into the workstation VM to explore or debug.

What runs behind the scenes 
# Simply runs:
vagrant ssh

# Connects you to the VM as the vagrant user
# You can then:
#   - Run docker ps to see containers
#   - Check logs with docker logs
#   - Explore the filesystem
#   - Debug issues

Why use this? Vagrant handles SSH key management and connection details. Just type make ssh and you're in.

make clean 30 sec

Destroys the workstation VM (start fresh).

What runs behind the scenes 
# 1. Destroy VM
vagrant destroy -f

# 2. Clean up Vagrant metadata
rm -rf .vagrant

# Your host machine is untouched
# All changes were in the VM only

Why use this? Safe experimentation! Break things, learn, then make clean && make install to start fresh.

Development Commands

make verify-install 10 sec

Verify workstation is properly configured.

What runs behind the scenes 
# Checks:
vagrant status | grep -q "running"           # VM running?
vagrant ssh -c "command -v git"              # Git installed?
vagrant ssh -c "command -v ansible"          # Ansible installed?
vagrant ssh -c "command -v docker"           # Docker installed?
vagrant ssh -c "systemctl is-active docker"  # Docker running?
make generate-compose apache mysql 5 sec

Generate docker-compose.yml for multiple services.

What runs behind the scenes 
# Runs Python script in secure Docker container
docker run --rm \
    -v $(pwd):/workspace \
    -w /workspace \
    python:3.11-slim \
    sh -c "pip install -q pyyaml && \
        python scripts/generate-docker-compose.py apache mysql"

# Creates: generated/docker-compose.yml
# With all security configurations

Why use this? Generates consistent, secure configurations. No copy-paste errors, no forgotten security flags.

Audit & Security Commands

make audit 2-3 min

Run accountability audit (checks for hardcoded secrets, root containers, etc.).

What runs behind the scenes 
# Runs comprehensive security audit:
bash scripts/audit-accountability.sh

# Checks for:
#   - Hardcoded secrets (API keys, passwords)
#   - Root containers (security violation)
#   - Unbounded loops (NASA Rule #2)
#   - Missing return value checks (NASA Rule #7)
#   - Functions > 60 lines (NASA Rule #4)
#   - Duplicate code (DRY violations)

Why use this? Catches security issues before they reach production. Automated checks are more reliable than manual review.

make audit-docker-stig 1 min

Validate Docker STIG compliance (DoD security standards).

What runs behind the scenes 
# Validates Docker containers against STIG requirements:
bash scripts/ci/validate-docker-stig.sh

# Checks:
#   - Non-root users (STIG V-235783)
#   - Read-only filesystems (STIG V-235784)
#   - Dropped capabilities (STIG V-235785)
#   - Security options (STIG V-235786)
#   - Resource limits (STIG V-235787)
#   - Network isolation (STIG V-235788)

Why use this? DoD-level security standards. If you're deploying in schools or government, these checks are essential.

All Commands

See all available commands:

make help

This shows the complete list with descriptions. Every command is documented.

Remember: You Can See Everything

Every Make command is defined in ahab/Makefile. Open it, read it, understand it, improve it.

# View the Makefile
cat ahab/Makefile

# Or open in your editor
vim ahab/Makefile
code ahab/Makefile

Found something wrong? Tell us! We want to fix it so everyone benefits.

Understanding What You Built

Architecture Overview

Your Computer

Mac, Linux, or Windows

↓

Virtualization

Runs virtual machines (VirtualBox, VMware, etc.)

↓

Fedora VM

Linux workstation with Docker

↓

Docker Container

Apache web server

Key Concepts

Virtual Machine (VM)

A computer inside your computer. It's completely isolated - you can't break anything on your real computer.

Think of it like: A sandbox where you can experiment safely.

Docker Container

A lightweight, portable package that contains everything needed to run an application.

Think of it like: A shipping container for software - works the same everywhere.

Ansible

Automation tool that configures systems. It reads instructions (playbooks) and makes them happen.

Think of it like: A recipe that a robot follows to set up your infrastructure.

Make

A build tool that runs commands. make install is easier to remember than long complex commands.

Think of it like: A remote control with simple buttons for complex operations.

Useful Commands

See the Commands Reference section above for complete details on what each command does behind the scenes.

make help

Show all available commands

make ssh

Connect to the VM

make test

Run tests (NASA standards + integration)

make verify-install

Verify workstation is configured correctly

make clean

Destroy the VM (start fresh)

make audit

Run security audit

Want to Learn More?

Every Make command is just a wrapper around standard tools:

  • Vagrant - VM management
  • Ansible - Configuration automation
  • Docker - Container runtime
  • Python - Scripting and generation

Open ahab/Makefile to see exactly what each command does. It's all transparent!

Next Steps

Deploy More Services

MySQL Database

make install mysql

Coming soon

PHP Runtime

make install php

For PHP applications

Nginx

make install nginx

Alternative web server

Your Service

make install yourservice

Create your own modules

Learn More

1

Explore the Documentation

2

Experiment Safely

  • SSH into the VM: make ssh
  • Explore Docker: docker ps, docker logs
  • Break things! You can always make clean and start over
3

Learn the Tools

4

Contribute

  • Report bugs on GitHub Issues
  • Suggest features
  • Create your own modules
  • Improve documentation

For Teachers & Schools

Using Ahab in the Classroom

Ahab is aligned with Georgia Computer Science Standards and teaches real-world DevOps skills.

  • Standards Alignment: IT-CSP, IT-NSS, IT-ITS, IT-PGAS
  • Real Tools: Same as used by Netflix, Spotify, NASA
  • Safe Learning: Virtual machines mean students can't break anything
  • Free for Education: CC BY-NC-SA 4.0 license

Read the Executive Summary for school administrators.

Frequently Asked Questions

How much does this cost?

Ahab is free for schools, non-profits, and students under the CC BY-NC-SA 4.0 license. For-profit entities need to negotiate commercial terms.

Is this safe for students to use?

Yes! Everything runs in virtual machines, which are completely isolated from your real computer. Students can experiment, break things, and learn without any risk to the host system.

What if I get stuck?

Check the Troubleshooting Guide or open an issue on GitHub. We're here to help!

Can I use this in production?

Not yet. Ahab is currently in alpha testing. It's great for learning and experimentation, but we're not ready for production use in schools yet. We're transparent about this and working toward production readiness.

What computer specs do I need?

Minimum: 8GB RAM, 20GB free disk space, modern CPU with virtualization support. Recommended: 16GB RAM for running multiple services.

Can I customize or modify Ahab?

Yes! Under the CC BY-NC-SA 4.0 license, you can modify it for your needs. If you share your modifications, they must use the same license.

Why is it called Ahab?

Automated Host Administration & Build. Also, we're chasing the white whale of perfect infrastructure automation!

Need Help?

GitHub Repository

Browse code and documentation

Report Issues

Found a bug? Let us know

Discussions

Ask questions and share ideas

Back to Home

Return to main page