Skip to content

Install Bizuno on macOS

1. Who this guide is for

You’re on a Mac and you want Bizuno running locally — usually for development, customization, or a quick demo. You’re comfortable in Terminal.

Sidebar: you probably want Docker instead. macOS native installs work fine, but the Docker guide is shorter, more reproducible, and survives macOS upgrades cleanly. If you don’t have a specific reason to install PHP, MariaDB, and nginx on the Mac itself, use Docker and skip this page.

Two paths are covered:

  • Homebrew — the “real” install. PHP, MariaDB, and nginx installed from Homebrew and managed as brew services. This is what you want if you plan to develop modules.
  • MAMP / Laravel Herd — the “fast” install. A bundled stack with a GUI. Useful when you want to try Bizuno and move on.

2. Prerequisites

  • macOS 13 (Ventura) or later. 12 works; earlier is unsupported.
  • Apple silicon (M1/M2/M3/M4) or Intel. Both work. Apple-silicon notes appear where they matter.
  • Command Line Tools for Xcode: xcode-select --install if you haven’t.
  • ~1 GB free disk.
  • Homebrew for the Homebrew path: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)".

Apple-silicon caveat

A handful of older PHP extensions (most notably legacy ioncube) don’t have arm64 builds. Bizuno itself doesn’t require any of them, but if you’re bringing third-party modules that do, you’ll hit this. Workarounds, in order of preference:

  1. Ask the module author for an arm64 build.
  2. Use the Docker path (the containers are multi-arch).
  3. Run a Rosetta 2 Terminal and use an x86_64 Homebrew prefix (/usr/local instead of /opt/homebrew).

Skip this section if you’re on Intel or you don’t use ioncube-style modules.

3. Step-by-step install — Homebrew (recommended)

3.1 Install PHP, MariaDB, nginx

brew update
brew install php@8.2 mariadb nginx
brew link --overwrite --force php@8.2

Homebrew may warn that php@8.2 is keg-only. The brew link step puts it on your PATH.

Start the services:

brew services start mariadb
brew services start php@8.2
brew services start nginx

Confirm:

php -v          # should print 8.2.x
mariadb --version
nginx -v

3.2 Harden MariaDB and create the database

sudo mariadb-secure-installation
mariadb -u root

CREATE DATABASE bizuno CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bizuno'@'localhost' IDENTIFIED BY 'CHANGE-THIS-PASSWORD';
GRANT ALL PRIVILEGES ON bizuno.* TO 'bizuno'@'localhost';
FLUSH PRIVILEGES;
EXIT;

3.3 Drop Bizuno into place

Homebrew’s nginx default root is /opt/homebrew/var/www on Apple silicon and /usr/local/var/www on Intel. The commands below assume Apple silicon — adjust if you’re on Intel.

cd /opt/homebrew/var/www
curl -LO https://github.com/bizuno/bizuno/releases/latest/download/bizuno.tar.gz
mkdir bizuno && tar xzf bizuno.tar.gz -C bizuno --strip-components=1
rm bizuno.tar.gz

3.4 Configure nginx

Edit /opt/homebrew/etc/nginx/servers/bizuno.conf (create the servers/ folder if it’s not there, and make sure nginx.conf has include servers/*.conf;):

server {
    listen 8080;
    server_name localhost;
    root /opt/homebrew/var/www/bizuno;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ ^/data/ { deny all; }
}

Port 8080 keeps this out of the way of anything listening on 80. Adjust if you want.

brew services restart nginx

3.5 Confirm PHP-FPM is listening on 9000

lsof -i :9000

Should show php-fpm. If not, brew services restart php@8.2 and re-check.

3.6 Open Bizuno

Navigate to http://localhost:8080/. Install wizard runs. Database host localhost, database bizuno, user bizuno, password as set in 3.2. Finish.

4. Step-by-step install — MAMP or Laravel Herd (fast)

4.1 MAMP

  1. Download MAMP (the free edition) from mamp.info.
  2. Install. Open MAMP.
  3. Preferences → PHP: choose PHP 8.2.
  4. Start Servers. Apache and MySQL come up on ports 8888 and 8889.
  5. Download the Bizuno release zip. Drop the contents into /Applications/MAMP/htdocs/bizuno/.
  6. Open http://localhost:8888/phpMyAdmin/. Create the bizuno database and a user.
  7. Navigate to http://localhost:8888/bizuno/. Install wizard runs.

4.2 Laravel Herd

Herd is free, faster to start, and uses its own PHP instead of Homebrew’s.

  1. Download from herd.laravel.com and install.
  2. Open Herd. Grant it permission to manage /etc/hosts.
  3. Set PHP to 8.2 in Herd’s settings.
  4. Herd watches ~/Herd/ for sites. Place the Bizuno folder there: ~/Herd/bizuno/.
  5. Visit http://bizuno.test/. Herd handles the vhost and the TLS.
  6. Create the database — Herd can use SQLite, but Bizuno needs MariaDB or MySQL. Install DBngin (free, from the same company) or keep MariaDB from Homebrew.
  7. Install wizard runs.

5. First-login walkthrough

Same across all three paths:

  1. Create the admin username, email, and password.
  2. Choose demo data or empty install.
  3. Confirm Tools → System Info.

6. Upgrade path

Homebrew

cd /opt/homebrew/var/www/bizuno
php bin/backup.php
cd ..
curl -LO https://github.com/bizuno/bizuno/releases/latest/download/bizuno.tar.gz
tar xzf bizuno.tar.gz -C bizuno --strip-components=1 \
  --exclude='data' --exclude='myConfig.php'
rm bizuno.tar.gz

Refresh the browser to run migrations.

MAMP / Herd

Same idea: back up the database through phpMyAdmin or DBngin, extract the new release on top of the existing folder (keeping data/ and myConfig.php), refresh the browser.

7. Uninstall / teardown

Homebrew

brew services stop nginx
brew services stop php@8.2
brew services stop mariadb
rm -rf /opt/homebrew/var/www/bizuno
mariadb -u root -e "DROP DATABASE bizuno; DROP USER 'bizuno'@'localhost';"

To remove the stack:

brew uninstall nginx php@8.2 mariadb

MAMP / Herd

Delete the Bizuno folder from the MAMP htdocs or Herd sites folder. Drop the database in phpMyAdmin or DBngin. Uninstall MAMP or Herd from the Applications folder.

8. Troubleshooting

“zsh: command not found: brew” — Homebrew’s path isn’t in your shell init. On Apple silicon: add eval "$(/opt/homebrew/bin/brew shellenv)" to ~/.zshrc. On Intel: /usr/local/bin/brew shellenv.

“502 Bad Gateway.” PHP-FPM isn’t listening on 9000. brew services list, restart php@8.2. Check /opt/homebrew/etc/php/8.2/php-fpm.d/www.conf — the listen = line should be 127.0.0.1:9000.

“macOS blocked this because it can’t verify the developer” on MAMP or Herd. System Settings → Privacy & Security → Open Anyway. Apple tightens Gatekeeper every release; both apps are safe and regularly re-signed.

“Cannot connect to MariaDB” on Apple silicon. Homebrew’s MariaDB on Apple silicon sometimes defaults to the unix socket at /tmp/mysql.sock where older clients expect /opt/homebrew/var/mysql/mysql.sock. Symlink it: ln -s /tmp/mysql.sock /opt/homebrew/var/mysql/mysql.sock. Or set mysql.default_socket in php.ini.

“GD or intl extension missing.” Homebrew’s php@8.2 bottle bundles both, but if you’re using an older keg-only PHP from another tap, they may be absent. brew info php@8.2 confirms. The quickest fix is brew reinstall php@8.2 from the official tap.

“Nothing in the terminal but macOS is blocking nginx’s network access.” System Settings → Network → Firewall → Options — allow incoming connections for nginx. Or turn the firewall off while testing locally.

9. Where to go next

  • Getting Started doc category.
  • If you’re doing module development, install Xdebug via pecl install xdebug and add the breakpoint-friendly settings from the module dev doc.
  • If you want this on a public URL from your Mac (demo for a client), use cloudflared or ngrok rather than exposing your home IP.
  • Ask in Install & Setup → macOS.

This guide is mirrored at bizuno/bizuno-docs/install-macos.md on GitHub. The Markdown file is the source of truth.