Syncing and Backing Up Obsidian Notes with Syncthing and GitHub

6 mins read

#tools

#productivity

cover image

Introduction

I’ve made Obsidian my go-to tool for organizing thoughts, capturing ideas, and maintaining a robust knowledge management system. Obsidian stores all your notes within a Vault which is basically the main folder containing subfolders, markdown files, images, and other assets. While Obsidian offers options like iCloud or their paid Obsidian Sync service for syncing and storing vaults, I wanted a setup that gives me more control over how and where my notes are managed.

In this article, I’ll share how I synchronize my notes across devices and ensure they’re securely backed up. My hope is to inspire you to create a system that works seamlessly for your needs.

Overview of the Setup

To synchronize notes across devices and back them up securely, I rely on two tools:

Syncthing

Setting Up Syncthing on Laptop

To run Syncthing, I chose to use Docker Compose instead of installing it directly from the Arch Linux repositories. While Syncthing is readily available in the official package repositories, I wanted to avoid potential version mismatches across my devices. Using Docker ensures that I can run the same version consistently on both my desktop and server, simplifying maintenance and compatibility.

Here’s the Docker Compose file I use:

docker-compose.yml
services:
syncthing:
image: syncthing/syncthing
container_name: syncthing
hostname: my-syncthing
environment:
- PUID=1000
- PGID=1000
volumes:
- /home/ouassim/st-sync:/var/syncthing
- /home/ouassim/ouassim-notes:/var/syncthing/ouassim-notes # path to your obsidian vault
ports:
- 8384:8384 # Web UI
- 22000:22000/tcp # TCP file transfers
- 22000:22000/udp # QUIC file transfers
- 21027:21027/udp # Receive local discovery broadcasts
restart: unless-stopped
healthcheck:
test: curl -fkLsS -m 2 127.0.0.1:8384/rest/noauth/health | grep -o --color=never OK || exit 1
interval: 1m
timeout: 10s
retries: 3

This configuration mounts two volumes:

It also exposes the necessary ports for the Web UI, file transfers, and local discovery. The health check ensures Syncthing remains operational, with automatic retries if issues occur.

The restart: unless-stopped directive ensures that Syncthing will automatically restart if it crashes or if the device (server or laptop) is rebooted. The container will only stop if you explicitly stop it with docker compose down.

To start up the container, simply run the following command in the directory where your docker-compose.yml is located:

Terminal window
docker compose up -d

This will start the Syncthing container in detached mode, allowing it to run in the background. Once Syncthing is running, you can access the Web UI by navigating to http://localhost:8384 in your browser.

Creating a Shared Folder for Your Obsidian Vault

Once Syncthing is up and running, the next step is to create a shared folder for your Obsidian Vault. You can either select an existing Vault or create a new one specifically for syncing.

Steps to Set Up the Shared Folder

  1. Open the Syncthing Web UI at http://localhost:8384.

  2. Click on Add Folder and configure the following:

    • Folder Label: A descriptive name for your Obsidian Vault (e.g., “Obsidian Notes”).
    • Folder Path: The location of your Vault on the device (e.g., /home/ouassim/ouassim-notes).

      Note: This path must match the folder you mounted in the Docker Compose volumes we shared earlier.

  3. Set up ignore rules to exclude unnecessary files. Navigate to the Ignore Patterns tab for the folder and add the following rules:

    .stignore
    // WARNING: Syncthing does not synchronise this file (.stignore)
    // During setup on a new device, create a copy of the .stignore file located under "50 Resources/"
    // most important one. this keeps track of your open panes and files in the app
    .obsidian/workspace
    .obsidian/workspace.json
    // vault stats are not useful
    .vault-stats
    // Ignore the Git repository
    .git
    .gitignore

    These patterns exclude temporary files, Git-related files, and Obsidian-specific workspace configurations that don’t need to be synced.

Setting Up Syncthing on Android

To synchronize my Obsidian Vault with my Android phone, I used Syncthing-Fork, an optimized version of Syncthing available on the Play Store. It’s lightweight and has a much lower impact on battery life, making it my top recommendation for Android users.

Connecting the Android Phone to the PC

  1. Install Syncthing-Fork on your phone from the Play Store.

  2. Add your PC as a remote device:

    • On your phone, go to Devices > Add > Scan QR Code.
    • On your PC, open the Syncthing Web UI and click Actions > Show ID.
    • Scan the QR code from your phone.
  3. Accept the connection on both the phone and PC.

This process works seamlessly when both devices are on the same WiFi network.

Sharing the Obsidian Vault Folder

  1. Create an empty folder at the root of your phone’s file system to store the synchronized files (e.g., /storage/emulated/0/ObsidianVault).
  2. On your PC, share the Obsidian Vault folder with your Android phone:
    • Open the folder settings in the Syncthing Web UI and click Edit > Sharing.
    • Select your phone as the target device.
  3. Accept the share notification on your phone.

Configuring the Shared Folder on Android

  1. On your phone, set the newly created folder (e.g., /storage/emulated/0/ObsidianVault) as the destination for the shared files.
  2. Once synchronization starts, copy the .stignore file from your Vault to the root of the synced folder on your phone to apply the same ignore rules.

Opening the Folder in Obsidian

Finally, open the synchronized folder as a Vault in Obsidian on your phone. Once configured, Syncthing will automatically keep your notes synchronized across devices!

Backing Up Your Notes to GitHub

While Syncthing keeps my notes synchronized across devices, I rely on GitHub for backups and version control. By using Git, I can track changes, revert to previous versions, and have an offsite backup in case of data loss.

Step 1: Initialize a Git Repository

  1. Navigate to your Obsidian Vault folder on your PC.

  2. Open a terminal and run the following commands:

    Terminal window
    git init
    git remote add origin https://github.com/<your-username>/<your-repo>.git

    Replace <your-username> and <your-repo> with your GitHub username and repository name.

Step 2: Create a .gitignore File

To avoid pushing unnecessary files to GitHub, create a .gitignore file in your Vault with the following content:

.gigignore
# Ignore vault stats
.vault-stats
# Ignore Syncthing versioned files
.stversions

Step 3: Commit and Push Changes

  1. Stage all files for the initial commit:

    Terminal window
    git add .
  2. Commit the changes:

    Terminal window
    git commit -m "Initial commit of Obsidian Vault"
  3. Push the changes to GitHub:

    Terminal window
    git branch -M main
    git push -u origin main

Conclusion

By combining Syncthing and GitHub, I’ve set up a robust system for syncing and backing up my Obsidian notes across devices.

This setup might not be the simplest, but it’s tailored to my needs for privacy, flexibility, and control. If you’re looking for a similar solution, I hope this guide inspires you to take control of your own note synchronization and backup workflow.

If you have any questions or alternative approaches, feel free to share, I’d love to hear how others tackle this challenge!

Thanks for reading, Happy note-taking! 🚀