Quick Start¶

Get up and running with Testing Containers in minutes.

Prerequisites¶

Podman or Docker installed
SSH key generated (~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub)
Ansible installed (for testing roles)

Method 1: Pull and Run¶

Step 1: Pull an Image¶

# Debian 12
podman pull ghcr.io/jackaltx/testing-containers/debian-ssh:12

# Rocky Linux 9
podman pull ghcr.io/jackaltx/testing-containers/rocky-ssh:9

# Ubuntu 24.04
podman pull ghcr.io/jackaltx/testing-containers/ubuntu-ssh:24

Step 2: Start Container¶

podman run -d \
    --name test_debian \
    --privileged \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    -p 2222:22 \
    ghcr.io/jackaltx/testing-containers/debian-ssh:12 \
    /sbin/init

Explanation: - --privileged: Required for systemd - -v /sys/fs/cgroup:...: Mount cgroups for systemd - -p 2222:22: Map SSH port to localhost:2222 - /sbin/init: Start systemd as PID 1

Step 3: Wait for SSH¶

# Wait a few seconds for SSH to start
sleep 5

# Check SSH is running
podman exec test_debian systemctl status sshd

Step 4: Connect via SSH¶

# SSH to container
ssh -p 2222 jackaltx@localhost

# Or from Ansible
ansible -i localhost:2222, all \
    --user jackaltx \
    --private-key ~/.ssh/id_ed25519 \
    -m ping

Step 5: Clean Up¶

# Stop and remove
podman stop test_debian
podman rm test_debian

Method 2: Use Helper Scripts¶

The testing-containers repository includes helper scripts:

Clone Repository¶

git clone https://github.com/jackaltx/testing-containers.git
cd testing-containers

Run Container¶

# Set container type
export CONTAINER_TYPE=debian12-ssh

# Start container (uses run-podman.sh)
./run-podman.sh

# Container is now running on port 2222
ssh -p 2222 jackaltx@localhost

Clean Up¶

# Stop and remove (uses cleanup-podman.sh)
./cleanup-podman.sh

Method 3: Molecule Integration¶

Create Molecule Scenario¶

# In your Ansible role directory
molecule init scenario -r my_role -d podman

Configure Molecule¶

Edit molecule/default/molecule.yml:

---
dependency:
  name: galaxy

driver:
  name: podman

platforms:
  - name: debian-12
    image: ghcr.io/jackaltx/testing-containers/debian-ssh:12
    privileged: true
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
    command: /sbin/init
    pre_build_image: true

  - name: rocky-9
    image: ghcr.io/jackaltx/testing-containers/rocky-ssh:9
    privileged: true
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
    command: /sbin/init
    pre_build_image: true

provisioner:
  name: ansible
  inventory:
    hosts:
      all:
        ansible_user: jackaltx
        ansible_ssh_private_key_file: ~/.ssh/id_ed25519

verifier:
  name: ansible

Run Molecule Tests¶

# Full test sequence
molecule test

# Or step by step
molecule create
molecule converge
molecule verify
molecule destroy

Method 4: CI/CD Integration¶

GitHub Actions¶

# .github/workflows/test.yml
name: Test Ansible Role

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        distro:
          - debian-ssh:12
          - rocky-ssh:9
          - ubuntu-ssh:24

    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install ansible molecule molecule-plugins[podman]

      - name: Run Molecule tests
        run: |
          export TEST_DISTRO=${{ matrix.distro }}
          molecule test

GitLab CI¶

# .gitlab-ci.yml
test:
  image: quay.io/podman/stable
  services:
    - docker:dind

  variables:
    TEST_IMAGE: ghcr.io/jackaltx/testing-containers/debian-ssh:12

  before_script:
    - apt-get update
    - apt-get install -y python3-pip
    - pip3 install ansible molecule molecule-plugins[podman]

  script:
    - molecule test

Common Scenarios¶

Scenario 1: Test Role on Multiple Distributions¶

# Test on Debian
export CONTAINER_TYPE=debian12-ssh
./run-podman.sh
ansible-playbook -i localhost:2222, site.yml
./cleanup-podman.sh

# Test on Rocky
export CONTAINER_TYPE=rocky9x-ssh
./run-podman.sh
ansible-playbook -i localhost:2222, site.yml
./cleanup-podman.sh

# Test on Ubuntu
export CONTAINER_TYPE=ubuntu24-ssh
./run-podman.sh
ansible-playbook -i localhost:2222, site.yml
./cleanup-podman.sh

Scenario 2: Interactive Debugging¶

# Start container
podman run -d \
    --name debug_container \
    --privileged \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    -p 2222:22 \
    ghcr.io/jackaltx/testing-containers/debian-ssh:12 \
    /sbin/init

# SSH into container
ssh -p 2222 jackaltx@localhost

# Inside container: test commands, check logs, etc.
sudo systemctl status
journalctl -xe

# Exit and remove when done
exit
podman rm -f debug_container

Scenario 3: Parallel Testing¶

# Start multiple containers on different ports
podman run -d --name debian_test -p 2222:22 --privileged \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    ghcr.io/jackaltx/testing-containers/debian-ssh:12 /sbin/init

podman run -d --name rocky_test -p 2223:22 --privileged \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    ghcr.io/jackaltx/testing-containers/rocky-ssh:9 /sbin/init

podman run -d --name ubuntu_test -p 2224:22 --privileged \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    ghcr.io/jackaltx/testing-containers/ubuntu-ssh:24 /sbin/init

# Test all in parallel
ansible -i inventory.yml all -m ping &
wait

# Cleanup all
podman rm -f debian_test rocky_test ubuntu_test

Troubleshooting Quick Start¶

Container Won't Start¶

# Check if image exists
podman images | grep testing-containers

# Check logs
podman logs test_debian

# Try without systemd first
podman run -it --rm ghcr.io/jackaltx/testing-containers/debian-ssh:12 /bin/bash

SSH Connection Refused¶

# Verify SSH is running
podman exec test_debian systemctl status sshd

# Check port mapping
podman port test_debian

# Try direct connection
podman exec -it test_debian bash

Permission Denied (publickey)¶

# Verify your SSH key was used to build the image
# These are pre-built with a specific key

# For custom key, rebuild image:
export SSH_KEY="$(cat ~/.ssh/id_ed25519.pub)"
./build.sh debian12-ssh

systemd Not Working¶

# Verify privileged mode
podman inspect test_debian | grep Privileged

# Verify cgroup mount
podman inspect test_debian | grep cgroup

# Restart with correct flags:
podman rm -f test_debian
podman run -d --name test_debian \
    --privileged \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    --cgroupns=host \
    -p 2222:22 \
    ghcr.io/jackaltx/testing-containers/debian-ssh:12 \
    /sbin/init

Next Steps¶

Learn More: Read Design Philosophy
Container Details: See Container Images
Advanced Usage: See Molecule Integration
Build Your Own: See Building Images

Cheat Sheet¶

# Pull image
podman pull ghcr.io/jackaltx/testing-containers/debian-ssh:12

# Run container
podman run -d --name test --privileged \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw -p 2222:22 \
    ghcr.io/jackaltx/testing-containers/debian-ssh:12 /sbin/init

# SSH access
ssh -p 2222 jackaltx@localhost

# Ansible ping
ansible -i localhost:2222, all -u jackaltx -m ping

# Check status
podman exec test systemctl status

# View logs
podman logs test

# Cleanup
podman rm -f test