quartz

Image on Forgejo	Forgejo
Official quartz project	GitHub - jackyzha0/quartz
Image Source	Forgejo - gravityfargo/quartz-docker
Issue Tracker

docker pull code.modernleft.org/gravityfargo/quartz-docker:v4.4.0

---

This project runs Quartz v4.4.0, a fast, batteries-included static site generator, inside a Docker container. It transforms Markdown content into a fully functional website.

While Quartz provides Docker support, it is not as self contained as this project. The primary audience of Quartz seems to be geared towards GitHub/Cloudflare/GitLab pages users. I prefer Forejo.

I made this container for users who want to self host Quartz without GitHub/Cloudflare/GitLab pages with minimal setup required. The intent is to host in a stand-alone container behind a reverse proxy like Traefik.

Benefits

• Repository setup is not required. Any git repository can be used as site content.
• GitHub/Cloudflare/GitLab pages is not the focus.
• The auto-deployment features that those services provide are replaced with a cron job.

There is no support for SSL or any other features that are not directly related to building the site. I run everything behind traefik, so I don’t need it.

🐳 Docker Compose Setup

Create a data directory

mkdir -p /srv/quartz

docker-compose.yml

services:
  quartz-wiki:
    container_name: quartz-wiki
    image: code.modernleft.org/gravityfargo/quartz-docker:dev
    ports:
      - 80:80
    environment:
      USER_ID: 1000
      GROUP_ID: 1001
      SERVER_NAME: "docs.modernleft.org"
      ENABLE_CRON: "true"
      BUILD_SCHEDULE: "*/30 * * * *"
      CONTENT_REPO: "https://code.modernleft.org/gravityfargo/modernleft-docs.git"
    volumes:
      - /srv/quartz:/quartz

First Run

docker-compose up -d
docker stop quartz-wiki

On first run, the container will download the necessary dependencies, build the site, and download the content repository.

After that, you can configure whatever you would like in /srv/quartz/src using the stock options found in the quartz documentation Bare minimum should be baseUrl (for rss services) and pageTitle.

🥳 Done! 🎉

Cloudflare

I’ve found that the cron schedule will eventually start having fatal git errors. Disabling Cloudflare fixed this. I am moving away from their services after their many controversies. Do with that what you will.

Manually Building the Site

If you don’t use the cron job, and don’t feel like restarting the container, you can build the site manually.

docker exec -it quartz-wiki bash
#
cd /quartz/content/ && git restore . && git pull
cd /quartz/src/ && npx quartz build

⚙️ Configuration

cron

This is the an equivalent command to the cron job.

cd /quartz/content
git restore .
git pull
cd /quartz/src &
npx quartz build
echo 'Content Updated.'

Setting ENABLE_CRON to true and defining BUILD_SCHEDULE performs these actions. If you need help configuring Crontab.guru - The cron schedule expression generator is a useful tool for that

Example:

environment:
  ENABLE_CRON: "true"
  BUILD_SCHEDULE: "*/1 * * * *" # Runs every minute

Environment Variables

Variable	Description	Default Value
USER_ID/GROUP_ID	UID/GID that /quartz will be chown’d to on startup	1000:1000
NGINX_PORT	Port for the Nginx server	80
SERVER_NAME	NGINX server name	quartz.zhao.xyz
ENABLE_CRON	Enables scheduled builds (true or false)	false
BUILD_SCHEDULE	Cron expression for scheduling site builds	"*/10 * * * *" every 10 min
CONTENT_REPO	URL of the content repository	https://code.modernleft.org/gravityfargo/empty.git

>

CONTENT_REPO Must use https, not git.