Add Obsidian (with git sync), Eclipse Mosquitto, Gitea, ESPHome and MS SQL Server 2025

.claude/commands/implement-container-deployment.md

@@ -13,7 +13,7 @@ Follow closely the architectural patterns described in the `docker/guidelines.md
 ### Part 1 - Create Docker Compose file
 
 - Read the `docker/guidelines.md` file for the architectural patterns you must follow.
-- Read the INSTALL_INSTRUCTIONS_FILE file and use its content to create the compose file in the required structure.
+- Read the INSTALL_INSTRUCTIONS_FILE file and use its content to create the compose file in the required structure. Abort if the file is not specified or does not exist.
 - Based on these patterns and the found examples on the installation instructions page, create the Docker Compose file and save it as `docker/<category>/<application>.yaml`.
 - Ensure the compose file contains a brief description of the project and links to the homepage, GitHub page, and any Docker or Docker Compose setup example (if available).
 - If the installation guide suggests enhancements (e.g., using an optional external database instead of a built-in one, or enabling SSO), add TODOs at the top of the compose file.

.pre-commit-config.yaml

@@ -10,7 +10,11 @@ repos:
       - id: trailing-whitespace
         args: ["--markdown-linebreak-ext=md,yaml"]
       - id: end-of-file-fixer
-        exclude: "docker/security/authelia/"
+        exclude: |
+            (?x)^(
+                docker/security/authelia/|
+                docker/automation/mosquitto/
+            )
       - id: mixed-line-ending
       - id: fix-byte-order-marker
       - id: check-merge-conflict

AGENTS.md

@@ -48,7 +48,7 @@ task docker:pull-update
 task docker:stop
 
 # Create/update Docker example environment configuration files
-task docker:create-example-env
+task docker:update-example-env
 ```
 
 ### Service Management

README.md

@@ -76,7 +76,7 @@ Some development workflows:
 Code quality scanning tools are set up via [pre-commit](https://pre-commit.com).
 Perform the checks by running `task lint` (or `pre-commit run --all-files`).
 
-Create/update example `.env` files: `task docker:create-example-env`.
+Create/update example `.env` files: `task docker:update-example-env`.
 
 ### GitHub automations
 

Taskfile.yaml

@@ -9,6 +9,7 @@ includes:
   docker: ./docker/Taskfile.docker.yaml
   app: ./docker/Taskfile.apps.yaml
   crowdsec: ./docker/security/Taskfile.crowdsec.yaml
+  obsidian: ./docker/tools/Taskfile.obsidian.yaml
   docs: ./docs/web/Taskfile.web.yaml
   devcontainer: ./.devcontainer/Taskfile.dev.yaml
   azure-vm:
@@ -55,7 +56,7 @@ tasks:
   build:
     desc: Run all linting and build tasks
     cmds:
-      - task: docker:create-example-env
+      - task: docker:update-example-env
       - task: docs-deploy
       - task: pre-commit-update
       - task: lint
@@ -130,6 +131,20 @@ tasks:
       - cd config && tar -cjf "../infra-config-backup/infra-config-$(date +%Y-%m-%d_%H-%M-%S).tar.bz2" .
       - ls -lh ../infra-config-backup/infra-config-*.tar.bz2 | tail -n 5
 
+  # Setup scheduling with command `crontab -e`, add this line:
+  # 0 1 * * * cd /home/buba/repos/infra && /home/linuxbrew/.linuxbrew/bin/task backup >> config/log/infra-backup.log 2>&1
+  backup:
+    desc: Create backup of the configuration directory and the Obsidian vault
+    silent: true
+    cmds:
+      - echo "=== Backup started at $(date) ==="
+      - task: backup-config
+      - task: obsidian:repo-backup
+      - |
+        if [ -f "config/sync-backup-to-remote.sh" ]; then
+            bash "config/sync-backup-to-remote.sh"
+        fi
+
   get-offline-data:
     desc: Download data files for offline use (stored both local and on Proxmox)
     cmds:

config-example/docker/myhost/.env

@@ -9,6 +9,7 @@ STORAGE_CALIBRE_LIBRARY=${STORAGE_LOCAL_MEDIA}/books
 STORAGE_CALIBRE_LIBRARY_HUN=${STORAGE_LOCAL_MEDIA}/books-hun
 STORAGE_WEBDAV=${STORAGE_LOCAL_MEDIA}/webdav
 STORAGE_KIWIX=${STORAGE_LOCAL_MEDIA}/kiwix
+STORAGE_OBSIDIAN=${STORAGE_LOCAL_MEDIA}/obsidian
 
 DOCKER_VOLUMES=${STORAGE_LOCAL}/docker-volumes
 
@@ -90,6 +91,23 @@ COUCHDB_PASSWORD="use-some-very-secure-value-here"
 OBSIDIAN_LIVESYNC_DATABASE_NAME="obsidian"
 OBSIDIAN_LIVESYNC_PASSPHRASE="use-some-very-secure-value-here"
 
+# Optional Obsidian container authentication
+# OBSIDIAN_CUSTOM_USER="user"
+# OBSIDIAN_PASSWORD="use-some-very-secure-value-here"
+# OBSIDIAN_LC_ALL="en_US.UTF-8"
+
+### Gitea configuration
+# Generate these with: docker run --rm gitea/gitea:1.24.6 gitea generate secret SECRET_KEY
+GITEA_SECRET_KEY="use-some-very-secure-value-here"
+# Generate these with: docker run --rm gitea/gitea:1.24.6 gitea generate secret INTERNAL_TOKEN
+GITEA_INTERNAL_TOKEN="use-some-very-secure-value-here"
+
+### Microsoft SQL Server configuration
+# Password requirements: At least 8 characters, with uppercase, lowercase, numbers, and special characters
+MSSQL_SA_PASSWORD="use-some-very-secure-value-here"
+# Optional: Custom collation (default: SQL_Latin1_General_CP1_CI_AS)
+# MSSQL_COLLATION="SQL_Latin1_General_CP1_CI_AS"
+
 ### Cloud accounts
 
 CLOUDFLARE_DNS_API_TOKEN="use-some-very-secure-value-here"

config-example/docker/myhost/services.yaml

@@ -1,4 +1,5 @@
 # Docker service configuration for myhost
+# yaml-language-server: $schema=../services-schema.yaml
 ---
 services:
   - security:
@@ -46,8 +47,10 @@ services:
         state: up
       - name: n8n
         state: up
-      - name: olivetin
-        state: down
+      - name: mosquitto
+        state: up
+      - name: esphome-device-builder
+        state: up
 
   - media/video:
       - name: jellyfin
@@ -89,6 +92,8 @@ services:
         state: up
       - name: couchdb
         state: up
+      - name: mssql-server
+        state: up
 
   - backup:
       - name: kopia-nas
@@ -101,6 +106,8 @@ services:
   - dev:
       - name: code-server
         state: up
+      - name: gitea
+        state: up
       - name: gitlab
         state: down
       - name: jupyter-notebook
@@ -123,6 +130,8 @@ services:
         state: up
       - name: searxng
         state: up
+      - name: obsidian
+        state: up
 
   - ai:
       - name: ollama
@@ -151,9 +160,9 @@ services:
         state: down
       - name: bazarr
         state: down
-      # TODO replace with Lazy Librarian
-      - name: readarr
-        state: down
+      # TODO Deprecated - replace with Lazy Librarian - https://lazylibrarian.gitlab.io/
+      # - name: readarr
+      #   state: down
       - name: prowlarr
         state: down
       - name: jellyseerr

config-example/docker/services-schema.yaml

@@ -0,0 +1,51 @@
+# YAML Schema definition for the Docker service configuration file
+
+$schema: http://json-schema.org/draft-07/schema#
+title: Docker Service Configuration
+description: Configuration schema for Docker services in a homelab environment
+type: object
+
+properties:
+  services:
+    type: array
+    description: Categories of Docker services
+    items:
+      type: object
+      additionalProperties:
+        type: array
+        description: List of services in a specific category
+        items:
+          type: object
+          required:
+            - name
+            - state
+          properties:
+            name:
+              type: string
+              description: Name of the Docker service
+            state:
+              type: string
+              description: Current state of the service
+              enum:
+                - up
+                - down
+            note:
+              type: string
+              description: Optional note about the service
+
+examples:
+  - services:
+      - security:
+          - name: crowdsec
+            state: up
+          - name: traefik
+            state: up
+      - dashboard:
+          - name: homepage
+            state: up
+      - media/video:
+          - name: jellyfin
+            state: up
+            note: Storage on NAS
+
+additionalProperties: false

docker/Taskfile.docker.yaml

@@ -66,17 +66,20 @@ tasks:
     cmds:
       - docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once --cleanup --monitor-only
 
-  create-example-env:
+  update-example-env:
     desc: Create/update Docker example environment configuration files
     dotenv: ['config/docker/.env']
     cmds:
-      - scripts/create-example-env.py config/docker/.env > config-example/docker/.env
-      - scripts/create-example-env.py config/docker/${MAIN_NODE}/.env > config-example/docker/myhost/.env
+      - scripts/update-example-env.py config/docker/.env > config-example/docker/.env
+      - scripts/update-example-env.py config/docker/${MAIN_NODE}/.env > config-example/docker/myhost/.env
       - cat config/docker/${MAIN_NODE}/services.yaml | sed "s/${MAIN_NODE}/myhost/g" > config-example/docker/myhost/services.yaml
+      - cp config/docker/services-schema.yaml config-example/docker/services-schema.yaml
     sources:
       - config/docker/**/.env
       - config/docker/**/services.yaml
+      - config/docker/services-schema.yaml
     generates:
       - config-example/docker/.env
       - config-example/docker/myhost/.env
       - config-example/docker/myhost/services.yaml
+      - config-example/docker/services-schema.yaml

docker/automation/esphome-device-builder.yaml

@@ -0,0 +1,44 @@
+# ESPHome Device Builder is a tool for creating custom firmware for ESP8266/ESP32 microcontrollers
+# through simple YAML configuration files and managing them through Home Automation systems like Home Assistant.
+#
+# 🏠 Home: https://esphome.io
+# 📦 Source: https://github.com/esphome/esphome
+# 📜 Docs: https://esphome.io/guides/getting_started_command_line/#bonus-esphome-device-builder
+# Docker: https://hub.docker.com/r/esphome/esphome
+#
+# TODO: Consider implementing non-privileged mode with specific device permissions for improved security
+# TODO: Set up udev rules for automatic USB device discovery
+---
+name: esphome-device-builder
+services:
+  esphome-device-builder:
+    image: esphome/esphome:2025.9
+    container_name: esphome-device-builder
+    restart: unless-stopped
+    network_mode: host
+    environment:
+      TZ: ${TIMEZONE}
+      PUID: ${PUID}
+      PGID: ${PGID}
+    # kics-scan ignore-block
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+    # Not needed due to 'network_mode: host'
+    # ports:
+    #   - "6052:6052"
+    # Required for USB device access
+    # kics-scan ignore-line
+    # privileged: true
+    # For USB device passthrough (uncomment and adjust as needed):
+    # devices:
+    #  - /dev/ttyUSB0:/dev/ttyUSB0
+    labels:
+      traefik.enable: true
+      traefik.http.routers.esphome-device-builder.rule: Host(`esphome.${MYDOMAIN}`)
+      traefik.http.routers.esphome-device-builder.middlewares: localaccess@file
+      traefik.http.services.esphome-device-builder.loadbalancer.server.port: 6052
+      homepage.group: Automation
+      homepage.name: ESPHome Builder
+      homepage.icon: esphome.png
+      homepage.href: https://esphome.${MYDOMAIN}/
+      homepage.description: "Firmware builder for ESP devices"

docker/automation/mosquitto.yaml

@@ -0,0 +1,45 @@
+# Eclipse Mosquitto is an open-source MQTT broker implementing versions 5.0, 3.1.1, and 3.1 of the MQTT protocol.
+# It is lightweight and suitable for devices from single board computers to full servers, providing publish/subscribe
+# messaging capabilities with support for TLS, WebSockets, and various authentication methods.
+#
+# 🏠 Home: https://mosquitto.org/
+# 📦 Source: https://github.com/eclipse/mosquitto
+# 📜 Docs: https://hub.docker.com/_/eclipse-mosquitto
+# Configure Authentication: https://mosquitto.org/documentation/authentication-methods/
+#
+# TODO: Consider enabling TLS/SSL certificates for secure connections on port 8883
+# TODO: Implement authentication with password file and ACL for access control
+# TODO: Configure performance tuning for high-throughput environments (max_connections, max_queued_messages)
+---
+name: mosquitto
+services:
+  mosquitto:
+    image: eclipse-mosquitto:2.0.22-openssl
+    container_name: mosquitto
+    restart: unless-stopped
+    environment:
+      TZ: ${TIMEZONE}
+    ports:
+      - "1883:1883"  # Standard MQTT
+      - "8883:8883"  # MQTT over TLS
+      - "9001:9001"  # WebSockets
+    volumes:
+      - ./mosquitto:/mosquitto/config
+      - ${DOCKER_VOLUMES}/mosquitto/data:/mosquitto/data
+      - ${DOCKER_VOLUMES}/mosquitto/log:/mosquitto/log
+    networks:
+      - proxy
+    labels:
+      traefik.enable: true
+      traefik.http.routers.mosquitto.rule: Host(`mosquitto.${MYDOMAIN}`)
+      traefik.http.routers.mosquitto.middlewares: localaccess@file
+      traefik.http.services.mosquitto.loadbalancer.server.port: 9001
+      homepage.group: Automation
+      homepage.name: Eclipse Mosquitto
+      homepage.icon: mosquitto.png
+      homepage.href: https://mosquitto.${MYDOMAIN}/
+      homepage.description: "Open-source MQTT broker"
+
+networks:
+  proxy:
+    external: true

docker/automation/mosquitto/mosquitto.conf

@@ -0,0 +1,36 @@
+# Eclipse Mosquitto Configuration File
+# More information: https://mosquitto.org/man/mosquitto-conf-5.html
+
+# Persistence settings
+persistence true
+persistence_location /mosquitto/data/
+
+# Logging settings
+log_dest file /mosquitto/log/mosquitto.log
+log_type error
+log_type warning
+log_type notice
+log_type information
+
+# Connection settings
+allow_anonymous true
+
+# Default MQTT port
+listener 1883
+
+# WebSocket port for web clients
+listener 9001
+protocol websockets
+
+# TLS/SSL settings (uncomment and configure certificates if needed)
+# listener 8883
+# cafile /mosquitto/config/ca.crt
+# certfile /mosquitto/config/server.crt
+# keyfile /mosquitto/config/server.key
+
+# Authentication settings (uncomment to enable)
+# allow_anonymous false
+# password_file /mosquitto/config/passwd
+
+# Access Control List (uncomment to enable)
+# acl_file /mosquitto/config/acl.conf