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

[quartz-docker image](https://code.modernleft.org/gravityfargo/-/packages/container/quartz-docker/v4.4.0)

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

This project runs **Quartz 4**, 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.

I explored several alternative approaches for configuration within this container, but none met my criteria for simplicity—specifically, avoiding the need to mount the entire site source and instead only requiring a dedicated `content` and `config` directory.

## 🚀 Features

- **Easy Configuration** – Customize settings using a json file
- **Automated Site Updates** – Configurable cron job to fetch and rebuild content

## 🐳 Docker Compose Setup

### Prepare Data Directories

Create a data directory and pull your existing content

```bash
# create directories
mkdir -p /srv/quartz/config
cd /srv/quartz
# clone your content
git clone https://code.modernleft.org/gravityfargo/modernleft-docs.git content
```

### Compose File

Create a `docker-compose.yml` file:
![[docker-compose]]

### First Run

```bash
docker-compose up -d
docker stop quartz-wiki
```

On first run, the container will download the necessary dependencies and build the site.

In `/srv/quartz/config/config.json`, you need to change the `baseUrl` to your domain.

## ⚙️ Configuration

### Optional `node_modules` volume

To keep the image small, `node_modules` are not included. When the container is run, they are downloaded to `/usr/share/nginx/html/node_modules`. Mounting this as a volume ensures they persist between container runs, reducing setup time.

### cron

This is the command run by cron

```bash
cd /usr/share/nginx/html/content && \
git pull >/dev/null 2>&1 && \
cd /usr/share/nginx/html && \
npx quartz build >/dev/null 2>&1
```

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

See a list of all environment variables [here](#environment-variables).

| Variable             | Description                                           | Default Value                 |
| -------------------- | ----------------------------------------------------- | ----------------------------- |
| `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 |
| `QUARTZ_CONFIG_PATH` | Path to the Quartz configuration file                 | `/config/quartz.json`         |
| `USER_ID`            | UID that` /content` and` /config` will be chown'd to. | `1000`                        |
| `GROUP_ID`           | GID that` /content` and` /config` will be chown'd to. | `1000`                        |

You shouldn't need to change `QUARTZ_CONFIG_PATH`