DEV Community

Bilal Haidar
Bilal Haidar

Posted on

Running Laravel Sail with Podman on macOS: A Step-by-Step Guide

#laravel #php #docker #podman

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
Enter fullscreen mode Exit fullscreen mode

Create and start a Podman machine (a lightweight Linux VM):

podman machine init
podman machine start
Enter fullscreen mode Exit fullscreen mode

Check the connection:

podman info
Enter fullscreen mode Exit fullscreen mode

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 <port> core@127.0.0.1

Step 2: Check Podman Socket and Connections

List Podman system connections:

podman system connection list
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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}'
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Verify the ports:

docker-compose ps
Enter fullscreen mode Exit fullscreen mode

You should see something like:

0.0.0.0:8080->80/tcp
0.0.0.0:5173->5173/tcp
Enter fullscreen mode Exit fullscreen mode

Now your Laravel app and Vite dev server run on safe, unprivileged ports with rootless Podman.

Step 7: Common Issues and Fixes

Issue Error Solution
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.

Top comments (0)