macOS

Run a local Ayakaleaf Pro instance on macOS with Docker Desktop and the Toolkit.

In this section we run Ayakaleaf Pro locally on your Mac with Docker Desktop and the Ayakaleaf Toolkit. The guide uses http://localhost:8080, keeps the data in your home directory, and compiles with TeX Live 2026 in sandboxed containers.

Docker Desktop runs the application, MongoDB, Redis and the TeX Live compiler in a Linux virtual machine. You don’t install MongoDB, Redis or MacTeX on macOS itself.

Use this setup for personal use and local testing. For an always-on shared service, follow the Linux guide and configure HTTPS, backups and access control. The instance is unavailable while the Mac sleeps or Docker Desktop is stopped, see Keep the instance available.

Before you start

You need:

• A macOS version supported by Docker Desktop for Mac.
• Git, Homebrew and GNU sed. The Toolkit uses GNU sed options that the BSD sed built into macOS does not accept.
• Enough resources for both macOS and Docker. For a small local instance, start with 4 CPUs and 8 GB of memory allocated to Docker Desktop. This is a suggested starting point, not a measured minimum.
• At least 40 GB of free storage for a full TeX Live image, plus space for your projects. Check both the free space on the Mac and Docker Desktop’s disk usage limit. Start with one TeX Live version: every additional version needs about as much space again.

The application and TeX Live images are published for arm64 and amd64. On Apple silicon, let Docker pick the native ARM image and do not force platform: linux/amd64.

Steps

Step	What you do
0. Setup Docker Desktop	Install Docker Desktop, check the engine, resources, file sharing and the Docker socket
1. Download the Toolkit	Put GNU sed on the PATH and clone the Toolkit
2. Familiarize yourself with the Toolkit	What differs from Linux when you run the Toolkit scripts
3. Initialize the configuration	Create the files in config/ with bin/init
4. Get Ayakaleaf Pro Images	Switch to the Ayakaleaf Pro image
5. Personalizing your instance	Set the port, site URL and TeX Live image, check the Docker VM kernel, and start
6. Post-installation tasks	Verify compiles and persistence, keep the Mac awake, daily commands
Troubleshooting	Problems seen on macOS and how to check them

Tested configuration

This guide was tested on 3 November 2026 against Toolkit commit 73a9efa with:

Component	Test configuration
Host	Apple silicon, macOS 27.0.1
Docker Desktop	4.88.1
Docker Engine / Compose	29.7.2 / 5.4.0
Docker VM kernel	7.0.12-linuxkit
Application	ghcr.io/ayaka-notes/overleaf-pro:6.3.2
Compiler	ghcr.io/ayaka-notes/texlive-full:2026.1, ARM64
Database / cache	mongo:8.0 / redis:7.4
Compatibility settings	GNU sed on the PATH; the MongoDB GLIBC_TUNABLES override from step 5

The test covered service startup, HTTP responses from the launchpad and login pages, and both LaTeX examples from step 6 submitted through the internal compile service. Both ran in separate ARM64 TeX Live containers, and their PDFs were fetched through the application and checked for the expected text. After bin/stop and bin/start, the MongoDB and Redis test records were still there and both examples compiled again.

Not covered: registering the administrator, the editor in a browser, optional integrations, and access from the LAN or over HTTPS. Complete the account, editor and persistence checks in step 6 on your own installation. Intel Macs, other Docker Desktop versions, Colima, OrbStack and Windows/WSL were not tested.