Onboarding 🚀

Onboarding Guide 🌱

This document outlines the step-by-step procedure required to onboard a new user onto the NAS infrastructure, provision their personal Hermes AI Agent, and configure their Obsidian LiveSync environment.

Step 1: Accessing NAS via TailScale VPN

TailScale VPN

Access to the NAS in the local area network (LAN) requires secure connection via TailScale

1. [User] Create a personal TailScale account
2. [Admin] Invite the [User] to the admin’s TailNet via the Tailscale Admin Console.
3. [User] Accept the invitation & install the TailScale application on your local machine.
4. [User] Login to TailScale & the device will automatically register to TailNet.

Network Attached Storage (NAS)

The core of the entire system, where all the configurations & deployments occur.

1. [Admin] Add [User] under User Management
   1. Setup username & password
2. [Admin] Setup the following directories
   1. /home/<Username>/vault for Obsidian vault
   2. /hermes/.hermes.username for user-specific Hermes AI configuration
      1. Decision:
3. [User] Login & access via NAS Desktop or TailNet host name

[Note] I decided to prioritise Bind Mounts over Named Volumes – volumes: test_vault: - Named Volumes are Docker-managed, which becomes a configuration black-hole. - Bind Mounts grants administrators direct visibility and greater control over configuration management on the NAS.

---

Step 2: Setup Hermes Agent with Telegram

Hermes Agent

Each user’s Hermes Agent is bound to a single, dedicated Telegram Bot. This isolation requires deploying a separate Docker container for every onboarded user.

Steps:

1. [Admin] Update docker-compose.yaml to add a new service container for the new user.
2. [User] Message @BotFather on Telegram to generate a new bot, then retrieve your TELEGRAM_BOT_TOKEN and personal TELEGRAM_USER_ID.
3. [User] (Optional) Set up an OpenRouter account and retrieve an API key to configure custom LLM models.
4. [Admin] Add these values to /hermes/.env
5. [Admin] Redeploy the stack

Networking Configuration

Since we’re using Caddy reverse proxy, we’ll need to expose the web interface to allow the user to access & configure Hermes Agent Dashboard

Steps:

1. [Admin] Allocate a unique, open host port for the new user’s Hermes Dashboard.
2. [Admin] Append a routing block in Caddyfile to securely proxy incoming traffic from the TailNet URL to the user’s designated backend port.

---

Step 3: Setup Obsidian Vault with LiveSync

Obsidian Vault

Vault stored locally on your device where all your notes, attachments, settings are stored. Effectively a brain that you can see, modify and extend with new thoughts and ideas.

1. [User] Install Obsidian application to your device.
2. [User] Create a new vault or mount it onto an existing directory.
3. [User] In the Settings, enable Community Plugins.

(NAS) Obsidian LiveSync

Instead of re-inventing the wheel, this community plugins coordinates the real-time live syncing feature of Obsidian Vault using CouchDB & PouchDB (JavaScript version) across all devices.

1. See Obsidian Livesync – README.md for documentation
2. [Admin] From CouchDB UI, add a new database for the user – DATABASE_NAME
3. [User] Install Obsidian LiveSync under Community Plugins
4. [User] Under Settings – Obsidian LiveSync,
   1. Under Remote Configuration, fill in the following:
      1. TailNet URL: <tailnet.ts.net>:8444
      2. Username, Password, DATABASE_NAME
      3. Test connection should be successful
   2. Under Remote Configuration,
      1. Setup End-to-End Encryption with Passphrase
      2. Will start replicating chunks from local vault to the remote vault via CouchDB
   3. Under Sync Settings,
      1. Enable Sync Mode: LiveSync for real-time synchronisation between local & remote vaults
      2. Otherwise, you may choose other sync modes as well

(NAS) Obsidian LiveSync CLI

Similar to how other devices require an Obsidian Client for syncing the local vault with the remote vault, this Headless CLI setup ensures that changes made within the NAS (i.e. by Hermes Agent) can be synced with all other devices.

1. See Obsidian Livesync CLI – README.md for documentation
2. [Admin] Ensure that obsidian-livesync-cli is properly configured
   1. Add .livesync/settings.json with required configurations
   2. Setup network bridge between couchdb & obsidian-livesync
   3. Directly use couchDB_URI = http://couchdb:5984 for connection
3. [Admin] Ensure that the remote DB is unlocked :LiUnlockKeyhole:
   1. Remote DB might be locked, will need to overwrite remote server data ⚠
   2. This allows the obsidian-livesync-cli to write changes to the remote couchDB
4. [Admin] Plugin will run the following commands:
   1. livesync-cli mirror : Local $\leftarrow$ CouchDB
   2. livesync-cli sync : Local $\to$ CouchDB
   3. livesync-cli mirror : Local $\leftarrow$ CouchDB

---

(Optional) Setup Hermes MCP server Integration

iujinwee-vault-plugin MCP Server

This MCP server was built & customised for my personal vault management workflow.

1. [Admin] Build the Go binary for UGREEN NAS compatible OS using the following command:

env GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o vault-plugin ./cmd/server

2. [Admin] Upload the binary file to NAS
3. [Admin] Update the permission of the binary file using the following command:

sudo chmod -R 777 /volume1/docker/hermes/vault-plugin

4. [Admin] Configure Hermes MCP configuration via the Dashboard
5. You should see the tools made available by iujinwee-vault-plugin!

Thanks for reading all the way up until here, hope this guide was useful :LiSmilePlus: