macOS Setup MySQL and Docker

Companion to MySQL Persistence Setup, which describes what this configures and the migration workflow that follows it.

This page covers the macOS-specific parts: installing MySQL 8.4, installing a Docker runtime for the integration test, creating the local database, and putting the environment variables where every tool can see them.

All commands run in Terminal, from any directory unless a cd is shown.

Two choices to make first

This page presents two options at each of steps 1 and 2. Decide both before starting, then follow only the chosen option at each step.

MySQL 8.4 can be installed with Homebrew or from the .dmg installer on mysql.com. Homebrew is the shorter path and uninstalls cleanly, which matters if a MySQL version has to be replaced later. The .dmg installer is the option to use without Homebrew.

A Docker runtime is required by the integration test, because macOS cannot run Linux containers on its own. Docker Desktop is the conventional choice and needs no configuration beyond installing it. Colima runs the same Docker engine in a smaller virtual machine managed from the command line, uses considerably less disk space, and can be deleted and rebuilt in one command. Colima needs two extra environment variables and has no graphical interface.

Steps 3 onwards are the same whichever options are chosen, apart from clearly marked lines.

One-time setup

0. Remove previous MySQL installs

Skip this section on a machine that has never had MySQL. It also resolves a half-finished install that left MySQL unusable.

Remove an install from the .dmg installer. This prompts for the macOS account password:

sudo launchctl bootout system /Library/LaunchDaemons/com.oracle.oss.mysql.mysqld.plist
sudo rm -rf /usr/local/mysql /usr/local/mysql-* /Library/LaunchDaemons/com.oracle.oss.mysql.mysqld.plist /Library/PreferencePanes/MySQL.prefPane
sudo pkgutil --forget com.mysql.mysql; sudo pkgutil --forget com.mysql.launchd; sudo pkgutil --forget com.mysql.prefpane

Remove a Homebrew MySQL of a different major version, including its data directory, which is not compatible across major versions:

brew uninstall mysql && rm -rf /opt/homebrew/var/mysql

Confirm no server is left running. Expected output: nothing.

pgrep -l mysqld

1. Install MySQL 8.4

Neither option adds mysql to PATH, so the command appears missing after an installation that in fact succeeded. Each option ends with the PATH line it needs.

Option A, Homebrew.

brew install mysql@8.4

The install log notes that root has no password. This is expected, and the administrative sign-in in step 4 is mysql -u root with no -p.

mysql@8.4 is keg-only, so Homebrew does not link it. Add this line to ~/.zshrc:

export PATH="/opt/homebrew/opt/mysql@8.4/bin:$PATH"

Option B, the .dmg installer. Download from dev.mysql.com/downloads/mysql, selecting version 8.4 rather than the default latest release, and the ARM build on Apple silicon.

The installer sets a root password during installation, so the administrative sign-in in step 4 is mysql -u root -p. It also registers the server to start at login, so the start command in step 4 and the session commands below are not needed.

Add this line to ~/.zshrc:

export PATH="/usr/local/mysql/bin:$PATH"

2. Install a Docker runtime

Option A, Colima. The docker formula here is the command-line client only, which requires a daemon for Colima to provide.

brew install colima docker

Create the virtual machine. The sizing flags are stored on first creation and apply to every later start.

colima start --cpu 2 --memory 4 --disk 20

The first start downloads a disk image and takes a minute or two. The output ends with done.

Option B, Docker Desktop. Install it, then launch it once from Applications and wait for it to finish starting.

brew install --cask docker

3. Set environment variables

The variables go in ~/.zshenv, not ~/.zshrc. ~/.zshrc is read only by interactive shells, so variables set there are invisible to IDE run configurations and to any non-interactive build. ~/.zshenv is read by every zsh shell.

open -e ~/.zshenv

Append, choosing a development-only password:

export SPRING_DATASOURCE_URL="jdbc:mysql://localhost:3306/fairshare"
export SPRING_DATASOURCE_USERNAME="fairshare_dev"
export SPRING_DATASOURCE_PASSWORD="your-local-password"

Colima only, add these two as well. DOCKER_HOST points Testcontainers at Colima's socket, which is not at the path it probes by default. The second variable applies to the Ryuk cleanup container Testcontainers starts, which needs the socket mounted at the path it holds inside the virtual machine.

export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"
export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock

Load both files into the current tab:

source ~/.zshenv && source ~/.zshrc

Verify. Expected output: three lines, or five with Colima.

printenv | grep -E 'DOCKER_HOST|TESTCONTAINERS|SPRING_DATASOURCE'

Tabs opened before the edit keep their previous environment. Open a new tab, or source the files in each existing tab. This is the most common cause of a later failure that looks like missing configuration.

Confirm the Docker runtime works. Expected output begins with Hello from Docker!.

docker run --rm hello-world

4. Create the database and user

Homebrew only, start the server for this boot:

brew services run mysql@8.4

brew services start instead registers the server to relaunch at login.

Confirm the client is on PATH and the server answers. Expected: 8.4.x from both.

mysql --version && mysql -u root -e "SELECT VERSION();"

Add -p to the second command with the .dmg installer, which sets a root password.

Create the database and user. Run this from the shell prompt, not from inside the mysql> prompt. The shell substitutes the values from step 3 before MySQL sees them. Pasted inside mysql>, the variable names would be taken literally as the username and password.

mysql -u root -e "CREATE DATABASE fairshare; CREATE USER '$SPRING_DATASOURCE_USERNAME'@'localhost' IDENTIFIED BY '$SPRING_DATASOURCE_PASSWORD'; GRANT ALL PRIVILEGES ON fairshare.* TO '$SPRING_DATASOURCE_USERNAME'@'localhost';"

Verify with the credentials the backend will use. There is no space after -p. Expected output includes fairshare.

mysql -u "$SPRING_DATASOURCE_USERNAME" -p"$SPRING_DATASOURCE_PASSWORD" -e "SHOW DATABASES;"

5. Verify the stack

Run the backend verification from the repository root. Testcontainers starts a throwaway MySQL container and never uses the local database or its credentials.

cd backend && ./mvnw --batch-mode clean verify

Expected: BUILD SUCCESS with no test failures or errors. The first run pulls the mysql:8.4 image, about 600 MB, and takes noticeably longer than later runs.

Run the application, which does use the local database through the environment variables:

./mvnw spring-boot:run

Expected log lines: Database JDBC URL [jdbc:mysql://localhost:3306/fairshare], Tomcat started on port 8080, and Started FairShareApplication. A 404 from / is expected unless a root route has been implemented. Stop with Ctrl+C.

Every dev session

Docker is needed for the backend verification. MySQL is needed for running the application. Both commands are safe to repeat; an "already running" warning is harmless.

Choice	Start	End, optional
Colima	colima start	colima stop
Docker Desktop	launch from Applications	quit the application
MySQL via Homebrew	brew services run mysql@8.4	brew services stop mysql@8.4
MySQL via .dmg	already running at login	no action

Stopping frees memory. Leaving both running until shutdown costs nothing else.

Troubleshooting

Symptom	Cause	Fix
command not found: mysql	PATH line missing, or the tab predates it	source ~/.zshrc
Verification fails with Could not find a valid Docker environment	Variables not visible in the shell that launched Maven, or the runtime is not started	source ~/.zshenv, then start Colima or Docker Desktop
Application fails with Access denied for user	The database user does not match the environment variables	Re-run the CREATE USER command in step 4, from the shell prompt
cannot execute binary file when setting variables	The configuration file was executed instead of edited	open -e ~/.zshenv
Docker disk space needs reclaiming, Colima	Images accumulate inside the virtual machine	colima delete, then recreate per step 2