Trilium Docker Stack Sync

A Python script to automatically synchronize and document your Docker Compose stacks within Trilium Notes. It provides a structured, visual representation of your infrastructure, complete with service details, configuration management, and lifecycle tracking.

🚀 Key Features

• Automated Documentation: Automatically creates and updates notes in Trilium for your Docker hosts, stacks, and individual services.
• Service Details: Extracts key information from docker-compose.yml (images, ports, restart policies) and formats them into clean HTML service notes.
• Lifecycle Management:
  • Automatically moves stacks between "Active" and "Decommissioned" states.
  • Tracks stack history by linking to Trilium's Day notes with prefixes like Deployed, Updated, and Decommissioned.
• Configuration Sync: Syncs your docker-compose.yml and, optionally, .env files directly into Trilium as code notes for easy reference.
• Bi-directional Metadata: Injects Trilium deep links and metadata back into your local compose files as comments.
• Template Support: Automatically applies predefined Trilium templates to ensure consistent styling across your documentation.
• Idempotent Attributes: Aggressively deduplicates note attributes and labels to keep your Trilium instance clean.

🛠️ Installation & Setup

1. Prerequisites

Ensure you have Python 3 and a running Trilium Notes instance with ETAPI enabled.

2. Install Dependencies

pip install -r requirements.txt

3. Configuration

Create a config.json in the project root with your Trilium details:

{
    "trilium_url": "https://your-trilium-url.com",
    "etapi_token": "YOUR_ETAPI_TOKEN",
    "parent_note_id": "PARENT_NOTE_ID_FOR_HOSTS",
    "sync_env_files": false,
    "stacks_dir": "/path/to/stacks"
}

• trilium_url: The base URL of your Trilium instance.
• etapi_token: Your ETAPI token (found in Trilium under Options -> ETAPI).
• parent_note_id: The ID of the note where you want host documentation to be created.
• sync_env_files: (Optional) Boolean to allow or suppress the synchronization of .env files to Trilium. Defaults to false.
• stacks_dir: (Optional) The directory where your Docker stacks are located. Defaults to ~/stacks if omitted.

📂 Project Structure

• Sync_Script.py: The main synchronization logic.
• config.json: Configuration for your Trilium instance.
• requirements.txt: Python library dependencies (requests, pyyaml, markdown).

📖 Usage

Standard Sync

The script looks for Docker stacks in the directory defined by stacks_dir in your config (defaulting to ~/stacks/). Each subdirectory is treated as a stack if it contains a docker-compose.yml (or .yaml).

python3 Sync_Script.py

Deactivating Stacks

To mark a stack as decommissioned, simply rename your compose file to include a .inactive suffix (e.g., docker-compose.yml.inactive). The script will:

1. Rename the Trilium note to include "(Deactivated)".
2. Set a decommDate attribute.
3. Move the note to a "Decommissioned Stacks" archive.
4. Link it to the current day in the Trilium calendar as "Decommissioned".

🧩 Templates

The script relies on several templates to maintain a consistent look and feel. For detailed instructions on how to set these up in your Trilium instance, see the Templates README.

The following templates should be created:

• Host Documentation Template
• Docker Stack Template
• Docker Container Template