Quartz v4 Docker Image

This repository provides ready Docker image for Quartz v4, an open-source tool for publishing digital gardens and Obsidian vaults.

Credits: All credit for Quartz goes to jackyzha0. This repository only handles the containerization process.

Purpose

This image is designed for local network use or VPN-only environments (like Tailscale/Headscale). It utilizes the npx quartz build --serve command, meaning it actively watches your mounted Markdown files and provides real-time Hot-Reloading via WebSockets.

Important Security Disclaimer & Recommendations

I DO NOT recommend exposing this image directly to the public internet "as is".

Because this image runs a continuous Node.js runtime to facilitate live-syncing and WebSocket connections (port 3001), it naturally has a larger attack surface than a static web server. It contains several npm dependencies that are strictly meant for the build process but remain present in the runtime to allow on-the-fly rebuilding.

For Public Production Environments: If you plan to expose your digital garden to the internet via Cloudflare, Caddy, or Nginx, you should use a 3-stage static build approach. In a production setup, Quartz should only be used to generate the /public static HTML/CSS files during a CI/CD pipeline, and those files should be served by a pure, stripped-down web server (like Caddy file_server or Nginx) without any Node.js runtime attached.

How to Use

1. Copy the compose.yml.example file to docker-compose.yml.

2. Edit the volume paths to point to your local Obsidian vault.

3. Run the stack:

       docker compose up -d
   

Ports

• 8080: Main HTTP Web Server.
• 3001: WebSocket Server (Required for Live Hot-Reloading).

Volumes & Permissions

• /usr/src/app/content: Mount your Markdown files here. Always use :ro (Read-Only) as shown in the compose file. This ensures the container can never accidentally corrupt or overwrite your personal vault data.

Environment Variables

Currently, no explicit environment variables are required for basic functionality. If you need to customize Quartz behavior, you should bind-mount your customized quartz.config.ts and quartz.layout.ts over the default ones inside /usr/src/app/.

This image implements several sysadmin-grade security practices:

Other Features

• Non-Root Execution: The process runs as the standard, unprivileged node user (UID 1000).
• Capability Drop: The compose.yml.example explicitly drops all Linux Kernel capabilities (cap_drop: - ALL).
• No New Privileges: Prevents privilege escalation vectors.
• Automated Scanning: Built monthly via GitHub Actions and scanned by Trivy. If CRITICAL or HIGH vulnerabilities are detected, the build fails and prevents publishing.
• Built-in Healthcheck: Docker automatically monitors the container via curl to ensure the HTTP server is responsive.

How to Build Locally

If you want to build the image yourself instead of pulling from GHCR:

docker compose up -d --build

You can specify a target Quartz version/tag by passing a build argument:

docker build --build-arg QUARTZ_VERSION=v4.2.3 -t quartz-custom .

Liability

This project is provided "as is" without warranty of any kind. You are solely responsible for ensuring the security of your network and infrastructure.