Quartz 4: install on a Linux VPS with Docker

Quartz 4 is an open-source static site generator that turns Markdown notes into a digital garden or a personal knowledge base. This guide builds the site with Docker and serves it with Nginx and Docker Compose on a Linux VPS.

What you need

• A Linux VPS with sudo access. If you are looking for one, we recommend UnixHost.pro.
• Docker, installed by the official instructions.
• Docker Compose, see the official guide.
• Basic Git knowledge. Optional, but it helps to keep the source of the site in a repository.

Step 1: prepare the VPS

Update the system:

sudo apt update && sudo apt upgrade -y

Create a project directory. It will hold the Quartz source files, the configuration and the generated site:

mkdir ~/quartz4
cd ~/quartz4

If you already have a Quartz site, clone its repository into this directory. Replace the address with your own:

git clone https://example.com/your-quartz-repo.git .

If you are starting fresh, create a new Quartz project by the official documentation. The rest of the guide assumes that ~/quartz4 has a content directory and a quartz.config.ts file.

Step 2: create docker-compose.yml

Nginx serves the static files that Quartz generates. Create docker-compose.yml in ~/quartz4:

services:
  quartz_server:
    image: nginx:stable-alpine
    container_name: quartz_nginx_server
    ports:
      - "80:80"
      - "443:443" # Only if you plan to use SSL/TLS
    volumes:
      - ./output:/usr/share/nginx/html:ro # The generated Quartz site
      # - ./nginx_custom.conf:/etc/nginx/conf.d/default.conf:ro # Optional custom Nginx configuration
    restart: unless-stopped
    read_only: true # Recommended for static content servers

• image: nginx:stable-alpine is a lightweight Nginx image.
• ports maps port 80 (HTTP) and optionally 443 (HTTPS) from the VPS to the container.
• ./output:/usr/share/nginx/html:ro mounts the local output directory with the built site into the Nginx web root, read-only.
• restart: unless-stopped brings Nginx back after a crash or a reboot.

Step 3: build the site with Docker

Make sure the Quartz source files are in ~/quartz4: the content/ folder, quartz.config.ts, package.json and the rest. Then run from that directory:

docker run --rm -v "$(pwd):/app" jackyzha0/quartz npm install
docker run --rm -v "$(pwd):/app" jackyzha0/quartz npx quartz build

• docker run --rm runs a container and removes it when it exits.
• -v "$(pwd):/app" mounts the current directory into the container as /app, so the image can read the sources and write the result.
• npm install installs the dependencies Quartz needs.
• npx quartz build generates the static site.

After this step there should be an output directory in ~/quartz4 with the HTML, CSS and JS files.

Step 4: start the server

docker compose up -d

The site is now available at the IP address or domain of the VPS on port 80.

Step 5: change the configuration and rebuild

Quartz is configured through quartz.config.ts and quartz.layout.ts in the project directory. Edit them, add notes to content/, then rebuild:

cd ~/quartz4
docker run --rm -v "$(pwd):/app" jackyzha0/quartz npx quartz build

Nginx serves the updated files from output straight away, no restart needed.

Step 6: SSL with Certbot (optional)

A public site needs HTTPS. Certbot can obtain and renew the certificates.

1. Open port 443 in the VPS firewall.
2. Install Certbot for your distribution by the instructions at certbot.eff.org.
3. Run it with your domain:

sudo certbot --nginx -d example.com -d www.example.com

Result

Quartz 4 runs on the VPS: Nginx serves the static site, and one Docker command rebuilds it after every change to the notes.