---
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, and I do not use Github/Gitlab.

I have included node, nginx, and cron. Setup, building, and updating are all taken care of. 

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