97 lines
6.4 KiB
Markdown
97 lines
6.4 KiB
Markdown
# 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 |