Skip to content

Update docs for developing on macOS #278

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thimios merged 2 commits into from
Feb 4, 2026
Merged

Update docs for developing on macOS #278

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b67047a
Update docs for developing on macOS
brianzelip Jan 28, 2026
7be02ab
Replace Jabba with mise
brianzelip Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 18 additions & 12 deletions src/content/docs/development/dev.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,24 +12,23 @@ System requirements:
Currently supported platforms for development:

- Linux (although generally only Ubuntu is actually used / tested)
- Mac (x86)
- macOS on Intel (x86_64)
- macOS on Apple silicon (ARM64) _since v4.0.0_

Windows is not supported because of issues building gems with C extensions (such as sassc).
:::note[Apple silicon and ArchivesSpace before v4.0.0]
To install versions of ArchivesSpace prior to v4.0.0 with macOS on Apple silicon, see [https://teaspoon-consulting.com/articles/archivesspace-on-the-m1.html](https://teaspoon-consulting.com/articles/archivesspace-on-the-m1.html).
:::

For Mac (arm) see [https://teaspoon-consulting.com/articles/archivesspace-on-the-m1.html](https://teaspoon-consulting.com/articles/archivesspace-on-the-m1.html).
:::danger[Windows development not supported]
Windows is not supported because of issues building gems with C extensions (such as sassc).
:::

When installing Java OpenJDK is strongly recommended. Other vendors may work, but OpenJDK is
most extensively used and tested. It is highly recommended that you use [Jabba](https://github.com/shyiko/jabba)
to install Java (OpenJDK). This has proven to be a reliable way of resolving cross platform
issues (looking at you Mac :/) that have occured via other means of installing Java.
When installing Java, [OpenJDK](https://openjdk.org/) is strongly recommended. Other vendors may work, but OpenJDK is most extensively used and tested. It is highly recommended that you use a version manager such as [mise](https://mise.jdx.dev/lang/java.html) to install Java (OpenJDK). This has proven to be a reliable way of resolving cross platform issues that have occured via other means of installing Java.

Installing OpenJDK with jabba will look something like:
Installing OpenJDK with mise will look something like:

```bash
# assuming you have jabba installed
jabba install openjdk@1.11.0-2
jabba use openjdk@1.11.0-2
jabba alias default openjdk@1.11.0-2 # [optional] make this the default java
mise use -g java@openjdk-21
```

On Linux/Ubuntu it is generally fine to install from system packages:
Expand All @@ -44,6 +43,13 @@ sudo update-java-alternatives --list
sudo update-java-alternatives --set $version
```

For [Homebrew](https://brew.sh/) users (macOS, Linux), the OpenJDK distribution from Azul has been reported to work:

```bash
# install Java v21 for example
brew install --cask zulu@21
```

If using Docker & Docker Compose install them following the official documentation:

- [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/)
Expand Down