Skip to main content

Container Support

Docker and Podman Integration

OMG provides seamless container integration for development workflows, preferring Podman for rootless security while supporting Docker.

🎯 Overview​

Container features:

  • Auto-detection — Detects Docker or Podman automatically
  • Dev shells — Interactive containers with project mounted
  • Dockerfile generation — Auto-generate from detected runtimes
  • Build integration — Build images with OMG defaults

🐳 Container Runtime​

Detection Priority​

OMG checks for container runtimes in this order:

  1. Podman (preferred for rootless security)
  2. Docker

Check Status​

omg container status

Output:

Container Runtime Status:
  Runtime: podman 4.8.0
  Rootless: Yes
  Running containers: 3
  Images: 15

🖥️ Development Shells​

Start Dev Shell​

# Interactive shell with current directory mounted
omg container shell

This:

  1. Detects project runtimes (from .nvmrc, etc.)
  2. Selects appropriate base image
  3. Mounts current directory to /app
  4. Starts interactive shell

Custom Base Image​

# Use specific base image
omg container shell --image node:20-alpine

Shell Options​

# Specify working directory
omg container shell --workdir /workspace

# Add environment variables
omg container shell --env NODE_ENV=development

# Mount additional volumes
omg container shell --volume ~/.ssh:/root/.ssh:ro

🏃 Running Containers​

Run Commands​

# Run command in container
omg container run alpine -- echo "hello"

# Run with specific image
omg container run node:20 -- npm test

# Interactive
omg container run -it ubuntu -- bash

Common Patterns​

# Quick test in clean environment
omg container run node:20 -- node -e "console.log('Hello')"

# Run tests in isolation
omg container run rust:1.75 -- cargo test

# Check Python version
omg container run python:3.12 -- python --version

🏗️ Building Images​

Build from Dockerfile​

# Build in current directory
omg container build

# Tag the image
omg container build -t myapp:latest

# Specify Dockerfile
omg container build -f Dockerfile.prod -t myapp:prod

Build Options​

# Disable cache
omg container build --no-cache -t myapp

# Build arguments
omg container build --build-arg NODE_VERSION=20 -t myapp

# Target specific stage
omg container build --target production -t myapp

📄 Dockerfile Generation​

Auto-Generate Dockerfile​

# Generate based on detected runtimes
omg container init

This creates a Dockerfile based on:

  • Detected version files (.nvmrc, .python-version, etc.)
  • Project type (package.json, Cargo.toml, etc.)
  • Best practices for that ecosystem

Example Generated Dockerfile​

For a Node.js project with .nvmrc containing 20.10.0:

# Auto-generated by OMG
FROM node:20-alpine

WORKDIR /app

# Install dependencies first for better caching
COPY package*.json ./
RUN npm ci --production

# Copy source
COPY . .

# Build if needed
RUN npm run build --if-present

EXPOSE 3000
CMD ["npm", "start"]

Custom Base Image​

# Specify base image
omg container init --base ubuntu:22.04

📋 Container Management​

List Containers​

# Running containers
omg container list

# All containers (including stopped)
omg container list --all

List Images​

omg container images

Pull Images​

omg container pull node:20
omg container pull alpine:latest

Stop Containers​

# Stop by name or ID
omg container stop mycontainer

# Stop all
omg container stop --all

Execute in Running Container​

# Run command in existing container
omg container exec mycontainer -- ls -la

# Interactive shell
omg container exec -it mycontainer -- bash

🔄 Workflow Integration​

Development Workflow​

# 1. Start dev container
omg container shell

# 2. Inside container, use OMG normally
omg run dev
omg run test

# 3. Exit when done
exit

CI/CD Integration​

# GitHub Actions example
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install OMG
        run: curl -fsSL https://raw.githubusercontent.com/PyRo1121/omg/main/install.sh | bash
      
      - name: Run in Container
        run: omg container run node:20 -- npm test

Docker Compose Compatibility​

OMG works alongside docker-compose:

# Start services with compose
docker-compose up -d

# Use OMG for one-off commands
omg container exec web -- omg run test

⚙️ Configuration​

Runtime Preference​

Set preferred runtime in ~/.config/omg/config.toml:

[container]
runtime = "podman"  # or "docker"

Default Options​

[container]
# Default user inside containers
user = "1000:1000"

# Always mount these paths
volumes = [
    "~/.gitconfig:/etc/gitconfig:ro",
    "~/.ssh:/root/.ssh:ro"
]

# Environment variables
env = [
    "TERM=xterm-256color"
]

🔒 Security​

Rootless Containers (Podman)​

OMG prefers Podman for rootless container execution:

  • No root daemon required
  • User namespace isolation
  • Better security defaults

Best Practices​

  1. Use non-root user in Dockerfile

    RUN adduser -D appuser
    USER appuser

  2. Read-only mounts when possible

    omg container shell --volume ~/.ssh:/root/.ssh:ro

  3. Avoid privileged mode

🔧 Troubleshooting​

"No container runtime found"​

# Check if Docker/Podman is installed
which docker
which podman

# Install Podman (Arch)
omg install podman

# Install Docker (Arch)
omg install docker
sudo systemctl start docker

"Permission denied"​

# For Docker, ensure user is in docker group
sudo usermod -aG docker $USER
newgrp docker

# Or use Podman (rootless)
omg install podman

"Image not found"​

# Pull image first
omg container pull node:20

# Check available images
omg container images

Container won't start​

# Check container logs
podman logs <container-id>
# or
docker logs <container-id>

# Try running interactively
omg container run -it <image> -- bash

📚 See Also​