# 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](https://quartz.jzhao.xyz/) 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](https://docs.docker.com/engine/install/)
-   [Docker Compose](https://docs.docker.com/compose/install/) (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:**
    ```bash
    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:**
    ```bash
    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:
```bash
cd /path/to/your/my-quartz-deployment
./update_quartz_docker.sh