Static sites with Python, uv, Caddy, and Docker

https://nkantar.com/blog/2025/08/static-python-uv-caddy-docker/

by indigodaddy • 11 months ago

157 88 11 months ago

zahlman2• 11 months ago

This just seems like several unnecessary layers of complexity to me.

For making a static site that you're personally deploying, exactly why is Docker required? And if the Docker process will have to bring in an entire Linux image anyway, why is obtaining Python separately better than using a Python provided by the image? And given that we've created an entire isolated container with an explicitly installed Python, why is running a Python script via `uv` better than running it via `python`? Why are we also setting up a virtual environment if we have this container already?

Since we're already making a `pyproject.toml` so that uv knows what the dependencies are, we could just as well make a wheel, use e.g. pipx to install it locally (no container required) and run the program's own entry point. (Or use someone else's SSG, permanently installed the same way. Which is what I'm doing.)

nkantar4• 11 months ago

Author—though not OP—here. I’ll try to broadly address the questions, which are all fair.

Broadly speaking, I explicitly wanted to stay in the Coolify world. Coolify is a self-hostable PaaS platform—though I use the Cloud service, as I mentioned—and I really like the abstraction it provides. I haven’t had to SSH into my server for anything since I set it up—I just add repos through the web UI and things deploy and show up in my browser.

Yes, static sites certainly could—and arguably even should—be done way simpler than this. But I have other things I want to deploy on the same infrastructure, things that aren’t static sites, and for which containers make a whole lot more sense. Simplicity can be “each thing is simple in isolation”, but it can also be “all things are consistent with each other”, and in this case I chose the latter.

If this standardization on this kind of abstraction weren’t a priority, this would indeed be a pretty inefficient way of doing this. In fact, I arrived at my current setup by doing what you suggested—setting up a server without containers, building sites directly on it, and serving them from a single reverse proxy instance—and the amount of automation I found myself writing was a bit tedious. The final nail in the coffin for that approach was realizing I’d have to solve web apps with multiple processes in some other way regardless.

divbzero• 11 months ago

I explicitly wanted to stay in the Coolify world.

I too was skeptical of the motivation until reading this. Given that Coolify requirement, your solution (build static files in one container, deploy with Caddy in another) seems quite sensible.

john-tells-all• 11 months ago

(Hi, Nik!)

So what you're saying is that "Static sites with Python, uv, Caddy, and Docker" wasn't the overall goal. You want to stay in Coolify world, where most things are a container image.

It just so happens that a container can be just a statically-served site, and this is a pattern to do it.

By treating everything as a container, you get a lot of simplicity and flexibility.

Docker etc is overkill for the static case, but useful for the general case.

cyanydeez• 11 months ago

Simple answer is to package it up with all its system dependencies ans not worry about anything.

TZubiri2• 11 months ago

Looking forward to the follow up:

Static sites with HTML, CSS, Apache and Linux.

Avamander2• 11 months ago

You can of course use something like Pelican to generate those plain static files. There are quite a few great themes available as well.

TZubiri2• 11 months ago

My guess is that when you are self taught and don't know what the hierarchy of technologies looks like, you can learn several advanced technologies without knowing the basic technologies that they are built upon and the challenges the basic tech can't solve.

So you just solve all problems with advanced tools, no matter how simple. You get into tech by learning how to use a chainsaw because it's so powerful and you wanted to cut a tree, now you need to cut some butter for a toast? Chainsaw!

busyant• 11 months ago

it's so powerful and you wanted to cut a tree, now you need to cut some butter for a toast? Chainsaw!

Using a Ferrari to deliver the milk is how I've heard it said.

worldsayshi• 11 months ago

Or maybe you stick with a stack that is too complex for most problems but also works for most of them so that when you solve/find a solution to a certain problem you can reuse that solution in all of your projects.

kelvinjps10• 11 months ago

I thought it's the opposite and I have seen it self taught use simpler tools that are not the standard,like just using ftp or rsync instead of complex tools

pfranz• 11 months ago

why is obtaining Python separately better than using a Python provided by the image?

I mostly work in a different domain than webdev, but feel strongly about trying to decouple base technologies of your OS and your application as much as possible.

It's one thing if you are using a Linux image and choose to grab their Python package and other if their boot system is built around the specific version of Python that ships with the OS. The goal being if you later need to update Python or the OS they're not tethered together.

wiether2• 11 months ago

I understand both your point of views and I guess I see the confusion.

With Docker, usually you try to pick the base image that is the most closer to your usecase.

For instance, if you intend to run a Python 3.10 script in your final image, you'll start from a python:3.10 base image, since it contains your most important requirement.

But in the article, the author is starting from an "uv" image, and then in the creation process (described in their Dockerfile), they'll install their required version of python.

Which, for many people writing Dockerfiles daily (me included), feels weird: if you intend to run python, why not starting from an image including your python version?

Then, if we look at what uv actually is, it can of make sense: it's an app written in Rust (so not a python app) that can be seen as a _docker for python apps_.

And since the author's focus seemed to be about uv, we can see why they started from an uv image.

rr8082• 11 months ago

At my work we use docker for everything now. Makes no sense. Literally we have a dedicated server for each application. Instead of copying python files to the server in 5 seconds we take 30 minutes to build a docker container, copy to repo, scan it, deploy.

9dev• 11 months ago

But you’ve gained the ability to do static analyses and quality control, enforce authorisation on who can deploy to the prod server, gained accountability and a history of changes by virtue of having it in the repo, enabled everyone to run the image locally regardless of their local environment…

a_t48• 11 months ago

Not saying you're wrong here, but if that 30 minutes doesn't include running tests it sounds like your Dockerfile is setup poorly. For a ci/cd setup it should take like...a minute at most, if you don't have heavy ML dependencies, etc. Maybe less, depending on how well you cache things.

raffraffraff• 11 months ago

I created a static site generator for my wife's business using go + js + git. She has no tech skills whatsoever, but had very specific ideas about how the website should work.

Once the basic functionality was worked out in js (with a simple JSON schema and Lourm Ipsum text), I created a Samba share on the network, mapped it to her computer.

Her first post was an edit of the Lorum Ipsum markdown and some new images, and from then on she had a pattern to follow: add a directory with a markdown file and assets.

The NAS runs a Go program that generates a JSON file for the static site js, starts a http server for testing. She can access the http server over the network to preview the static site. If it's ok, she can trigger a git commit and push (with a click). She didn't have to learn anything (like Hugo or jinja), because markdown is kinda obvious. She has exactly the website she wants.

Of course, I had more work to do initially, coming up with the static site, the JSON schema and the go generator, but it was over a week of evenings. She's been happily adding to it regularly without my interaction.

And this, my friends, is why I (a mere DevOps / Cloud guy) "vibe code" with Claude.

skylurk• 11 months ago

This sounds exactly like how I use Hugo. It's sweet that you made your own thing! But if you ever end up wanting to use a prebuilt Hugo theme, I bet it would be super easy to switch over.

hk1337• 11 months ago

That’s really cool for you but for your wife, I would find something simpler. What happens if you’re not around and that all breaks and she cannot get content published?

At the very least, assuming you want to keep it somewhat techy, I would setup a repository with a Hugo config, theme pulled in as a module, with ci to auto deploy it. Make it so the repository is just her markdown content, some css/js overrides if needed, and a hugo.toml.

Or just setup a Wordpress or similar site for her

superkuh• 11 months ago

The best way to make static sites is to install nginx/caddy or whatever basic static webserver from your repos. Then put the .html and files in directories on your filesystem in the web root folder. Done. No overhead, no attack surface, no problems with software changing (deps, etc, etc), lasts forever. Super easy interface (it's your filesystem!).

This project seems more like something you'd do to demonstrate your skills with all these tools that do have use in a business/for-profit context working with groups but they have absolutely no use or place hosting a personal static website. Unless you're doing it for kicks and enjoy useless complexity. That's fair. No accounting for taste in recreation.

chrisweekly2• 11 months ago

The author wrote a comment in another thread^1 just a few min before yours.

Also, starting any comment with an unqualified "The best way..." is probably not the best way to engage in meaningful dialog.

1. https://news.ycombinator.com/item?id=44993875

Spivak• 11 months ago

The flow where you build the static site into a container in CI, push it to a registry, and then your server watches for changes (watchtower) and runs it behind nginx-proxy is the true lazy solution. Push to your git repo and forget about it. Same config for a huge variety of applications—static and not.

ahmedfromtunis• 11 months ago

At this point, why not use a wordpress container? With a minimalist theme, it would be way easier and faster to deploy, and still be blazingly responsive.

This level of complexity would've been acceptable if this was about deploying one's own netlify type of service for personal use. Otherwise, it's just way too complicated.

I'm currently working on a Django app, complete with a database, a caching layer, a reverse-proxy, a separate API service, etc. and still much simpler to deploy than this.

chrisweekly2• 11 months ago

wordpress is php is a non-starter for many of us

cosmic_cheese• 11 months ago

More broadly, a lot of people are disinclined from anything that needs to run on the server, especially anything involving dynamic languages, because that brings vulnerabilities and an elevated need to keep it all patched up. Static HTML/CSS/JS can be hosted from a wide variety of zero maintanence solutions and can’t be exploited.

It might have gotten better since, but back when I was running a Wordpress install it was a constant battle to keep bots out.

pluto_modadic• 11 months ago

it's true, wordpress is self contained - it does bundle in a lot of overhead (database, php) - but it has a good story for quickly getting a presentable site. Static sites require learning about template engines, git (possibly), FTP...

1a527dd52• 11 months ago

I think the author would do well to front load "the why". Seems very over the top, sometimes you want to do things just because. Totally valid, but helps contextual the blog.

tedmiston• 11 months ago

They are essentially choosing the philosophy of optimizing for speed in every dimension.

The tools selected are faster than their more mainstream counterparts — but since it's a static site anyway, the pre-build side of the toolchain is more about "nice dev ux" and the post-build is more about "really fast to load and read".

zahlman2• 11 months ago

Much faster still would be to not set up a container for what appears to be a one-off run of some SSG-generation library on some Markdown files.

hu3• 11 months ago

I love Caddy and it's fast enough. But it's not the fastest. nginx is generally faster for example.

So I can't agree.

gerdesj• 11 months ago

We both speak the same language. I can get to grips with "front load" but what does:

"helps contextual the blog" mean?

It appears, for the verb, you meant: "frobnicate".

bmacho• 11 months ago

It's supposed to be 'contextualize': putting it in context, ~explain.

nkantar4• 11 months ago

Author (not OP) here. In hindsight, I wish I’d explained “the why” mostly to save so many folks in this thread from making lots of assumptions. The third paragraph in this comment touches on that: https://news.ycombinator.com/item?id=44993875

the__alchemist• 11 months ago

This is a snapshot of what's gone wrong in acutely, web development culture, and broadly, software development culture over the past few decades. Complexity, provincialization, and discarding improvements in computing hardware.

BolsunBacset• 11 months ago

This is a snapshot of what's gone wrong in acutely, web development culture, and broadly, software development culture over the past few decades. Complexity, provincialization, and discarding improvements in computing hardware.

Taken from the Coolify website (which OP uses for hosting):

Brag About It. You can impress anyone by saying that you self-host in the Cloud. They will definitely be amazed.

This is the result of a hyper consumerist post Protestant culture in America and the rest of the English speaking countries.

zidoo• 11 months ago

Why don't you just upload the HTML/CSS/JS files to a folder and point Apache or Nginx to that folder?

lemonberry3• 11 months ago

A post on Coolify from 4 months ago.

https://news.ycombinator.com/item?id=43555996

tinix• 11 months ago

this is satire right?

zelphirkalt• 11 months ago

And I deploy that using Ansible! Well, in my case a truly static HTML file and a bunch of CSS files. But yes, Caddy is great for serving static pages. If you have set it up once, you can apply the whole thing as one setup (playbook).

marmalade24133• 11 months ago

Adding fuel to the fire of "this is over engineering" but this is overkill right?! I'm not in the web development field but my own site is just deployed with Emacs (specifically HTML generated from org-mode).

hamandcheese• 11 months ago

I'd be a lot more impressed if your static site was served from Emacs :)

zrail• 11 months ago

You joke but this is absolutely a thing: https://github.com/skeeto/emacs-web-server

lemonberry3• 11 months ago

I'm interested in doing this. Have you posted about your process?

marmalade24133• 11 months ago

Yes! It's not hosted via Emacs but here's the static site generation process: https://abdrysdale.phd/colophon.html

stackskipton• 11 months ago

this is overkill right?!

My Ops brain says "Taken in vacuum, yes" However, if you make other things that are not static, put them into a container and run said container on a server, keeping the CI/CD process consistent makes absolute sense.

We run static sites at my company in containers for same reason. We have Kubernetes cluster with all DNS Updating, Cert Grabbing and Prometheus monitoring so we run static sites from nginx container.

justinsaccount• 11 months ago

I don't really have an opinion on using caddy in a container to serve a static site. That's fine, really.. However, the way the container is built is done in the worst possible way:

  # copy all files
  COPY . .

  # install Python with uv
  RUN uv python install 3.13

  # run build process
  RUN uv run --no-dev sus

This adds the entire repository to the first layer, then installs python, then runs the build which I assume will only then install the dependencies. This means that changing any file in the repository invalidates the first layer, triggering uv reinstalling python and all the dependencies again. The correct Dockerfile would be something like

  # install Python with uv
  RUN uv python install 3.13

  # copy info for dependencies
  COPY pyproject.toml uv.lock .

  # Install dependencies
  RUN uv whatever

  # Copy over everything else
  COPY . .

  # run build process
  RUN uv run --no-dev sus

krick2• 11 months ago

Exactly. I wanted to also point this out in the relation of the author's desire to put all build commands in `just` configuration file. It sounds to me like a desire to use some another "slick and shiny tool" (which `just` is when compared to `make`), but what's the point exactly? The build-process will still be container-dependent and may or may not work outside of the container, and you don't get the benefit of Docker caching anymore.

simonw6• 11 months ago

Being able to run "just build" in a container-free local development environment and have the same build process run as the one in your production setup is a productivity boost worth having.

Same as how it's good to be able to easily run the exact same test suite in both dev and CI.

pvtmert2• 11 months ago

delayed

codespin• 11 months ago

Getting the dockerfile order right is critical due to how docker caching works.

Even if you aren't an expert it is trivial these days to copy/paste it into chatGPT and ask it to optimize or suggest improvements to the dockerfile, it will then explain it to you.

globular-toast• 11 months ago

My heuristic to go from least likely to change to most likely, bearing in mind dependencies, of course.

nkantar4• 11 months ago

Author (not OP) here. It hadn’t really occurred to me to optimize the Dockerfile in this way because of how rarely the build is run in the first place, but I’m absolutely going to do this, since the ratio of code changes to content changes will definitely skew heavily toward the latter, and it just seems like a good habit anyway. Thanks for reminding me, and even explaining how to do it!

pvtmert2• 11 months ago

I see the Docker stuff here but Kubernetes is missing. Lacking required complexity for a simple _static_ personal blog.

Also while using Kubernetes, please use event-driven PubSub mechanisms to serve files for added state-of-the-art points.

/pun

ThinkBeat• 11 months ago

Is this satire?

html file -> ftp -> WWW html file -> mv /var/www/public -> WWW

Possibly SSG -> html -> etc.

slashdave• 11 months ago

It's... a static site. Generate the output (use docker if you want, doesn't really matter), and just dump the result to a directory on an ordinary server.

knlb2• 11 months ago

My current personal site (https://knlb.dev) is built with a single 500 line python file that starts with

  #!/usr/bin/env -S uv run --script
  # -*- mode: python -*-
  #
  # /// script
  # requires-python = ">=3.12"
  # dependencies = [
  #    "pyyaml", "flask", "markdown-it-py",
  #    "linkify-it-py", "mdit-py-plugins"
  # ]
  # ///

The HTML templates & CSS are baked into the file which is why it's so long. flask so that I can have a live view locally while writing new notes.

uv's easy dependency definition really made it much easier to manage these. My previous site was org exported to html and took much more effort.

(With the conceit that the website is a "notebook" I call this file "bind").

justusthane• 11 months ago

Do you have the whole thing available? I love SSGs, especially personal ones.

knlb2• 11 months ago

Not the latest one just yet, I still want to play with it a lot more / bake in some more features -- but it's also terribly simple and doesn't do much at the moment.

The org mode one is at https://explog.in/config.html.

simonw6• 11 months ago

Almost every other comment in this thread is people complaining this is too complex and over-engineered.

I had the opposite reaction when I read this post: I thought it was a very neat, clean and effective way to solve this particular problem - one that took advantage of an excellent stack of software - Caddy, Docker, uv, Plausible, Coolify - and used them all to their advantage.

Ignoring caching (which it sounds like the author is going to fix anyway, see their other comments) this is an excellent Dockerfile!

  FROM ghcr.io/astral-sh/uv:debian AS build
  WORKDIR /src
  COPY . .
  RUN uv python install 3.13
  RUN uv run --no-dev sus
  
  FROM caddy:alpine
  COPY Caddyfile /etc/caddy/Caddyfile
  COPY --from=build /src/output /srv/

8 lines is all it takes. Nice. And the author then did us the favor of writing up a detailed explanation of every one of them. I learned a few useful new trick from this, particularly around using Caddy with Plausible.

This one didn't strike me as over-engineering: I saw it as someone who has thought extremely carefully about their stack, figured out a lightweight pattern that uses each of the tools in that stack as effectively as possible and then documented their setup in the perfect amount of detail.

hamdingers• 11 months ago

Meanwhile, my dockerfile for "purely static—hand-crafted artisanal HTML and CSS" is this:

  FROM nginx:alpine
  COPY . /usr/share/nginx/html

simonw6• 11 months ago

Sure, but that doesn't handle Plausible proxying or run the static site generator script.

oefrha2• 11 months ago

People are complaining because

  make && make deploy

where the default target is simply `uv run --no-dev sus` and the deploy target is simply `rsync -avz --delete ./dist/ host:/path/to/site/` is hell a lot more neat, clean, effective, and lightweight? (And if you care about atomic deployment it's just another command in the deploy target.)

I have ~60 static websites deployed on a single small machine at zero marginal cost. I use nginx but I can use caddy just the same. With this "lightweight pattern" I'd be running 60 and counting docker containers for no reason.

simonw6• 11 months ago

The author of this clearly mostly runs non-static sites in containers, but since they have container-based hosting setup already it's more consistent for them to deploy a static site with Caddy in a dedicated container than to spin up a new deployment mechanism that's inconsistent with everything else they are running.

Also their site isn't entirely static: they're using Caddy to proxy specific paths to plausible.io for analytics.

indigodaddy3• 11 months ago

Here's my dockerfile (hosted on fly). It was done before I knew about uv, but poetry works fine. Anything look wrong or any suggested optimizations?

https://raw.githubusercontent.com/jgbrwn/my-upc/refs/heads/m...

theden• 11 months ago

My minor suggestion would be to not to use `COPY . .` as it could slow down the build process if it has to copy everything in the context that's not needed. Also a potential privacy/sec risk if private/secret data is copied the final docker image, but probably not applicable in a multi-stage builds where it's in an aux stage.

If you don't want to have multiple `COPY`s, you can add a `.dockerignore` file (https://docs.docker.com/build/concepts/context/#dockerignore...) with the `COPY . .` directive and effectively configure an allowlist of paths, e.g.,

  *
  !src/
  !requirements.txt

adithyassekhar2• 11 months ago

I went through the coolify rabbit hole. They have a google fonts drop in alternative https://fonts.coollabs.io, which uses https://gwfh.mranftl.com/fonts but there are no mentions of the latter anywhere on coollabs readme or GitHub. If anyone from coollabs is here, you should atleast mention it somewhere.

rivepica• 11 months ago

Imagine Caddy had a built-in feature to manage redirects with a very simple syntax. Maybe it could be called redir? That'd help removing the whole "run python to compile a bunch of HTML files" part of this.

Oh wait …

saagarjha• 11 months ago

Maybe I'm just venting but you can probably eject Docker from this setup. If your dependencies are pretty well-defined then you don't really need a base image; just install Caddy and let uv handle the Python dependencies. Among us on Hacker News you'd think that there's a bunch of Docker hate but I really think that you don't need it if your dependencies are really simple and you don't need a specific version of things.

indigodaddy3• 11 months ago

True, but his server has Coolify already which already has a reverse proxy on the host listening on 80/443, and uses Docker based deploy/application method

vivzkestrel• 11 months ago

You won't have to sit and do any of this manually once my production grade python application generator goes live. At the moment it works with poetry and i am working on a uv version of it. Let me explain what the poetry one does

- Setup a docker container - Install python 3.x (specified by you) - Install poetry x.y (specified by you) - Setup README - Setup gitignore - Install black, isort, flake8, tox, pre-commit, mypy, commitizen, darglint, xdoctest, pytest with src and tests directory with a lot of inputs from you with pinned dependencies - Add nginx / caddy / traefik with Github Actions CI / CD and templates for pull requests, issues, feature requests, questions etc - Verify everything works by running all commands in docker - Give you a downloadable version of this production grade python application - As dependencies update, this whole pipeline updates immediately

heavensteeth• 11 months ago

I found a pretty cool 80kb docker image that is just a copy of busybox httpd, which makes creating a docker image out of static files very simple.[0]

[0] https://github.com/lipanski/docker-static-website

indigodaddy3• 11 months ago

I've had this starred forever but never messed with it, looks great I need to try it. Also makes me want to try redbean in a docker container:

https://github.com/kissgyorgy/redbean-docker

mediumsmart• 11 months ago

Is this container containing the website inside a Linux OS running inside an outer docker container that is contained in the coolify container inside a web app in the cloud or is it just shipped in the container?

wiether2• 11 months ago

@author: I'm disappointed by all the negativity in the comments.

People are mocking you without even trying to understand what you did, why, and also the actual work that went in writing the article.

That's not everyday that someone takes the time to explain every layer of their Dockerfile.

Even if I would have went a different way, I found it interesting and it also forced me to dig deeper in uv, which I wrongly assumed I understood.

Thank you for writing it and please don't make the bad comments have any significant impact on you (maybe just put a big disclaimer in your intro next time so they'll find someone else to pick on)

nkantar4• 11 months ago

Hi! Thanks for the kind words! I’m not taking the comments to heart, though I might write a follow-up post explaining why I chose this stack to pre-empt the surprising number of assumptions, and I might keep this in my for other, future posts.

I’m glad this lead to some learning for you! Some of the comments did that for me, which is great.

Static sites with Python, uv, Caddy, and Docker

Related Stories