Automated Docker Deployment for My Quartz Digital Garden

Last Updated: May 29, 2025

1. Overview

This repository contains the configuration and automation scripts to build, deploy, and automatically update a Quartz static site using Docker. The site content is sourced directly from a specified Obsidian vault directory, allowing for seamless updates when notes are changed.

The setup uses:

• Docker: To containerize the Quartz build process and the NGINX web server.
• Docker Compose: To manage the Docker build and deployment lifecycle.
• NGINX: As the web server for the static site, with custom configuration for Quartz's clean URLs.
• Multi-Stage Dockerfile: For an efficient build, separating the Node.js build environment from the final NGINX runtime environment.
• Shell Script (update_quartz_docker.sh): The core automation script that handles:
  • Cloning/updating the Quartz framework source code.
  • Detecting changes in your Obsidian content.
  • Preparing content for the Docker build.
  • Triggering Docker image rebuilds and container deployments.
• Cron Job: For scheduling the update_quartz_docker.sh script to run periodically.

2. Prerequisites

Before you begin, ensure you have the following installed on your host system (e.g., NALTHIS):

• Docker Engine
• Docker Compose (The script uses docker-compose V1/V2 syntax)
• git
• rsync (used by the update script for copying content: sudo apt install rsync)
• Your Obsidian vault containing the Quartz content accessible on the host system.

3. Repository Structure

Key files in this repository:

• Dockerfile: Defines the multi-stage Docker build for building Quartz and serving it with NGINX.
• docker-compose.yml: Configures the Docker Compose service for the Quartz site.
• update_quartz_docker.sh: The main automation script for updates and deployment.
• custom_nginx.conf: Custom NGINX configuration for serving Quartz (handles clean URLs).
• quartz.config.ts: Your primary Quartz configuration file.
• quartz.layout.ts: (If customized) Your Quartz layout configuration.
• .gitignore: Ignores transient files, including the cloned quartz/ directory.

External/Ignored Directories (managed by update_quartz_docker.sh):

• ./quartz/: A local clone of the Quartz framework, managed by the update script. This directory is added to .gitignore.
• ./content/: A temporary directory created by the update script during builds to hold a copy of your Obsidian content. This directory is added to .gitignore.

4. Setup and Configuration

1. Clone this Repository:

   git clone <your-repo-url> my-quartz-deployment
   cd my-quartz-deployment
   

2. Configure update_quartz_docker.sh: Open update_quartz_docker.sh and carefully review and update the following configuration variables at the top of the script:

   • QUARTZ_PROJECT_DIR: Should be the absolute path to this my-quartz-deployment repository on your host. (e.g., /home/hoid/projects/my-quartz-deployment).
   • OBSIDIAN_CONTENT_SOURCE: Crucial! The absolute path to the specific folder in your Obsidian vault that contains the Markdown files and assets for your Quartz site (e.g., /home/hoid/docker/obsidian/vaults/weeslahw_coppermind/Digital_Garden).
   • QUARTZ_FRAMEWORK_BRANCH: The branch or tag of the jackyzha0/quartz repository you want to use (e.g., v4, main, or a specific version tag like v4.2.5).
   • DOCKER_COMPOSE_CMD: The absolute path to your docker-compose executable. Find this by running which docker-compose in your terminal. (e.g., /usr/local/bin/docker-compose).
   • LOG_FILE: Path to where the script will write its logs.

3. Customize Quartz Files:

   • Ensure your quartz.config.ts, quartz.layout.ts (if used), and any other custom Quartz files (e.g., in assets/, components/ if you have them at the root of this deployment repo) are set up as desired.
   • Verify custom_nginx.conf meets your needs (the default provided should work for Quartz).

4. Make the script executable:

   chmod +x update_quartz_docker.sh
   

5. How It Works

The automation relies on the update_quartz_docker.sh script:

1. Quartz Framework: The script first ensures a local clone of the Quartz framework (from the branch/tag specified in QUARTZ_FRAMEWORK_BRANCH) exists in the ./quartz/ directory. It will clone it if missing or attempt to update it if it exists.
2. Change Detection: It checks if any files in your OBSIDIAN_CONTENT_SOURCE directory are newer than a timestamp file (.last_build_content_timestamp) stored in this project's root. If no changes are detected, the script exits early.
3. Content Preparation: If changes are found (or on the first run):
   • It removes any old temporary ./content/ directory.
   • It creates a new ./content/ directory.
   • It uses rsync to copy all files from your OBSIDIAN_CONTENT_SOURCE into this temporary ./content/ directory. This directory now becomes part of the Docker build context.
4. Docker Deployment:
   • It runs docker stop <container_name> and docker rm -f <container_name> to preemptively remove any existing container with the target name, ensuring a clean slate.
   • It runs docker-compose down --remove-orphans --volumes to further clean up any resources managed by Docker Compose for this project.
   • It then runs docker-compose up -d --build --remove-orphans. This command:
     • Builds a new Docker image using the Dockerfile. The Dockerfile copies the ./quartz/, your custom config files (like quartz.config.ts), and the prepared ./content/ directory into the builder stage. npm ci is run using the framework's package.json, and then npx quartz build compiles your site. The resulting static files are copied into a final NGINX image.
     • Starts a new container from the freshly built image in detached mode (-d).
5. Timestamp & Cleanup:
   • If the deployment is successful, the .last_build_content_timestamp file is updated.
   • The temporary ./content/ directory is removed to keep the project directory clean.

6. Usage

A. Manual Deployment/Update

You can run the script manually at any time to build and deploy your site:

cd /path/to/your/my-quartz-deployment
./update_quartz_docker.sh