Skip to content

Commit cc54daa

Browse files
CHANGES MADE: (#94)
│ │ 1. ✅ Updated preflight checks │ - Auto-detects Docker OR Podman │ - Sets up Docker compatibility when using Podman │ - File: devops/scripts/azd/helpers/preflight-checks.sh │ │ 2. ✅ Created Podman setup script │ - File: devops/scripts/azd/helpers/setup-podman-docker-compat.sh │ - Creates docker symlink for Podman │ │ 3. ✅ Updated documentation │ - README.md - Added Podman to prerequisites │ - docs/getting-started/prerequisites.md - Added Podman option │ - docs/deployment/PODMAN.md - Full Podman guide (NEW) │ │ 4. ✅ Configured your shell │ - Added to ~/.zshrc: │ export DOCKER_HOST="unix:///run/podman/podman.sock" │ alias docker=podman
1 parent 02e44aa commit cc54daa

5 files changed

Lines changed: 268 additions & 10 deletions

File tree

README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,10 +125,12 @@ Best for: Speed to production, lowest latency requirements.
125125
|------------|-------------|
126126
| Azure CLI | `az --version` |
127127
| Azure Developer CLI | `azd version` |
128-
| Docker | `docker --version` |
128+
| Docker **or** Podman | `docker --version` or `podman --version` |
129129
| Azure Subscription | `az account show` |
130130
| Contributor Access | Required for resource creation |
131131

132+
> **Note**: Podman is fully supported as a Docker alternative. See [Using Podman](docs/deployment/PODMAN.md) for setup instructions.
133+
132134
### ⚡ Fastest Path (15 minutes)
133135

134136
```bash

devops/scripts/azd/helpers/preflight-checks.sh

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,21 @@ check_required_tools() {
7272
"jq:jq (JSON processor):https://jqlang.github.io/jq/download/"
7373
)
7474

75-
# Docker is optional in CI mode
75+
# Check for container runtime (Docker or Podman) - optional in CI mode
76+
local container_runtime=""
77+
if command -v docker &>/dev/null; then
78+
container_runtime="docker"
79+
elif command -v podman &>/dev/null; then
80+
container_runtime="podman"
81+
fi
82+
7683
if [[ "${CI:-}" != "true" ]]; then
77-
tool_checks+=("docker:Docker:https://docs.docker.com/get-docker/")
84+
# Add container runtime check in non-CI mode
85+
if [[ -n "$container_runtime" ]]; then
86+
tool_checks+=("$container_runtime:Container Runtime (Docker/Podman):https://docs.docker.com/get-docker/")
87+
else
88+
tool_checks+=("docker:Container Runtime (Docker/Podman):https://docs.docker.com/get-docker/")
89+
fi
7890
fi
7991

8092
for tool_info in "${tool_checks[@]}"; do
@@ -85,6 +97,7 @@ check_required_tools() {
8597
az) version=$(az --version 2>/dev/null | head -1 | awk '{print $2}') ;;
8698
azd) version=$(azd version 2>/dev/null | head -1) ;;
8799
docker) version=$(docker --version 2>/dev/null | awk '{print $3}' | tr -d ',') ;;
100+
podman) version=$(podman --version 2>/dev/null | awk '{print $3}') ;;
88101
jq) version=$(jq --version 2>/dev/null) ;;
89102
*) version="installed" ;;
90103
esac
@@ -95,14 +108,23 @@ check_required_tools() {
95108
fi
96109
done
97110

98-
# Check Docker separately in CI mode (warn only)
111+
# Setup Podman Docker compatibility if using Podman
112+
if [[ "$container_runtime" == "podman" ]] && [[ ! $(command -v docker) ]]; then
113+
info "Setting up Podman Docker compatibility..."
114+
# Export docker alias for current shell and azd
115+
alias docker=podman
116+
export DOCKER_HOST="unix://$(podman info --format '{{.Host.RemoteSocket.Path}}' 2>/dev/null || echo '/var/run/podman/podman.sock')"
117+
log " ✓ Docker alias configured (podman)"
118+
fi
119+
120+
# Check container runtime in CI mode (warn only)
99121
if [[ "${CI:-}" == "true" ]]; then
100-
if command -v docker &>/dev/null; then
122+
if [[ -n "$container_runtime" ]]; then
101123
local version
102-
version=$(docker --version 2>/dev/null | awk '{print $3}' | tr -d ',')
103-
log "Docker ($version)"
124+
version=$($container_runtime --version 2>/dev/null | awk '{print $3}' | tr -d ',')
125+
log "Container Runtime: $container_runtime ($version)"
104126
else
105-
log "Docker - skipped (CI mode)"
127+
log "Container Runtime - skipped (CI mode)"
106128
fi
107129
fi
108130

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
#!/bin/bash
2+
# ============================================================================
3+
# Podman Docker Compatibility Setup
4+
# ============================================================================
5+
# Sets up Docker CLI compatibility when using Podman instead of Docker.
6+
# This allows azd and other tools expecting 'docker' command to work with Podman.
7+
# ============================================================================
8+
9+
set -euo pipefail
10+
11+
info() { echo "ℹ️ $*"; }
12+
success() { echo "$*"; }
13+
warn() { echo "⚠️ $*"; }
14+
fail() { echo "$*" >&2; }
15+
16+
# Check if Podman is installed
17+
if ! command -v podman &>/dev/null; then
18+
fail "Podman is not installed. Please install it first:"
19+
fail " macOS: brew install podman"
20+
fail " Linux: See https://podman.io/getting-started/installation"
21+
exit 1
22+
fi
23+
24+
# Check if docker command already exists
25+
if command -v docker &>/dev/null; then
26+
docker_version=$(docker --version 2>/dev/null || echo "unknown")
27+
info "Docker command already available: $docker_version"
28+
29+
# Check if it's actually podman
30+
if docker --version 2>&1 | grep -q "podman"; then
31+
success "Docker is aliased to Podman - compatibility already configured"
32+
exit 0
33+
else
34+
info "Using native Docker installation"
35+
exit 0
36+
fi
37+
fi
38+
39+
info "Setting up Podman Docker compatibility..."
40+
41+
# Get Podman socket path
42+
PODMAN_SOCKET=$(podman info --format '{{.Host.RemoteSocket.Path}}' 2>/dev/null || echo "")
43+
44+
if [[ -z "$PODMAN_SOCKET" ]]; then
45+
warn "Could not determine Podman socket path"
46+
warn "You may need to start a Podman machine:"
47+
warn " podman machine init"
48+
warn " podman machine start"
49+
exit 1
50+
fi
51+
52+
# Create docker symlink (requires sudo on most systems)
53+
INSTALL_DIR="/usr/local/bin"
54+
55+
if [[ -w "$INSTALL_DIR" ]]; then
56+
ln -sf "$(command -v podman)" "$INSTALL_DIR/docker"
57+
success "Created docker symlink at $INSTALL_DIR/docker"
58+
else
59+
info "Creating docker symlink (may require password)..."
60+
sudo ln -sf "$(command -v podman)" "$INSTALL_DIR/docker"
61+
success "Created docker symlink at $INSTALL_DIR/docker"
62+
fi
63+
64+
# Set up environment variables
65+
cat << 'EOF'
66+
67+
╭─────────────────────────────────────────────────────────────
68+
│ ✅ Podman Docker Compatibility Configured
69+
├─────────────────────────────────────────────────────────────
70+
71+
│ Add these to your shell profile (~/.zshrc, ~/.bashrc):
72+
73+
│ export DOCKER_HOST="unix:///run/podman/podman.sock"
74+
│ alias docker=podman
75+
76+
│ Or run this command:
77+
│ echo 'export DOCKER_HOST="unix:///run/podman/podman.sock"' >> ~/.zshrc
78+
│ echo 'alias docker=podman' >> ~/.zshrc
79+
│ source ~/.zshrc
80+
81+
╰─────────────────────────────────────────────────────────────
82+
EOF
83+
84+
# Verify setup
85+
if command -v docker &>/dev/null; then
86+
docker_version=$(docker --version 2>/dev/null)
87+
success "Docker command verified: $docker_version"
88+
else
89+
fail "Docker symlink creation failed"
90+
exit 1
91+
fi
92+
93+
info "Note: You may need to restart your terminal for changes to take effect"

docs/deployment/PODMAN.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# 🐳 Using Podman Instead of Docker
2+
3+
This project supports **Podman** as an alternative to Docker for container operations during development and deployment with `azd`.
4+
5+
## ✅ Quick Setup
6+
7+
### 1. Install Podman (if not already installed)
8+
9+
**macOS:**
10+
```bash
11+
brew install podman
12+
```
13+
14+
**Linux:**
15+
```bash
16+
# Fedora/RHEL/CentOS
17+
sudo dnf install podman
18+
19+
# Ubuntu/Debian
20+
sudo apt install podman
21+
```
22+
23+
### 2. Initialize Podman Machine (macOS/Windows)
24+
25+
```bash
26+
podman machine init
27+
podman machine start
28+
```
29+
30+
### 3. Set Up Docker Compatibility
31+
32+
Run the provided setup script:
33+
```bash
34+
./devops/scripts/azd/helpers/setup-podman-docker-compat.sh
35+
```
36+
37+
Or manually add to your shell profile (`~/.zshrc` or `~/.bashrc`):
38+
```bash
39+
export DOCKER_HOST="unix:///run/podman/podman.sock"
40+
alias docker=podman
41+
```
42+
43+
Then reload your shell:
44+
```bash
45+
source ~/.zshrc # or source ~/.bashrc
46+
```
47+
48+
### 4. Verify Setup
49+
50+
```bash
51+
docker --version
52+
# Should output: podman version X.X.X
53+
54+
podman info
55+
# Should show running Podman machine
56+
```
57+
58+
## 🚀 Usage with azd
59+
60+
Once configured, all `azd` commands work seamlessly:
61+
62+
```bash
63+
# Deploy with Podman (no changes needed)
64+
azd up
65+
66+
# Build containers with Podman
67+
azd package
68+
69+
# Deploy just the apps
70+
azd deploy
71+
```
72+
73+
## 🔧 How It Works
74+
75+
The preflight checks in `devops/scripts/azd/helpers/preflight-checks.sh` have been updated to:
76+
77+
1. **Detect container runtime**: Checks for either `docker` or `podman` commands
78+
2. **Auto-configure**: Sets up Docker compatibility if using Podman
79+
3. **Seamless integration**: `azd` uses the container runtime transparently
80+
81+
## 🐛 Troubleshooting
82+
83+
### Podman machine not running
84+
85+
```bash
86+
podman machine list
87+
podman machine start
88+
```
89+
90+
### Docker command not found after setup
91+
92+
Reload your shell:
93+
```bash
94+
exec $SHELL
95+
# or
96+
source ~/.zshrc
97+
```
98+
99+
### azd still looking for Docker
100+
101+
Ensure environment variable is set:
102+
```bash
103+
echo $DOCKER_HOST
104+
# Should output: unix:///run/podman/podman.sock
105+
106+
export DOCKER_HOST="unix:///run/podman/podman.sock"
107+
```
108+
109+
### Permission issues with Podman socket
110+
111+
Check Podman socket permissions:
112+
```bash
113+
ls -la /run/podman/podman.sock
114+
# or on macOS:
115+
ls -la ~/Library/Containers/*/Data/run/podman/podman.sock
116+
```
117+
118+
## 📚 Additional Resources
119+
120+
- [Podman Documentation](https://docs.podman.io/)
121+
- [Docker to Podman Migration](https://podman.io/docs/migration)
122+
- [Azure Developer CLI with Podman](https://learn.microsoft.com/azure/developer/azure-developer-cli/)
123+
124+
## 🔄 Switching Back to Docker
125+
126+
If you need to switch back to Docker:
127+
128+
1. Remove/comment out the Podman configuration from your shell profile
129+
2. Install Docker Desktop
130+
3. Restart your terminal
131+
132+
The preflight checks will automatically detect and use Docker.

docs/getting-started/prerequisites.md

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,14 @@ Install these tools on your development machine:
2222
|------|---------|---------|--------|
2323
| **Azure CLI** | Azure resource management | [:material-download: Install](https://docs.microsoft.com/cli/azure/install-azure-cli) | `az --version` |
2424
| **Azure Developer CLI** | One-command deployment | [:material-download: Install](https://aka.ms/azd-install) | `azd version` |
25-
| **Docker** | Container builds | [:material-download: Install](https://docs.docker.com/get-docker/) | `docker --version` |
25+
| **Docker or Podman** | Container builds | [:material-download: Docker](https://docs.docker.com/get-docker/) / [:material-download: Podman](https://podman.io/getting-started/installation) | `docker --version` |
2626
| **Python 3.11+** | Backend runtime | [:material-download: Install](https://www.python.org/downloads/) | `python --version` |
2727
| **Node.js 22+** | Frontend build | [:material-download: Install](https://nodejs.org/) | `node --version` |
2828
| **jq** | JSON processing for scripts | [:material-download: Install](https://jqlang.github.io/jq/download/) | `jq --version` |
2929

30+
!!! info "Podman as Docker Alternative"
31+
Podman is fully supported! If you prefer Podman over Docker, see [:material-docker: Using Podman](../deployment/PODMAN.md) for setup instructions.
32+
3033
---
3134

3235
## :material-package-down: Quick Install Scripts
@@ -64,8 +67,14 @@ Install these tools on your development machine:
6467
brew install [email protected]
6568
brew install node@22
6669
brew install jq
67-
brew install --cask docker
70+
71+
# Choose one:
72+
brew install --cask docker # Docker Desktop
73+
brew install podman # Podman (Docker alternative)
6874
```
75+
76+
!!! tip "Using Podman on macOS"
77+
If using Podman, you'll need to set up Docker compatibility. See [:material-docker: Using Podman](../deployment/PODMAN.md) for detailed setup instructions.
6978

7079
=== ":material-microsoft-windows: Windows"
7180

0 commit comments

Comments
 (0)