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
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.