Skip to content

Add Podman/Docker compatibility to container commands#7

Merged
safurrier merged 5 commits intomainfrom
feat/podman-docker-compatibility
Jun 22, 2025
Merged

Add Podman/Docker compatibility to container commands#7
safurrier merged 5 commits intomainfrom
feat/podman-docker-compatibility

Conversation

@safurrier
Copy link
Owner

@safurrier safurrier commented Jun 22, 2025

Summary

Adds seamless Podman/Docker compatibility to all container-related commands, with automatic engine detection, smart defaults, and robust error handling.

Changes

Smart Container Engine Detection

  • Auto-detects Podman (preferred) or Docker with fallback
  • Override with CONTAINER_ENGINE=docker make dev-env
  • New make container-info command shows current configuration and status

Podman Integration & Fixes

  • Automatic Podman machine lifecycle management (starts if needed)
  • Uses podman-compose for proper compose functionality
  • Fixed volume mount permissions with :Z SELinux option
  • Improved macOS compatibility with proper machine detection

Docker Compatibility & Robustness

  • Fixed Dockerfile to use --system flag for uv dependency installation
  • Made container setup resilient to make init project restructuring
  • Simplified volume mounts to avoid missing file errors
  • Proper working directory setup at /workspace

Developer Experience

  • All existing commands work unchanged (make dev-env, build-image, etc.)
  • Added comprehensive troubleshooting documentation
  • Environment variable configuration for edge cases
  • Automatic dependency and machine readiness checks

Documentation

  • Updated README with container compatibility information
  • Added detailed docs/container-setup.md with:
    • Setup instructions for both engines
    • Troubleshooting guide for common issues
    • Compatibility notes for project initialization
    • Usage examples and best practices

Testing

  • Verified on macOS with both Docker and Podman
  • Tested before and after make init workflow
  • Confirmed volume mounts and permission handling
  • Validated automatic machine management

This maintains the 80/20 principle - most users get seamless operation, power users can configure as needed.

- Auto-detects container engine (Podman preferred if available)
- Handles UID/GID mapping for both engines
- Updates all container-related Make targets
- Adds container-info target to show current configuration
- Includes troubleshooting documentation

Users can now use either Docker or Podman seamlessly, with the ability
to override via CONTAINER_ENGINE environment variable.
- Fix Podman machine detection with proper JSON parsing
- Add automatic machine startup when needed
- Use podman-compose instead of podman compose
- Add comprehensive Podman readiness checks
- Update documentation with macOS-specific troubleshooting

Resolves issues with Podman setup on macOS where the machine
needs to be running and podman-compose must be used for compose functionality.
- Fix Dockerfile to use --system flag for uv pip sync
- Simplify docker-compose.yml volume mounts to avoid missing files
- Use :Z option for proper SELinux context in Podman
- Remove user mapping to let Podman rootless handle permissions
- Mount entire project as /workspace for simplicity

Podman dev environment now works correctly on macOS.
- Remove hardcoded src/ directory references from Dockerfile
- Use /workspace as WORKDIR to match volume mount location
- Copy dependencies to /tmp for installation, then clean up
- This ensures containers work both before and after make init renames src/

The container setup now survives project initialization and directory restructuring.
@safurrier safurrier merged commit 7eb0cc5 into main Jun 22, 2025
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant