Basics · 1
Docker is the only program HERON needs. This page installs it on macOS, Windows or Linux, checks that it works with two commands and fixes the problems people usually meet.
Pick your system below and follow only that part. It takes ten to twenty minutes, most of it waiting for the download.
Docker runs programs in a container: a closed box that carries the program and everything it needs. HERON comes as such a box, called an image. You do not install HERON itself, you ask Docker to run the HERON image, and it behaves the same on a MacBook, a Windows laptop and a Linux server.
An everyday comparison: an image is a sealed lunchbox. Docker is the microwave that heats any lunchbox the same way. You do not need to know how the food was cooked.
When you need this page: before your first site. When you can skip it: if docker --version already prints a version in your terminal.
The terminal is an app called Terminal. It is already on your Mac.
terminal, press Enter.% or $. That is where you type commands.On Windows, HERON works inside WSL, a Linux terminal built into Windows. You install it together with Docker below.
powershell, choose Run as administrator for the install step.You already know where your terminal is: usually Ctrl, Alt and T.
sudo: they ask for your password and run as administrator. Typing the password shows nothing on screen, that is normal.wsl --install, then restart the computer. After the restart, the Ubuntu window asks for a user name and a password: pick any, they are only for this Linux.Install Docker Engine with the official script:
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
Let your user run Docker without sudo:
sudo groupadd -f docker && sudo usermod -aG docker $USER && newgrp docker
The docker group gives the same power as an administrator. It is fine on your own computer and on a server that only you use.
Two commands. Copy them into the terminal one at a time.
docker --version
You see Docker version followed by a number. The number does not matter, the answer does.
docker run --rm hello-world
Docker downloads a tiny test image and prints "Hello from Docker!" with a few lines of explanation. --rm removes the test box afterwards, so nothing is left behind. If you see that greeting, everything is ready.
The same way, Docker runs HERON. This command downloads the stable HERON image and prints its version:
docker run --rm ghcr.io/fmstm/heron:prod --version
The first time it downloads the image, which takes a minute. After that it starts instantly. To create your first site and set up the short heron command, go to Get started.
Docker is installed but not running.
sudo systemctl start docker, and sudo systemctl enable docker to start it with the computer.Linux only: your user is not in the docker group yet.
groups must list docker.Windows sometimes says WSL 2 or virtualization is not available.
wsl --install again.Docker Desktop reserves memory for its Linux box.
More problems, including build errors, are on If something goes wrong.
Docker Desktop is free for personal use, education, open-source projects and small companies. Large companies need a paid Docker subscription. Docker Engine on Linux is free for everyone.
Yes, with Python 3.12 or newer: pip install git+https://github.com/FMSTM/HERON.git@prod. See other ways to run HERON.
It installs one program and keeps its images in its own storage. HERON only sees the folder you run it in. Uninstalling Docker removes everything it downloaded.
Pick a text editor, then create your first site on Get started.