Caddy: a real web server that stays readable

A clerk behind a small window listens to a queue of visitors (a laptop, a phone and a small robot), each holding a request note, with a looping arrow above the window. — A web is a clerk at a window: wait, read the request, hand back the page, and wait again.

A web server in one shell script

Here is a complete web server written in . It opens a , reads the , it, and sends back as a proper . Twenty lines, no , and a browser cannot tell the difference.

Two do the heavy lifting. (nc) speaks the , and makes a so the answer we write can be fed back into the connection nc is holding open.

server.sh

#!/bin/bash

PORT=8084
PIPE=simple-web-server-pipe

rm -f "$PIPE"
mkfifo "$PIPE"

response() {
    read -r method path _
    echo "[$(date)] $method $path" >&2
    index=$(cat index.html)
    printf 'HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\nConnection: close\r\n\r\n%s' \
      "$index"
}

while true; do
    response < "$PIPE" | nc -l "$PORT" > "$PIPE"
done

Line by line

PORT=8084The port to listen on. Anything above 1024 works without administrator rights, and 8084 is unlikely to collide with something you already run.
PIPE=simple-web-server-pipeThe name of the file. It appears in the folder like an ordinary file, but nothing is ever stored in it — it only passes between two commands.
mkfifo "$PIPE"Creates the named pipe (a FIFO). The line above deletes any leftover from a previous run, because mkfifo refuses to an existing file.
read -r method path _Reads the first line of the and splits it into method, and the rest. Everything after it — the browser's — is ignored by this server.
echo "[$(date)] $method $path" >&2Prints a log line. The sends it to so it appears on your instead of being sent to the browser as part of the page.
index=$(cat index.html)Reads index.html from the into a . This is why the server must be started from the folder that holds the file.
printf 'HTTP/1.1 200 OK\r\n…'Writes the response: a , the content type, a header saying the connection ends here, then a and the page. The blank line is what separates headers from content, and demands carriage-return-and-newline on every one of them.
response < "$PIPE" | nc -l "$PORT" > "$PIPE"The trick that makes it work. nc takes the response written by response before the | and sends it to the browser, and writes the browser's request into the FIFO file ($PIPE). response reads the request from that FIFO, so the two halves feed each other.
while true; do … doneThe . nc handles one connection and exits, so without this the server would answer a single visitor and stop.

Why a pipe, and not just a variable

The request has to reach the before the function's answer can reach nc — a circle. A shell pipeline only flows one way, so the named pipe closes the loop: the response goes into nc through the pipeline, and the request comes back out through the FIFO. It is the smallest way to make two commands talk to each other in both directions.

Run it yourself

Save the as server.sh, put an index.html next to it, and start it. Leave that terminal running and use a second one to make requests.

terminal

# 1. create an index.html in the same folder
echo '<h1>Hello</h1>' > index.html

# 2. save the script above as server.sh and start it
bash server.sh

# 3. open it in a browser (or check from a second terminal)
open http://localhost:8084
curl http://localhost:8084

Watch the first terminal while you reload the browser: one log line appears per request. Stop the server with , and delete the pipe file afterwards if it is still there. On the nc command may need an extra -p before the port; on the shipped with the system works as written.

Learn the shell commands used here

What actually travels down the wire

Open the connection and you find you could have typed yourself. This is the whole reason the shell server is possible — and the reason you can a web problem by reading, rather than guessing.

The request the browser sends

request

GET / HTTP/1.1
Host: localhost:8084
User-Agent: Mozilla/5.0
Accept: text/html

The first line is the only part our server reads: the method ( means fetch, means send something), the path, and the .
says which site is wanted. One server can hold hundreds of domains on one address, and this is how it tells them apart.
The rest are the browser introducing itself: what it is, what formats it can read, what languages it prefers. A server may use them or ignore them.

The response the server sends

response

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Connection: close

<h1>Hello</h1>

The : the protocol version and a saying how it went. means the succeeded.
tells the browser how to read what follows. Send with the wrong type and the browser will show your as text instead of a page.
The part is not optional in practice. Without it, any non-English text is likely to arrive as garbled characters.
Then one , and everything after it is the content. That blank line is the entire border between the headers and the page.

Status codes worth knowing

Code	Meaning
`200 OK`	Success. The contains what was asked for. Codes in the all mean some flavour of that.
`301 Moved Permanently`	It moved, permanently. The new address is in the and the browser follows it automatically — this is how a site sends visitors from to https (some, like , use , which means the same).
`404 Not Found`	The server is fine but that path does not exist. Codes in the mean the problem is in the request.
`500 Internal Server Error`	The server broke while handling a perfectly good request. Codes in the mean the problem is yours to fix, and the details are in the .

is a modern web server in a single . It is worth learning right after the shell example because it keeps the same feeling — a few readable lines and it is running — while solving what the shell cannot (many visitors at once, , by path).

Its headline feature is . Give it a real and it obtains a , installs it, renews it before it expires, and visitors from http to https. On other servers that is a chore you repeat every few months.

Installing it

install

# macOS
brew install caddy

# Ubuntu / Debian — add Caddy's own package list first (official steps)
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

# with Docker (covered in the Docker tab): serve this folder on port 8080
docker run -p 8080:80 -v "$PWD":/usr/share/caddy caddy:2

Serving a folder in one command

No needed. Go to the folder holding your and run one command — this is the fastest way to show a page to someone on the same .

terminal

# serve this folder's index.html on port 8080
caddy file-server --listen :8080

# add a directory listing for folders without an index.html
caddy file-server --listen :8080 --browse

The Caddyfile

For anything permanent you write a . It is a file, and a whole site can be four lines long.

Caddyfile

example.com {
	root * /var/www/html
	file_server
	encode gzip zstd
}

example.com {The site address. Write a real domain here and Caddy arranges the HTTPS certificate on its own. Even with , Caddy uses HTTPS with a certificate it makes itself; for plain http, write http://localhost or :80 instead.
root * /var/www/htmlWhere the files live on . The star means it applies to every path of this site.
file_serverActually serve those files. Without this line Caddy answers the with nothing.
encode gzip zstd before sending them. One word, and pages arrive noticeably faster on slow connections.

About that certificate

Caddy asks for a free certificate. For that, the domain's must point at your machine, and ports 80 and 443 must be reachable from outside. If another in front answers those ports instead, the check fails and the certificate never arrives. That is the most common reason a first Caddy setup does not turn green.

Reverse proxy: passing the request on

Most sites are not files on disk; they are an application listening on some . A is a server that takes the public request and hands it to that application, then returns its answer. One line does it.

Caddyfile

example.com {
	reverse_proxy 127.0.0.1:8080
}

files.example.com {
	root * /srv/files
	file_server browse
}

This is also how one machine many sites. Only one may hold port 443, so Caddy holds it, reads which domain each visitor asked for, and forwards each one to a different application behind it.

The commands you need

Command	What it does
`caddy run`	Run in the foreground and print the to the . This is what you want while you are still getting the configuration right.
`caddy start`	Run in the background and return your prompt. Fine for a quick demo; a proper server runs it as a instead.
`caddy reload`	Load the changed configuration without dropping a single connection. Editing a Caddyfile does not require a restart.
`caddy fmt --overwrite`	Reformat the file into the standard in place. A Caddyfile works with any indentation, but Caddy warns when the formatting is off.
`caddy validate`	Check the configuration for mistakes without starting anything. Run it before you reload a live server.

This site runs exactly like that

On the SONUB server, one front Caddy holds ports 80 and 443 and splits traffic by domain name: the main site goes to the app , and the download goes to a small Caddy container that serves files. Each site is one more block like the example above, and there is no second program fighting for the port.

Docker: Caddy in a box, then a real site online

packs a , and everything it needs to run, into a single . Libraries, settings and even a small go in. Then it runs that image as a . A container behaves the same on your laptop and on a rented server. So the old excuse "but it works on my machine" disappears.

is already a single file, so why bother? Because a real server soon runs more than one thing — a site, an app, a . Docker gives each one its own box that you start, stop, update and delete with the same few commands, without installing anything else on the server or disturbing its neighbours.

Four words to know first

ImageA frozen package of a program and everything it needs. You download one (caddy:2) or build your own from a recipe file called a Dockerfile. It never changes while it runs.
ContainerAn image that is running. One image can start many containers, and deleting a container never touches the image — the next start is fresh.
Port mappingA container has its own ports that nobody outside can see. -p 8080:80 connects port 8080 of your computer to port 80 inside the container, so a browser can reach it.
VolumeThe files a container writes inside itself vanish when it is deleted. A volume, or one of your folders mounted into it, is storage that stays — your pages, your settings and Caddy's certificates live there.

Installing Docker

On a or a PC, install from docker.com and start it once; after that the docker command works in the . On a server, Docker's official script installs everything in one line. Both check commands should answer before you go on.

install

# macOS · Windows: install Docker Desktop from docker.com and start it once

# Ubuntu / Debian server: Docker's official install script
curl -fsSL https://get.docker.com | sh

# check that both commands answer
docker --version
docker compose version

Caddy in one command

Go to a folder that holds an and run the line below. The first time, Docker downloads the Caddy image; after that it starts in about a second. Open http://localhost:8080 and your page is there.

terminal

# serve this folder at http://localhost:8080 (Control-C stops it)
docker run --rm -p 8080:80 -v "$PWD":/usr/share/caddy caddy:2

docker runCreate a container from an image and start it.
--rmDelete the container as soon as it stops, so stopped containers do not pile up. The image stays, so the next run is just as fast.
-p 8080:80Connect 8080 of your computer to port 80 inside the container, where Caddy listens. You choose the left number; the right one is fixed by the image.
-v "$PWD":/usr/share/caddyShow the current folder ($PWD) inside the container as /usr/share/caddy — the folder the official image serves by default. Edit a file here and the next reload shows the change.
caddy:2The image to run: the official Caddy image, any 2.x . Without the :2 Docker takes , which may one day jump to a new major version under your feet.

Press to stop it. This is perfect for a quick look, but the command is long and forgotten the moment the terminal closes. For anything permanent you write it down in a file — which is the next project.

Project 1: an HTML homepage, from a folder to the internet

The whole project is three small files. index.html is the page, the tells Caddy what to serve, and tells Docker how to run Caddy. Docker Compose reads that file, so you never have to retype a long command.

my-site

my-site/
├── compose.yaml
├── conf/
│   └── Caddyfile
└── site/
    └── index.html

compose.yaml

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./conf:/etc/caddy
      - ./site:/srv
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

compose.yaml line by line

image: caddy:2The image to run — the same official Caddy image as before.
restart: unless-stoppedIf the container crashes or the server reboots, Docker starts it again by itself, until you stop it on purpose.
"80:80" · "443:443"Open the machine's ports 80 () and 443 (https) to Caddy. Caddy needs both to obtain a and to send visitors from http to https.
"443:443/udp"Port 443 again, but over . It lets browsers use . Leaving it out is harmless; the site simply uses HTTP/2.
./conf:/etc/caddyYour conf folder becomes /caddy. That is where Caddy looks for its Caddyfile. Caddy's documentation mounts the folder, not the single file. Many editors replace a file when they save it, and a single mounted file would keep showing the old one.
./site:/srvYour site folder becomes /srv — the folder the Caddyfile serves. Change a page on and Caddy serves the new version at once, with no restart.
caddy_data:/dataA named that Docker keeps for you. Caddy stores its HTTPS certificates and keys here, so they survive when the container is deleted and recreated. caddy_config beside it keeps Caddy's automatic settings the same way.

Try it on your own computer first

Write :80 in the address slot of the Caddyfile. It means "answer on port 80, whatever name is asked for" — plain http with no certificate, which is exactly right on a computer that has no . Then start it and open http://localhost.

conf/Caddyfile

:80 {
	root * /srv
	file_server
}

terminal

cd my-site
docker compose up -d      # start Caddy in the background
open http://localhost     # or type the address into a browser
docker compose logs -f    # watch requests arrive (Control-C stops watching)

Putting it on the internet

Rent a serverAny with a will do — a small, cheap one is plenty. Install Docker on it with the script above, and make sure its lets ports 80 and 443 in.
Point your domain at itWhere you bought the domain name, add a : name , value the server's . It can take from a few minutes to a few hours before the whole internet sees the change.
Write the real addressIn the Caddyfile, replace :80 with your domain name. That one change is what switches on : Caddy a certificate, installs it, renews it and sends http visitors to https.
Copy and startCopy the folder to the server with (a command that copies only what changed), in with ssh (a command that opens a terminal on another computer) and start it with -d. Watch the log: a line saying the certificate was obtained means your site is live.

conf/Caddyfile

example.com {
	root * /srv
	file_server
	encode gzip zstd
}

The address 203.0.113.10 below is a reserved example; use your own server's IP. To change the page later, edit index.html and run the same rsync again. The site folder is mounted into the container, so the new page is live on the next reload without restarting anything.

terminal

# on your computer: copy the project folder to the server
rsync -av my-site/ root@203.0.113.10:~/my-site/

# on the server: start it — Caddy fetches the HTTPS certificate by itself
ssh root@203.0.113.10
cd ~/my-site
docker compose up -d
docker compose logs -f caddy

Project 2: a React homepage

is a for building a page out of small reusable . What matters for publishing is this: a React project is not served as it is. A turns it into plain , and JavaScript files in a dist folder — and from there it is the same job as Project 1.

You need on your computer for the commands below. creates a React project that is ready to run. dev shows it while you work, and npm run build makes the finished site.

terminal

# needs Node.js (nodejs.org) — create a React project with Vite
npm create vite@latest my-react -- --template react
cd my-react
npm install
npm run dev      # development server at http://localhost:5173

npm run build    # the finished site is written to dist/

Way A: build on your computer, copy the result

The simplest route reuses Project 1 as it is. Build, then copy only the dist folder into the server's site folder. --delete removes files from the previous build that no longer exist, so old leftovers do not pile up.

terminal

# way A: build here, copy only the result into Project 1's site folder
npm run build
rsync -av --delete dist/ root@203.0.113.10:~/my-site/site/

The one line React needs in the Caddyfile

A React app draws every page itself from one index.html. An address like /about is not a file on disk, so without help Caddy answers the moment someone reloads that page or opens a shared link to it. tells Caddy: serve the file if it exists, otherwise hand over index.html and let React draw the right page.

Caddyfile

example.com {
	root * /srv
	encode gzip zstd
	try_files {path} /index.html
	file_server
}

Way B: let Docker build it, with a two-stage Dockerfile

The sturdier route builds inside Docker, so the server — or a colleague's computer — always builds the same way, and nobody has to install Node on the server. The has two stages: the first builds with Node, the second keeps only the result.

Dockerfile

# stage 1: build the React app with Node
FROM node:24-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# stage 2: only the finished files go into the Caddy image
FROM caddy:2
COPY Caddyfile /etc/caddy/Caddyfile
COPY --from=build /app/dist /srv

The Dockerfile line by line

FROM node:24-alpine AS buildStage one starts from an image that has Node.js and names this stage build, so the next stage can take files from it.
COPY package*.json ./ · RUN npm ciCopy only the package list first and install exactly the versions in the lock file. Docker reuses this step while the list stays the same, so later builds skip the slow install.
COPY . . · RUN npm run buildCopy the rest of the source and build. The finished site is now in /app/dist inside the build stage.
FROM caddy:2Stage two starts again from a clean Caddy image. Nothing from stage one comes along unless you copy it.
COPY --from=build /app/dist /srvTake only the built files from the build stage and put them where the Caddyfile serves from. Node and stay behind, so the final image stays small.

Put the Caddyfile with try_files next to the Dockerfile and use the compose.yaml below: build: . means "make the image from this folder's Dockerfile" instead of downloading one. On the server, clone the and one command builds and starts it; after each change, pull and run the same command again.

compose.yaml

services:
  web:
    build: .
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

terminal

# on your computer, inside my-react: keep node_modules and old builds out of the image
printf 'node_modules\ndist\n' > .dockerignore
git add .dockerignore && git commit -m "Add .dockerignore" && git push

# on the server: get the code, then build and start in one step
git clone https://github.com/you/my-react.git
cd my-react
docker compose up -d --build

# after you push a change: pull it and rebuild
git pull && docker compose up -d --build

The commands you will use

Command	What it does
`docker compose up -d`	Start everything in compose.yaml in the background. Run it again after you change compose.yaml; only what changed is recreated.
`docker compose ps`	List this project's containers and whether they are running. The first thing to check when the site does not answer.
`docker compose logs -f`	Follow the logs live. Certificate problems, wrong paths and crashes all show up here first. Control-C stops the watching, not the server.
`docker compose exec -w /etc/caddy caddy caddy reload`	Make its Caddyfile inside the running container without dropping a single connection. Use it after editing the Caddyfile.
`docker compose down`	Stop and delete the containers. Named volumes are kept, so the certificates survive. Adding -v would delete them too — avoid it.
`docker compose pull`	Download a newer Caddy image. Follow it with docker compose up -d to switch over to it.

Never throw away caddy_data

Your certificates are stored in the caddy_data volume. If it is deleted, Caddy has to request new certificates every time it starts. It gets deleted by -v, or by leaving the volume out of compose.yaml. limit how many certificates one domain can get in a week. So a few careless restarts can leave your site without HTTPS for days.

Web Client

You mark this yourself. Nothing is graded here.

Mark this step as understood?

This cannot be undone yet, so mark it only when you really understand.

Marked as understood

You mark this yourself. Nothing is graded here.

Notifications

How to enable notifications

Web Server

A web server is a program that answers

One visit, four steps

A web server in one shell script

Line by line

Run it yourself

What actually travels down the wire

The request the browser sends

The response the server sends

Status codes worth knowing

What this server cannot do