From zero to a live site

Get started

Q: Do I need to know how to code?

No. Pages are text files with a few simple marks, and the configurator explains every setting next to its field. Code is needed only for your own theme.

Q: What is the stable image?

The version of HERON that is tested and recommended for live sites. Other versions are listed in the docs .

Q: Can I move my WordPress site?

Yes. Move the texts into pages and list the old addresses in redirect_from: . HERON writes real redirects, so search rankings move with the pages.

Q: Where is the documentation?

On this site, in the repository and inside the image. heron docs prints the documentation for exactly the version you run.

Q: Is it free?

Yes. HERON is open source under AGPL-3.0. Hosting static files can be free too.

You need Docker, a text editor and ten minutes. At the end you have a working site on your computer, and you choose how to store and publish it. Never used a terminal or Docker? Start with the basics: install Docker on macOS, Windows or Linux, pick an editor, learn Markdown, then come back here.

All commands use the stable image of HERON¹ from the official registry². An image is a ready package with HERON and its documentation inside, so nothing else needs installing. Other ways to run HERON are described below, in a separate section.

What you need

Docker

Docker Desktop on macOS and Windows, Docker Engine on Linux. It runs HERON in a closed box, so your computer stays clean.

A text editor

Any will do, from VS Code to Notepad. Pages are plain text files in Markdown, a simple way to mark headings and lists.

Git, to store the site

Recommended: it keeps every change, and GitHub builds the image of the site from it by itself.

A domain, when you publish

Not needed to start: the new site has a placeholder you replace in the configurator.

Set up the heron command once

Every command on this site starts with heron. It is a short name for the full Docker command: it downloads the stable image, shows it only the current folder and runs as your user, so the new files belong to you. Set it up once, and every command below can be copied as is.

macOS and Linux

Add the short name to your shell profile and reload it. Works in zsh, the default on macOS, and in bash, the default on most Linux systems. Open the Terminal app, paste the line and press Enter.

echo 'heron() { docker run --rm -it -p 8000:8000 -v "$PWD":/site -w /site --user $(id -u):$(id -g) ghcr.io/fmstm/heron:prod "$@"; }' >> ~/.zshrc && source ~/.zshrc && heron --version

What you should see: The last command prints the HERON version, branch and build time. The first run downloads the image, which takes a minute.; bash instead of zsh? Replace ~/.zshrc with ~/.bashrc in both places. Not sure which one you have? echo $SHELL prints it.
Port 8000: Lets you open the preview at localhost:8000. If another program uses it, change both numbers, for example to -p 8001:8000.
Docker must be running: On macOS start Docker Desktop first: the whale icon in the menu bar means it is ready.
Nothing breaks: The line only adds a short name; delete it from the profile file to remove it.

Windows

Use WSL, the Linux terminal built into Windows, and follow the macOS and Linux step there. Docker Desktop uses WSL anyway, so you need it once.

wsl --install

Where to type it: Open PowerShell as administrator, run the command, restart the computer.
Then: Open «Ubuntu» from the Start menu, create a user name and password, and run the macOS and Linux line there.
Docker Desktop: In its settings, Resources → WSL integration, turn on your Ubuntu.
Why WSL: File permissions and paths work the same way as on a server, so every command on this site works as written.
Your files: Keep the site folder inside the Ubuntu home folder, it builds faster there than on drive C.

Docker on Windows step by step →

Update HERON

Download the latest stable image. Your sites keep building with the version they name in site.yaml, so updating HERON never changes a site by surprise.

docker pull ghcr.io/fmstm/heron:prod && heron --version

How often: When a release note says something useful for you; there is no need to update every week.
Which version a site wants: The first line of site.yaml, for example heron: ">=0.1,<0.2".
What changed: Releases are listed in the news and in the CHANGELOG of the repository.
Pip users: Run the same pip install line again to update.

Your first site in five steps

Five steps from an empty folder to a finished site on your computer. Every step is one command with a clear result. The configurator and the pages can be finished later.

Create the site

The command takes the stable HERON image, and the image creates the my-site folder: the content structure, demo pages, a theme and the settings file site.yaml. The demo pages are a sample you replace with your own.

heron new my-site -y && cd my-site && ls

What you get: site.yaml for settings, content/ for the texts of the pages, media/ for photos and video, theme/ for the look. Every folder has a note heron-readme.md: what it holds and what you can change.
Folder name: my-site is just an example, call it anything. The address and name of the site are set in the configurator, not by the folder name.
Questions or `-y`: Without the -y flag HERON asks a few questions in the terminal: the language you prefer to work in, the name, the domain, the languages of the site and the main one. Enter takes the suggestion in brackets. With -y there are no questions and the defaults are used. Either way, everything can be filled in and changed in the configurator at the next step.; What a site folder holds

Set it up in the configurator

The configurator is a questionnaire. You fill in the name and domain, the reference data (contacts, company details, who you are: a company, a doctor, a lawyer, a private person), and choose a theme, languages and the way to publish. The configurator fits the folder structure to your project and saves the answers to site.yaml.

heron setup .

About you: What the company or person does, address, phone, opening hours. HERON builds search markup, the sitemap and llms.txt from it.
Look and languages: The theme and the languages of the site: one or several. Each language gets its own folder of pages.
Publishing: Choose GitHub and turn on the automatic build, and the configurator adds the image build file for GitHub.
Skip freely: An empty field breaks nothing; the build report reminds you what is left.; The configurator, field by field

Fill the pages

Open the site folder in your editor. In content/ there is the folder of your language with the page files. Open the home page file: at the top is its description for search engines (title, description, h1), below are the blocks of the page, each starting with a heading ## Title {#anchor}. Replace the texts with yours and save.

title and description: The line and the text under it in search results: up to 60 and up to 155 characters.
h1: The big heading on the page itself, not a copy of the title.
A new page: Copy any page file under a new name, for example services.md, and change the text. The file name becomes the address of the page.
Photos: Put a file into media/ and refer to it from the page. HERON makes the sizes for every screen.
With an AI agent: An agent can fill the pages from your brief; it does not touch the theme or the structure. How to hand it to an agent; Markdown in ten minutes; Pages and content

Preview

Start the preview and open localhost:8000 in your browser. The site rebuilds on every save, and a change shows a second later.

heron serve .

Stop it: Press Ctrl+C in the terminal.
The report: The terminal lists what to fix: an empty description, a broken link, a picture without a caption.
From a phone: A phone on the same Wi-Fi opens your computer's address with :8000.; Commands in the terminal

Build the final version

The final build opens the site to search engines and turns every warning into an error, so a broken link never reaches visitors. The result is the dist/ folder with the finished site; the image is built from it too.

heron build . --env prod --strict && ls dist

Result: The dist/ folder is the whole site, ready for any hosting.; An error? It names the file, the line and what to do. Common errors
Next: Choose how to store and publish the site, below.

Ready files or an image

Ready files

The dist/ folder is the whole site: pages, pictures, sitemap, llms.txt.
Any hosting works, including free GitHub Pages and Cloudflare Pages with your domain and HTTPS.
No server to look after.
Every update: build again and copy.

An image of the site

The whole site together with a small web server; runs on any machine with Docker.
Stored on GitHub (built by itself when you send changes to git), on Docker Hub or in your own registry.
A server takes the new image with one command; with HERON Agent (paid), by itself.
Real 301 and 410 redirects, several sites on one server.

Choose how to store and publish

There are three ways today, and more will come. Pick a tab: the steps, commands and full guide change with it. The site folder stays the same whatever you choose.

gitDocker HubReady files

You keep the site in a repository on GitHub. After the first setup you edit a page and send the changes, and GitHub Actions builds the image, checks it and puts it into GitHub Packages by itself. No separate account for images is needed.

git init && git add . && git commit -m "First version" && git branch -M main && git remote add origin https://github.com/you/my-site.git && git push -u origin main

Repository. Sign up at github.com and create an empty repository named my-site. Private keeps drafts hidden; GitHub Pages on the free plan needs a public one.
First send. Run the command above with your name instead of you. Git and GitHub from zero
Build. The configurator adds the file .github/workflows/image.yml. After sending, open the Actions tab on GitHub to watch the build and the check.
Every update. Edit a page file, then git add . && git commit -m "…" && git push. The fresh image builds by itself.
Where to publish. A server takes the new image with one command: docker pull and a run in place of the old one. Or publish the ready files on GitHub Pages and do without a server.
Paid add-on. HERON Agent updates the site on your server after every send by itself.

Full guide: storing in git and building the image →

You edit a .md pageYour step
git commit and git pushYour step
GitHub Actions builds the siteAutomatic
It checks that the site opensAutomatic
The image goes to the registryAutomatic
The server takes the new image^¹Your step
You open the site and check itYour step

Your step Automatic · 3 of 7 steps run by themselves

¹ With HERON Agent (paid) this step runs by itself: the Agent pulls the new image, swaps the container and rolls back if the check fails. On GitHub Pages it is automatic anyway.

You build the image yourself and keep it in a private repository on Docker Hub. The server pulls it from there.

docker login -u you && heron build . --env prod --strict && curl -fsSL https://raw.githubusercontent.com/FMSTM/HERON/prod/Dockerfile.site | docker build -t you/my-site:prod -f - dist && docker push you/my-site:prod

Account. Sign up at hub.docker.com and create a private repository named my-site.
Tokens. Account settings → Personal access tokens. One with read and write access for your computer, one with read access only for the server. A token is the password for docker login; keep it out of the site folder and out of git.
Sign in. docker login -u you once on your computer and once on the server.
Build and push. Run the command above, with your Docker Hub name instead of you.
On the server. Pull the image and start it, the command is below. Every update: the same command.
Add-on. HERON Agent (paid) pulls each new image with your key and updates the container by itself.

docker pull you/my-site:prod && docker rm -f my-site && docker run -d --name my-site -p 80:8080 --restart unless-stopped you/my-site:prod

Full guide: images and Docker Hub →

Docker Hub account and a tokenYour step
Sign in with the token: here and on the serverYour step
You build the siteYour step
You pack it into an image and push itYour step
The server pulls and runs the image^¹Your step
The new site is liveAutomatic
You open the site and check itYour step

Your step Automatic · 1 of 7 steps runs by itself

¹ With HERON Agent (paid) the last steps run by themselves: it pulls the image from your Docker Hub with your key and updates the container.

The most manual way: you build the site, check it on localhost and copy the files to the hosting yourself, on every update. Runs anywhere, from shared hosting to free GitHub Pages.

heron build . --env prod --strict && ls dist

Build. The command above makes the dist/ folder: every page, image, sitemap and llms.txt.
Check locally. Open the finished site at localhost:8080 before it goes live, the command is below.
Copy. To a VPS with rsync, to shared hosting through FTP or the file manager.
Free hosting. GitHub Pages or Cloudflare Pages take the dist/ folder with your domain and HTTPS, no server at all.
Domain and HTTPS. Once: an A record with the server address, then a free certificate.
Every update. Build and copy again: nothing happens on its own.

docker run --rm -p 8080:8080 -v "$PWD/dist:/usr/share/nginx/html:ro" nginxinc/nginx-unprivileged:1.27-alpine

rsync -avz --delete dist/ you@my-server:/var/www/my-site/

Full guide: ready files and where to host them →

You build the siteYour step
You check it on localhostYour step
You copy dist/ to the hosting^¹Your step
Once: domain and HTTPSYour step
The site is liveAutomatic
Next update: build and copy againYour step

Your step Automatic · 1 of 6 steps runs by itself: every update is by hand

¹ Where: shared hosting or a VPS (from about €5 a month), or free on GitHub Pages and Cloudflare Pages.

Other ways to run HERON

The main path on this site is the Docker image. If it does not suit you, there are two more ways. The result is the same with any of them: the same folder, the same build, the same site, and you can switch later.

Docker image

Recommended. HERON and its documentation come in one stable image, nothing to install besides Docker. Your computer stays clean: delete the image, and nothing is left behind.

docker run --rm -it -v "$PWD":/site -w /site --user $(id -u):$(id -g) ghcr.io/fmstm/heron:prod new my-site -y

Good for: Everyone: one command on macOS, Linux and Windows with WSL.
What the parts mean: -v "$PWD":/site shows HERON only the current folder; --user makes you the owner of the new files.
Same as on GitHub: GitHub Actions builds your site with the same image, so «works on my computer» means works there too.
Docs inside: heron docs reads the documentation of exactly this image, offline.

Python

Install HERON as a program with pip, and the heron command works directly, without Docker.

pip install git+https://github.com/FMSTM/HERON.git@prod && heron new my-site -y

You need: Python 3.12 or newer. python3 --version shows yours.
Good for: Machines without Docker, and quick previews: heron serve . rebuilds on every save.
Tip: Install it in a virtual environment so it does not mix with other Python programs: python3 -m venv .venv first.

A copy of the stable branch

Clone the prod branch of the repository and work through its scripts. One script builds, packs, checks and publishes any number of sites.

git clone -b prod https://github.com/FMSTM/HERON.git && cd HERON && ./scripts/site.sh my-site new ../my-site

Commands: ./scripts/site.sh my-site build, then image, smoke for a test run and push to the registry.
Settings: Each site has its own file in env/, based on env/.env.example: paths, image name, registry.
Good for: Several sites on one machine and anyone who wants to read or change HERON itself.
Keep it fresh: git pull in the HERON folder brings the latest stable version.

Questions

Do I need to know how to code?

No. Pages are text files with a few simple marks, and the configurator explains every setting next to its field. Code is needed only for your own theme.

What is the stable image?

The version of HERON that is tested and recommended for live sites. Other versions are listed in the docs.

Can I move my WordPress site?

Yes. Move the texts into pages and list the old addresses in redirect_from:. HERON writes real redirects, so search rankings move with the pages.

Where is the documentation?

On this site, in the repository and inside the image. heron docs prints the documentation for exactly the version you run.

Is it free?

Yes. HERON is open source under AGPL-3.0. Hosting static files can be free too.