Laravel Sail is an excellent Docker-based development environment, but macOS users may want to switch from Docker to Podman, especially if using rootless Podman for security. In this guide, I’ll show you how to run Sail with Podman, step by step, and highlight common pitfalls with solutions.
Step 1: Install Podman and Set Up a Machine
Install Podman via Homebrew:
brew install podman
Create and start a Podman machine (a lightweight Linux VM):
podman machine init
podman machine start
Check the connection:
podman info
Issue: Initially, Podman may fail to connect, showing Cannot connect to Podman. Please verify your connection.
Solution: Use the correct identity key to SSH into the Podman machine. Test with:
ssh -i ~/.local/share/containers/podman/machine/machine -p
core@127.0.0.1
Step 2: Check Podman Socket and Connections
List Podman system connections:
podman system connection list
Ensure the default machine is set correctly. The socket path will be something like:
ssh://core@127.0.0.1:51011/run/user/501/podman/podman.sock
Issue: Docker commands may fail with Host key verification failed or Permission denied.
Solution: Add the Podman machine key to your SSH known_hosts or use the -i identity option.
Tip: To avoid specifying the SSH connection every time, you can export the environment variables permanently in your shell configuration (~/.zshrc or ~/.bashrc):
export DOCKER_HOST=ssh://core@127.0.0.1:51011
export DOCKER_SSH_KEY=/Users/{Replace with your User Account}/.local/share/containers/podman/machine/machine
This allows Sail and Docker CLI commands to automatically use your Podman machine.
Step 3: Configure Laravel Sail for Podman
Sail uses docker-compose under the hood. Create a .env file in your Laravel project:
APP_PORT=8080
VITE_PORT=5173
FORWARD_DB_PORT=4006
FORWARD_MAILHOG_PORT=2008
FORWARD_MAILHOG_DASHBOARD_PORT=2009
FORWARD_MEILISEARCH_PORT=6008
FORWARD_REDIS_PORT=6009
Issue: Rootless Podman cannot bind ports below 1024.
Solution: Make sure all ports in .env are ≥1024 (e.g., VITE_PORT=5173, APP_PORT=8080).
Step 4: Override the Docker Compose File
Create docker-compose.override.yml in your project root:
version: '3'
services:
laravel.test:
ports:
- '${APP_PORT:-8080}:80'
- '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
This ensures Sail reads the correct ports from .env.
Step 5: Bring Down Old Containers
Before starting Sail with Podman, remove any existing containers:
./vendor/bin/sail down -v
Issue: Cached containers may still try to bind old ports (like 1007).
Solution: The -v flag removes volumes and forces Sail to reload the updated .env and override files.
Step 6: Start Sail
Start Sail as usual:
./vendor/bin/sail up -d
Verify the ports:
docker-compose ps
You should see something like:
0.0.0.0:8080->80/tcp
0.0.0.0:5173->5173/tcp
Now your Laravel app and Vite dev server run on safe, unprivileged ports with rootless Podman.
Step 7: Common Issues and Fixes
Step 8: Success!
Your Laravel Sail setup now runs completely on Podman, without needing Docker Desktop, using rootless ports, and with all services (MySQL, Redis, Meilisearch, Mailhog, Vite) running correctly.
This workflow ensures Podman compatibility on macOS, addresses common pitfalls with rootless port restrictions, and guarantees Laravel Sail runs smoothly in a Docker-free environment.
More...
Step 1: Install Podman and Set Up a Machine
Install Podman via Homebrew:
brew install podman
Create and start a Podman machine (a lightweight Linux VM):
podman machine init
podman machine start
Check the connection:
podman info
Issue: Initially, Podman may fail to connect, showing Cannot connect to Podman. Please verify your connection.
Solution: Use the correct identity key to SSH into the Podman machine. Test with:
ssh -i ~/.local/share/containers/podman/machine/machine -p
core@127.0.0.1
Step 2: Check Podman Socket and Connections
List Podman system connections:
podman system connection list
Ensure the default machine is set correctly. The socket path will be something like:
ssh://core@127.0.0.1:51011/run/user/501/podman/podman.sock
Issue: Docker commands may fail with Host key verification failed or Permission denied.
Solution: Add the Podman machine key to your SSH known_hosts or use the -i identity option.
Tip: To avoid specifying the SSH connection every time, you can export the environment variables permanently in your shell configuration (~/.zshrc or ~/.bashrc):
export DOCKER_HOST=ssh://core@127.0.0.1:51011
export DOCKER_SSH_KEY=/Users/{Replace with your User Account}/.local/share/containers/podman/machine/machine
This allows Sail and Docker CLI commands to automatically use your Podman machine.
Step 3: Configure Laravel Sail for Podman
Sail uses docker-compose under the hood. Create a .env file in your Laravel project:
APP_PORT=8080
VITE_PORT=5173
FORWARD_DB_PORT=4006
FORWARD_MAILHOG_PORT=2008
FORWARD_MAILHOG_DASHBOARD_PORT=2009
FORWARD_MEILISEARCH_PORT=6008
FORWARD_REDIS_PORT=6009
Issue: Rootless Podman cannot bind ports below 1024.
Solution: Make sure all ports in .env are ≥1024 (e.g., VITE_PORT=5173, APP_PORT=8080).
Step 4: Override the Docker Compose File
Create docker-compose.override.yml in your project root:
version: '3'
services:
laravel.test:
ports:
- '${APP_PORT:-8080}:80'
- '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
This ensures Sail reads the correct ports from .env.
Step 5: Bring Down Old Containers
Before starting Sail with Podman, remove any existing containers:
./vendor/bin/sail down -v
Issue: Cached containers may still try to bind old ports (like 1007).
Solution: The -v flag removes volumes and forces Sail to reload the updated .env and override files.
Step 6: Start Sail
Start Sail as usual:
./vendor/bin/sail up -d
Verify the ports:
docker-compose ps
You should see something like:
0.0.0.0:8080->80/tcp
0.0.0.0:5173->5173/tcp
Now your Laravel app and Vite dev server run on safe, unprivileged ports with rootless Podman.
Step 7: Common Issues and Fixes
| Cannot connect to Podman | Cannot connect to Podman socket | Ensure machine is started and SSH connection works with -i identity key |
| Host key verification | Host key verification failed | Add Podman machine key to ~/.ssh/known_hosts or use ssh -i ... |
| Rootless port binding | rootlessport cannot expose privileged port 1007 | Make sure all ports ≥1024 in .env (APP_PORT, VITE_PORT) |
| Cached containers | Containers still try old ports | Run ./vendor/bin/sail down -v to remove old containers and volumes |
Step 8: Success!
Your Laravel Sail setup now runs completely on Podman, without needing Docker Desktop, using rootless ports, and with all services (MySQL, Redis, Meilisearch, Mailhog, Vite) running correctly.
This workflow ensures Podman compatibility on macOS, addresses common pitfalls with rootless port restrictions, and guarantees Laravel Sail runs smoothly in a Docker-free environment.
More...