How to Install and Configure Quartz 4 on a Linux VPS with Docker

Introduction to Quartz 4

Quartz 4 (official website: https://quartz.jzhao.xyz/) is an open-source, markdown-based static site generator that transforms your notes and documents into a digital garden or a personal knowledge base. It’s designed for speed, flexibility, and a beautiful reading experience, allowing you to publish your thoughts and insights with ease. This guide will walk you through setting up and serving your Quartz 4 site on a Linux Virtual Private Server (VPS) using Docker and Docker Compose, ensuring a robust and scalable deployment.

Prerequisites

Before you begin, make sure you have the following:

A Linux VPS: A reliable virtual private server with sudo access. If you’re looking for a powerful and affordable VPS, we recommend UnixHost.pro.
Docker: The containerization platform installed on your VPS. You can find official installation instructions at docs.docker.com/engine/install/.
Docker Compose: A tool for defining and running multi-container Docker applications. Install it by following the official guide at docs.docker.com/compose/install/.
Basic understanding of Git: (Optional, but recommended for managing your Quartz site source code.)
Node.js and npm/yarn: (Optional, if you prefer to build locally, or required if building on the VPS without Docker for the build step.)

Step-by-Step Installation and Configuration

This guide focuses on using Docker Compose to serve your Quartz 4 site, and Docker to build it on your VPS.

Step 1: Prepare Your VPS

Update your system:
```
sudo apt update && sudo apt upgrade -y
```
Create a project directory for Quartz: This directory will hold your Quartz source files, configuration, and the generated output.
```
mkdir ~/quartz4
cd ~/quartz4
```
Clone your Quartz site repository (or set up a new one): If you already have a Quartz site, clone its repository into the ~/quartz4 directory.
```
git clone your_quartz_repo_url . # Clones into the current directory
```
If you’re starting fresh, you can initialize a new Quartz project. Refer to the official Quartz documentation for initial setup. For instance, you might use npm create quartz or similar. For this guide, we’ll assume you have a content directory and a quartz.config.ts file in your ~/quartz4 directory.

Step 2: Create `docker-compose.yml` for Serving

We’ll use Nginx to serve the static files generated by Quartz. Create a file named docker-compose.yml in your ~/quartz4 directory:

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

image: nginx:stable-alpine: Uses a lightweight Nginx image.
ports: Maps port 80 (HTTP) and optionally 443 (HTTPS) from your VPS to the Nginx container.
volumes: ./output:/usr/share/nginx/html:ro: This is crucial. It mounts a local directory named output (which will contain your built Quartz site) into the Nginx container’s web root (/usr/share/nginx/html). :ro means read-only.
restart: unless-stopped: Ensures Nginx restarts automatically if the container stops or the VPS reboots.

Step 3: Build Your Quartz Site with Docker

Now, you need to generate your static Quartz site. We’ll use the official jackyzha0/quartz Docker image to do this directly on your VPS.

Ensure your Quartz source files are in ~/quartz4. This includes your content/ folder, quartz.config.ts, package.json, etc.
Run the Quartz build command: From your ~/quartz4 directory, execute:
```
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 automatically when it exits.
- -v "$(pwd):/app": Mounts your current directory (which is ~/quartz4 containing your Quartz project) into the container as /app. This allows the Docker image to access your source files and write to the output directory.
- jackyzha0/quartz: The official Quartz Docker image.
- npm install: Installs dependencies required by Quartz.
- npx quartz build: Executes the Quartz build command, generating your static site into the output directory within your ~/quartz4 project.
After this step, you should see an output directory created in your ~/quartz4 directory, containing all your static HTML, CSS, and JS files.

Step 4: Start Your Quartz Server

With your output directory populated and docker-compose.yml ready, you can now start your Nginx server.

From your ~/quartz4 directory, run:

docker compose up -d

docker compose up -d: Starts the services defined in docker-compose.yml in detached mode (in the background).

Your Quartz site should now be accessible via your VPS’s IP address or domain name on port 80 (HTTP).

Step 5: Configure Quartz (Rebuilding Your Site)

Quartz configuration primarily happens through quartz.config.ts and the quartz.layout.ts files in your project directory.

Edit your configuration: Make any desired changes to your quartz.config.ts, add new content to your content/ directory, or modify layouts.
```
# Example: edit quartz.config.ts
nano quartz.config.ts
```
Rebuild your site: After making any changes to your source files or configuration, you must rebuild your Quartz site for the changes to take effect.
```
cd ~/quartz4
docker run --rm -v "$(pwd):/app" jackyzha0/quartz npx quartz build
```
The Nginx container will automatically serve the updated files from the output directory without needing a restart.

Step 6: (Optional) Set up SSL with Certbot

For production sites, HTTPS is essential. You can use Certbot with Nginx to easily obtain and renew SSL certificates.

Ensure port 443 is open in your VPS firewall and uncommented in docker-compose.yml.
Install Certbot: Follow the instructions for Nginx on your specific Linux distribution from certbot.eff.org.
Run Certbot:
```
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
```
Certbot will automatically configure Nginx and set up automatic renewals. You may need to adjust your Nginx container’s volume mapping if Certbot modifies /etc/nginx/sites-available or similar; a simpler approach might be to stop your Nginx container, let Certbot configure a temporary Nginx on the host, get the certs, then manually update your nginx_custom.conf and restart your Dockerized Nginx. For a simpler path, you might consider a reverse proxy like Traefik or Caddy handling SSL in front of your Nginx container.

Conclusion

You have successfully installed and configured Quartz 4 on your Linux VPS using Docker and Docker Compose. Your static site is now served by Nginx, and you can easily update your content by rebuilding your Quartz project with a simple Docker command. This setup provides a robust, maintainable, and scalable solution for your digital garden or knowledge base. Enjoy sharing your thoughts with the world!