quartz

Official quartz project	GitHub - jackyzha0/quartz
Image on Forgejo	Forgejo
Image on Docker Hub	Dockehub
Image Source	Forgejo - gravityfargo/quartz-docker
Issue Tracker	GitHub - gravityfargo/quartz-docker
Image Documentation	ModernLeft Docs

docker pull code.modernleft.org/gravityfargo/quartz-docker:latest

---

This project runs Quartz, 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.
• Customizations can be made in a fork of the jackyzha0/quartz repository and passed into the container as an environment variable.

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:latest
    ports:
      - 80:8080
    environment:
      USER_ID: 1000
      GROUP_ID: 1000
      NGINX_PORT: 8080
      SERVER_NAME: "docs.modernleft.org"
      ENABLE_CRON: "true"
      BUILD_SCHEDULE: "*/30 * * * *"
      CONTENT_REPO: "https://code.modernleft.org/gravityfargo/modernleft-docs.git"
      QUARTZ_REPO: "https://code.modernleft.org/gravityfargo/modernleft-docs-quartz.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/quartz.config.ts using the options found in the quartz documentation. Bare minimum should be baseUrl (for rss services) and pageTitle.

🥳 Done! 🎉

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	"*/5 * * * *" every 5 min
CONTENT_REPO	URL of the content repository	“
QUARTZ_REPO	URL of the quartz repository	https://github.com/jackyzha0/quartz.git

>

CONTENT_REPO Must use https, not git.

FAQ

Why do I get fatal git errors when the cron job runs?

You’re probably running behind cloudflare, that’s the only time I’ve seen this happen.