Setting up Podman for Supabase on macOS

This guide walks you through setting up Podman as a Docker alternative on macOS for Supabase development. Podman is a daemonless container engine that's compatible with Docker commands and provides enhanced security.

Prerequisites

• macOS (Intel or Apple Silicon)
• Homebrew package manager installed
• Terminal access
• Basic familiarity with command line operations

Why Podman for Supabase?

Podman offers several advantages over Docker:

• Daemonless architecture: No background daemon required
• Rootless containers: Enhanced security by running without root privileges
• Docker compatibility: Drop-in replacement for Docker commands
• Lightweight: Lower resource usage compared to Docker Desktop

Step 1: Install Podman and Related Tools

Install Podman, Podman Desktop (GUI), and Podman Compose using Homebrew:

brew install podman podman-desktop podman-compose

What this installs:

• podman: The core container engine
• podman-desktop: Optional GUI for managing containers
• podman-compose: Docker Compose compatibility layer

Step 2: Initialize Podman Machine

Podman on macOS requires a virtual machine to run Linux containers. Initialize it:

podman machine init

What happens:

• Downloads a lightweight Linux VM image
• Configures the VM for container operations
• Sets up networking and storage

Common options:

• --cpus 4: Set number of CPU cores (default: 1)
• --memory 4096: Set memory in MB (default: 2048)
• --disk-size 50: Set disk size in GB (default: 10)

Example with custom resources:

podman machine init --cpus 4 --memory 4096 --disk-size 50

Step 3: Start Podman Machine

Start the Podman virtual machine:

podman machine start

Verification: Check if the machine is running:

podman machine list

You should see output similar to:

NAME                     VM TYPE     CREATED      LAST UP            CPUS        MEMORY      DISK SIZE
podman-machine-default*  qemu        2 hours ago  Currently running  1           2.147GB     10.74GB

Step 4: Configure Docker Compatibility

For Supabase CLI compatibility, set up Docker socket emulation:

export DOCKER_HOST=unix:///var/run/docker.sock

Make it permanent: Add this to your shell profile (~/.zshrc for zsh or ~/.bash_profile for bash):

echo 'export DOCKER_HOST=unix:///var/run/docker.sock' >> ~/.zshrc
source ~/.zshrc

Alternative method: You can also create an alias for docker commands:

alias docker=podman

Step 5: Start and Configure Podman Desktop

Podman Desktop provides a GUI interface and is required for the Supabase CLI to properly detect the Docker daemon. Start and configure it:

Launch Podman Desktop

1. Start the application:

   • Open Launchpad or Applications folder
   • Launch "Podman Desktop"
   • Or use Spotlight: Cmd + Space, then type "Podman Desktop"

2. Alternative command line launch:

   open -a "Podman Desktop"

Configure Docker Compatibility

Critical Step: Enable Docker compatibility in Podman Desktop for Supabase CLI to work properly.

1. Open Preferences:

   • Click on "Podman Desktop" in the menu bar
   • Select "Preferences" or use Cmd + ,

2. Navigate to Docker Compatibility:

   • Click on "Preferences" or "Settings" tab
   • Look for "Docker Compatibility" or "Docker" section

3. Enable Docker Socket:

   • Check "Enable Docker socket compatibility"
   • Check "Start Docker API on Podman machine start"
   • Check "Docker compatibility mode"

4. Apply Settings:

   • Click "Apply" or "Save"
   • The application may prompt to restart the Podman machine

Verify Podman Desktop Setup

1. Check Dashboard:

   • You should see your Podman machine listed as "Running"
   • The status should show green indicators

2. Verify Docker socket:

   ls -la /var/run/docker.sock

   This should show the Docker socket is available.

3. Test Docker compatibility:

   docker version

   This should return Podman version information without errors.

Keep Podman Desktop Running

Important: Keep Podman Desktop running in the background while developing with Supabase. The Supabase CLI requires the Docker daemon detection that Podman Desktop provides.

• Podman Desktop can run minimized to the system tray
• It will automatically start the Podman machine when needed
• You can set it to start automatically at login in Preferences

Install the Supabase CLI using Homebrew:

brew install supabase/tap/supabase

Verify installation:

supabase --version

Navigate to your project directory and initialize Supabase:

cd /path/to/your/project
supabase init

What this creates:

• supabase/ directory with configuration files
• supabase/config.toml: Main configuration file
• supabase/seed.sql: Database seed file
• Various migration and function directories

Step 8: Start Supabase Services

Start the local Supabase development environment:

supabase start

What happens:

• Downloads required Docker images (PostgreSQL, PostgREST, etc.)
• Starts all Supabase services in containers
• Sets up local database with default schema
• Provides local URLs for API and Dashboard

Expected output:

Started supabase local development setup.

         API URL: http://localhost:54321
     GraphQL URL: http://localhost:54321/graphql/v1
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
      JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
        anon key: [long-jwt-token]
service_role key: [long-jwt-token]

Troubleshooting

Podman Machine Won't Start

Issue: Machine fails to start or shows connection errors.

Solutions:

1. Check if virtualization is enabled:

   sysctl kern.hv_support

   Should return kern.hv_support: 1

2. Restart the machine:

   podman machine stop
   podman machine start

3. Recreate the machine:

   podman machine rm
   podman machine init
   podman machine start

Docker Compatibility Issues

Issue: Supabase CLI shows "Cannot connect to Docker daemon" errors.

Solutions:

1. Ensure Podman Desktop is running:

   • Check that Podman Desktop is open and the machine shows as "Running"
   • Verify Docker compatibility is enabled in Podman Desktop preferences

2. Ensure DOCKER_HOST is set:

   echo $DOCKER_HOST

3. Create Docker socket link (if needed):

   sudo ln -sf /var/run/podman/podman.sock /var/run/docker.sock

4. Use Podman directly:

   alias docker=podman

5. Restart Podman Desktop:

   • Quit Podman Desktop completely
   • Restart the application
   • Wait for the machine to show "Running" status

Port Conflicts

Issue: Supabase services fail to start due to port conflicts.

Solutions:

1. Check what's using the ports:

   lsof -i :54321
   lsof -i :54322
   lsof -i :54323

2. Stop conflicting services or change Supabase ports in supabase/config.toml

Performance Issues

Issue: Containers run slowly or consume too much memory.

Solutions:

1. Increase VM resources:

   podman machine stop
   podman machine rm
   podman machine init --cpus 4 --memory 4096
   podman machine start

2. Prune unused containers and images:

   podman container prune
   podman image prune

Useful Commands

Podman Machine Management

# List machines
podman machine list

# Stop machine
podman machine stop

# SSH into machine
podman machine ssh

# Remove machine
podman machine rm

Container Management

# List running containers
podman ps

# View logs
podman logs <container-name>

# Stop all containers
podman stop $(podman ps -q)

# Remove all containers
podman rm $(podman ps -aq)

Supabase Commands

# Stop Supabase services
supabase stop

# Reset database
supabase db reset

# Generate TypeScript types
supabase gen types typescript --local

# View logs
supabase logs

Best Practices

1. Resource Allocation: Allocate sufficient CPU and memory to the Podman machine based on your project needs.

2. Regular Updates: Keep Podman and Supabase CLI updated:

   brew upgrade podman supabase

3. Clean Up: Regularly clean up unused containers and images to free up disk space.

4. Environment Variables: Use a .env file for project-specific environment variables.

5. Version Control: Add supabase/.temp/ to your .gitignore file.

Next Steps

• Explore the Supabase Studio at http://localhost:54323
• Set up your database schema using migrations
• Configure authentication and RLS policies
• Integrate with your frontend application

Additional Resources

• Podman Documentation
• Supabase Local Development
• Podman Desktop

---

This guide was created for macOS users looking to use Podman as a Docker alternative for Supabase development. For Docker-specific setup, refer to the official Supabase documentation.