Installing Pengin Pi 3 on macOS

This guide covers installing and running Pengin Pi 3 on macOS. Both Apple Silicon (M1/M2/M3/M4) and Intel-based Macs are supported.

Prerequisites

Before starting, ensure you have:

1. Xcode Command Line Tools

Open your Terminal app and install the command-line developer tools:

xcode-select --install

(If a prompt appears, click Install and wait for it to finish).

2. Homebrew

If Homebrew is not already installed on your Mac, run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Method 1: The Automated Installer (deploy_mac.sh)

Pengin Pi 3 includes a dedicated macOS installer script (deploy_mac.sh) that automates installing Docker Desktop via Homebrew, setting up system requirements, and configuring the container stack.

Important: Do NOT run this script with sudo. Homebrew deliberately refuses to run as root. Run it as your normal user account; the script will prompt for your password only for the specific steps that require elevated permissions.

Steps:

1. Clone the repository:

   git clone https://code.penginopensource.org/pengin-open-source/pengin-pi-3.git
   cd pengin-pi-3
   

2. Make the script executable and run it:

   chmod +x deploy_mac.sh
   ./deploy_mac.sh
   

3. Follow the interactive prompts:

   • The script verifies Homebrew and installs Docker Desktop if it is not already installed.
   • If Docker Desktop was just installed, it launches the app and waits for the Docker engine to initialize.
   • It will guide you through setting up your initial .env file and bringing up the stack.

Method 2: Lightweight Local Dev Stack

If you already have Docker Desktop installed and running on your Mac, you can start the development stack in seconds without running the full installer:

1. Clone the repository and enter the directory:

   git clone https://code.penginopensource.org/pengin-open-source/pengin-pi-3.git
   cd pengin-pi-3
   

2. Build and start the containers:

   docker compose -f docker-compose.dev.yml up --build
   

Verifying Your Setup

Once the containers are running:

• Web Application: http://localhost:8000/
• Documentation Wiki: http://localhost:8000/docs/
• Superuser / Admin: http://localhost:8000/admin/

To create your first admin user inside the container:

docker compose exec web python manage.py createsuperuser

macOS Notes & Troubleshooting

• "Cannot connect to the Docker daemon": Make sure Docker Desktop is running in your macOS menu bar (green icon).
• Apple Silicon (M1/M2/M3/M4): In Docker Desktop Settings -> General, make sure "Use Rosetta for x86/amd64 emulation on Apple Silicon" is checked for optimal container performance.
• Port 8000 Conflicts: If port 8000 is occupied by another application, identify it with:

  lsof -i :8000
  

Related Documentation

• Install — Return to the main Installation Guide
• Deployment — Full docker-compose stack and service details
• Configuration — Environment variables and .env reference
• Quickstart — Creating your first slug page and roles