Quartz

It's simply quartz, in a docker container.

Warning

I no longer maintain this container. I switched to mkdocs, obviously. The container still works and should be fine unless the upstream quartz project changes the way they build, reload, and serve the site.


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.

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`

Note

CONTENT_REPO Must use https, not SSH.

FAQ

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

You're probably running behind cloudflare, or some other CDN that's rate limiting that's the only time I've seen this happen. Significantly decreasing the frequency of the cron job should help.