Your image, your registry

Publish an image to Docker Hub

You build the site into an image yourself and keep it in a private repository on Docker Hub. An image is a sealed package: the finished pages plus a small nginx web server, ready to run on any machine with Docker.

The order is always the same: an account and a token, sign in on your computer and on the server, build and push the image, then pull and run it on the server. This way suits you when images should live in your own registry, or when GitHub is not an option.

How it goes

1
Account

Sign up at hub.docker.com and create a private repository for the site.
2
Token

Create an access token: it is the password for docker login.
3
Sign in

Once on the computer where you build, once on the server.
4
Build

The strict build makes the dist/ folder of ready pages.
5
Pack and push

docker build packs dist/ into an nginx image, docker push sends it to Docker Hub.
6
Pull and run

The server downloads the new image and starts it instead of the old one. With HERON Agent this step runs by itself.
7
Check

Open the site and the page you changed.

Set up once

1. Create a Docker Hub repository

Sign up at hub.docker.com and create a private repository, for example my-site. On Docker Hub a repository is the shelf where versions of one image are kept.

Free tier: The free Personal plan includes one private repository at the time of writing; more need a paid plan.
Name: The image is called you/my-site, where you is your Docker Hub name.
Where to click: Repositories → Create a repository → name → Visibility: Private → Create.
One repository per site: Ten sites are ten repositories; each keeps its own versions.; No Docker yet? Install it before step 3: Docker on macOS, Windows and Linux.

2. Create two tokens

Account settings → Personal access tokens → Generate. Make two: one for building, one for the server. A token is a long password for one job that you can revoke at any time without touching your account password.

For building: Read and write access: it can push new images.
For the server: Read access only: the server only downloads. If it leaks, nobody can replace your image.
Where to keep them: In a password manager, or in the configurator, which stores them outside the site folder. Never in the site folder and never in git.
Shown once: Docker Hub shows a token only right after you create it. Copy it at once; if you lose it, revoke it and make a new one.
Name them clearly: laptop-build and server-read: later you see at a glance which one to revoke.

3. Sign in on both machines

On your computer with the read-write token, on the server with the read-only one. Docker remembers the sign-in.

docker login -u you

Password prompt: Paste the token, not your account password.
Nothing appears as you paste: That is normal: terminals hide passwords. Paste and press Enter.
Success: Docker answers Login Succeeded. It is remembered until you run docker logout.
On the server: Connect over SSH first, then run the same command with the read-only token.

Build, pack and push

Build the image

Run in the site folder, with your Docker Hub name instead of 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

Build: The strict build makes dist/ and stops on any broken link or empty description.
Pack: docker build packs only dist/ into nginx, by the image recipe from the stable HERON version. Sources, .git and tokens cannot get into the image.
Configurator: When you choose Docker Hub with the helper on, it writes .heron/scripts/publish.sh with these commands. Configurator
Takes: A few seconds for the build, under a minute for packing the first time; later runs reuse the cache.
If it stops: The build names the file and line to fix. Common errors

Check it on your computer

Start the image and open localhost:8080: the home page, a missing page, an old address that should redirect. This is exactly what the server will run, so what you see is what visitors get.

docker run --rm -p 8080:8080 you/my-site:prod

What to look at: The home page, two or three inner pages, localhost:8080/does-not-exist/ should show your 404 page.
Stop it: Press Ctrl+C in the terminal.
Many sites: The prod branch of HERON has scripts/site.sh with a smoke step that checks 200, 404, 301 and 410 for you. Other ways to run HERON

Push it

Send the image to your private repository. After this, any machine signed in with your token can download it.

docker push you/my-site:prod

Tags: prod always points to the latest version. Add a dated tag as well, for example you/my-site:2026-10-19, and you can always go back to it.
Dated tag in one line: docker tag you/my-site:prod you/my-site:2026-10-19 && docker push you/my-site:2026-10-19.
Check: Open the repository on hub.docker.com: the new tag shows with its time.

Run it on the server

First start

Any server with Docker, signed in with the read-only token. Inside the image the site listens on port 8080; the command makes it answer on port 80 and come back after a reboot.

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

Domain and HTTPS: Point the A record of the domain to the server and put HTTPS in front: nginx with certbot, Caddy or Traefik.
Where to get a server: A small VPS from about €5–6 a month, or a free container service with its catches. Where your site can live
Check: docker ps lists my-site as running; the server address in a browser opens the site.
Name: --name my-site lets you address the container in later commands.

Every update

Download the new image, replace the container, start it. One line on the server, a few seconds of work.

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

Roll back: Start the previous dated tag with the same command.
Clean up: Old images take space; docker image prune removes the ones no container uses.
Automatic: The paid HERON Agent does this step for you, below.

Add-on: HERON Agent

Paid

HERON Agent

Pulls every new image from your Docker Hub with your key and updates the container for you. You push, the Agent does the rest on the server.

What it does: Sees a new image, swaps the container, checks that the site opens and rolls back if it does not.
How it connects: Install the Agent on the server, generate a bot key, add your Docker Hub token: Telegram becomes the control panel.
Your bot or ours: Set up your own Telegram bot, or use ours by subscription.
Keys stay with you: The bot key and the read-only Docker Hub token live on your server.
More: HERON Agent

Questions

Why an image and not just files?

The image carries the web server settings with it: real 301 and 410 redirects, caching, gzip, the 404 page. The site behaves the same on your laptop and on the server.

Can I use another registry?

Yes. Any registry that Docker can push to works: GitHub Packages, GitLab, your own. Change the image name in the commands.

How big is the image?

Small: nginx on Alpine Linux plus your pages and images. Most of the size is your photos, already turned into WebP and AVIF.

Do I need HERON Agent?

No. Without it the server is updated with the one command above. The Agent is a paid add-on for those who do not want to log in to the server.