If you’re into penetration testing, you’ve probably used Metasploit — the Swiss Army knife of offensive security. Pair it with Armitage, and you get a powerful GUI front-end for visualizing exploits, managing sessions, and collaborating with your team.

But installing Armitage today is a mess. It’s outdated, full of dependencies, and prone to breaking.

So here’s the fix: Run Metasploit + Armitage in Docker, either with a one-liner or a full-blown Docker Compose setup — and make it work with X11 GUI even on modern distros like CachyOS.

⚙️ Tools Used

• 🐳 Docker
• 🧰 mirogula/kali_linux_metasploit_armitage
• 🖥️ X11 for GUI forwarding
• 🧪 Tested on CachyOS (Arch-based)

🚀 Quick Start with docker run

Run this if you want it fast:

✅ 1. Install xhost

sudo pacman -S xorg-xhost

✅ 2. Allow local Docker GUI access

xhost +local:docker

For fish shell:

set -x DISPLAY :0

✅ 3. Run Armitage in Docker

docker run --rm \
  --name armitage \
  --hostname="kali_armitage" \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v mg_metasploit_postgresql_data:/var/lib/postgresql \
  -v mg_metasploit_framework_dir:/usr/share/metasploit-framework \
  mirogula/kali_linux_metasploit_armitage

If everything is set up right, Armitage GUI will appear and connect to the bundled Metasploit framework + PostgreSQL.

🐳 Full Setup with Docker Compose (Recommended)

For a more reusable and clean lab, use this:

📄 docker-compose.yml

services:
  armitage:
    image: mirogula/kali_linux_metasploit_armitage
    container_name: armitage
    hostname: kali_armitage
    environment:
      - DISPLAY=${DISPLAY}
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix
      - mg_metasploit_postgresql_data:/var/lib/postgresql
      - mg_metasploit_framework_dir:/usr/share/metasploit-framework
    network_mode: host
    restart: unless-stopped
    stdin_open: true
    tty: true

volumes:
  mg_metasploit_postgresql_data:
  mg_metasploit_framework_dir:

▶️ Launch:

xhost +local:docker
docker compose up -d

🛠️ Troubleshooting

❌ Can't connect to X11 window server using ':0'

Fix: You didn’t run xhost +local:docker, or $DISPLAY is not set.

xhost +local:docker
echo $DISPLAY  # should output :0

In fish shell:

set -x DISPLAY :0

✅ Test Your X11 Setup

Before launching Armitage, test with:

docker run --rm -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix archlinux xeyes

If xeyes appears, GUI forwarding works.

🧯 Reset the Lab

To delete everything and start fresh:

docker compose down -v

🧰 Volumes Used

These keep your sessions and configs between runs.

🧪 Tested on

• ✅ CachyOS (Arch-based)
• ✅ KDE Plasma (X11 session)
• ✅ Docker 25+