Prepare the machine

You install the software ZFM is built and run with. At the end of this page the machine is an ordinary Ubuntu host with that software on it, and nothing on it is ZFM yet.

Supported versions

tool	supported
Ubuntu LTS	24.04 LTS, and nothing else
systemd	255+, which 24.04 ships
Node	24.x, the same major version production runs, installed with nvm
npm	whatever ships with Node 24
git	2.43+
gh	2.45+, Ubuntu's own package
Docker	docker.io with the docker-compose-v2 plugin
Caddy	2.7+, from Caddy's own apt repository
Python	3.12, with python3.12-venv, for building the documentation

The deployment guide's Prepare the hosts page states these versions for production. The checks on this page report what the machine has, for you to compare.

Check the operating system

lsb_release -ds                 # the Ubuntu release, as a sentence
systemctl --version | head -1   # the systemd version

Node

The server and the web client are compiled and run with Node. A development machine may carry several projects on different Node versions, so install Node with the version manager nvm:

# install nvm, unless this shell already has it
command -v nvm || curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
# the installer added nvm's hook to ~/.bashrc; a fresh shell is one that has read it
exec bash
nvm install 24
node --version
npm --version

Where nvm put node matters later, so collect it now:

dirname "$(command -v node)"

You'll need that directory when the services are set up.

git

git --version

sudo apt install -y git if it is missing. Then give it your identity, which a fresh machine does not have and the first commit refuses to go without:

git config --global user.name "<your name>"
git config --global user.email "<your email>"

gh

The repository, its issues and its project boards are on GitHub, and the GitHub command-line tool gh is how the work here reaches them. Signing in with it also gives git the credentials it needs to clone the private repository.

gh --version

sudo apt install -y gh if it is missing. Then sign in once:

gh auth login --scopes project   # answer: GitHub.com, HTTPS, log in with a web browser
gh auth setup-git                # git now signs in the same way, for clone, pull and push
gh auth status

The sign-in asks for the project scope as well as the default ones because the backlog lives on project boards, and adding an issue to one is refused without it.

Docker

A dev facility's records live in a database engine, MySQL, and the mail it sends goes to a mail catcher, Mailpit. Both run on this machine as containers, so it needs the Docker engine and its compose plugin. Install Ubuntu's own packages, and put your account in the docker group so that you can run containers without sudo:

sudo apt install -y docker.io docker-compose-v2
sudo usermod -aG docker "$USER"

The group change takes effect at your next login. Log out and back in, then:

docker ps

An empty table is the right answer. A permission error means the new login has not happened yet.

Caddy

Every facility on this machine is served by Caddy at an address of its own, on port 80. Before installing it, check that nothing else on the machine holds that port:

ss -ltn | grep ':80 '    # nothing printed means port 80 is free for Caddy

If another web server holds it, decide now between stopping that server and giving Caddy a different port, which is one line in the Caddyfile written on a later page, http_port 8080 in its global options. If you choose the port, every address these pages write as http://<name>.test becomes http://<name>.test:8080 for you, in the browser and in each facility's settings.

Install Caddy from Caddy's own apt repository, which is the same step on a production host, so the commands and the reason for them are written once: Caddy, in the deployment guide. Stop after caddy version. The directory for facility files comes on a later page here, because a development machine's web server configuration is set up with everything else that is done once.

Python, for the documentation

The documentation is built with MkDocs, which is Python. Ubuntu refuses to install Python packages system-wide, so the toolchain lives in a virtual environment inside the checkout, and the one system package that makes virtual environments is installed now:

sudo apt install -y python3.12-venv

Confirm the machine is ready

lsb_release -ds
node --version
git --version
docker --version
caddy version
python3 --version