modernleft-docs/Docker Images/quartz.md

---
title: quartz
draft: false
date: 2025-01-16
---

|                         |                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| Image on Forgejo        | [Forgejo](https://code.modernleft.org/gravityfargo/-/packages/container/quartz-docker/v4.4.0)  |
| Official quartz project | [GitHub - jackyzha0/quartz](https://github.com/jackyzha0/quartz)                               |
| Image Source            | [Forgejo - gravityfargo/quartz-docker](https://code.modernleft.org/gravityfargo/quartz-docker) |
| Issue Tracker           |                                                                                                |

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

---

This project runs [Quartz](https://quartz.jzhao.xyz/) 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](https://quartz.jzhao.xyz/features/Docker-Support), it is not as self contained as this project. The primary audience of Quartz [seems](https://quartz.jzhao.xyz/hosting#self-hosting) 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](https://quartz.jzhao.xyz/setting-up-your-GitHub-repository) 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

```bash
mkdir -p /srv/quartz
```

```yaml title="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**

```bash
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](https://quartz.jzhao.xyz/configuration)
Bare minimum should be `baseUrl` (for rss services) and `pageTitle`.

🥳 Done! 🎉

> [!NOTE] 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.

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

```bash
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](https://crontab.guru/) is a useful tool for that

Example:

```yaml
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` |

> [!NOTE] >
> `CONTENT_REPO` Must use https, not git.