Gitea with Docker for syncing Obsidian notes
The goal is to spin a lightweight self-hosted git server. I already have gitlab, but it is quite heavy to run. I want a simple solution.
The main goal is to be able to use obsidian on MacOS, Iphone, Windows and Linux.
My setup is 100% local and behind a VPN.
You can setup multiple git remotes to push to different servers.
Currently I’m using iCloud to sync the content but I had lost a document (retrieved successfully with the local snapshot feature) But using the power of git makes more sense for me, and it will work on multiple platform.
Gitea Installation
I’ll use Docker to simplify everything,
I followed this documentation: https://docs.gitea.io/en-us/install-with-docker-rootless/
docker-compose.yml
version: "2"
services:
gitea-server:
image: gitea/gitea:1.16.5-rootless
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
For my requirements, I’ll stick with the SQLite3 database, but if you need something more powerful, add the MySQL/Postgres instance. Also for this article, I’ll keep the default values
Start the Gitea server
docker-compose up -d
Configuration
Access the web page using http://localhost:3000
Fill the form with your information, I’ve used the default values for all of them. This is only a POC.
First User
Click on register to create the first user, then you will be able to create new organization and repositories.
That new user is administrator by default.
So far I really like the UI (Github Style), the usage everything is as expected and it runs well on a Macbook air. The setup took me 3 minutes to bring up ! And I’ve been able to connect my iPhone easily.
Obsidian
Gitea will be deployed in either a raspberry Pi or an existing server, and everything is behind a VPN.
The plan,
With Windows, linux and MacOS; It is quite straigthforward to configure,
- clone the repository locally from gitea
- open the folder with obsidian
- Obsidian Configuration:
- Install the community
Shell Command
plugin - You will be able to execute the
sync.sh
andpull.sh
scripts using hotkeys to simplify the flow. - Create a new Shell command and use that kind of command :
/bin/sh /Users/tgingras/Documents/test-gitea/sync.sh
-
The scripts are commited within the notes to facilitate the tracking and maintenance.
- Set an Alias for the command :
sync with gitea
- You can also select the event :
Before Obsidian quits
, that way you will always push your local changes (if any) - Check the
Ask confirmation before execution
to avoid bad surprises
-
- Create another new Shell command and use that kind of command :
/bin/sh /Users/tgingras/Documents/test-gitea/pull.sh
-
The scripts are commited within the notes to facilitate the tracking and maintenance.
- Set an Alias for the command :
pull from remote
- You can also select the event :
After Obsidian starts
, that way you will always pull the remote.
-
- Then to simplify the flow, go to
Hotkeys
and configure an hotkey for the new commands. (I’ve put randomlyCTRL+SHIFT+S
&CTRL+SHIFT+P
)- Once the combinaison is pressed, a pop-up will ask you if you really want to sync your changes, or will automatically sync your local changes with the remote content.
- If there is merge conflict your files will be weirdly messed up (On Iphone there is a check)
- On MacOS; It prints an error.
- You must stash your local changes, pull again and fix the conflict(s)
- You can also add an hotkey to do so. But use it carefully to avoid weird/unwanted changes
- On MacOS; It prints an error.
- Install the community
The scripts
NOTE: didn’t test on windows yet, as soon as I test I’ll update the article.
Save these scripts and set them executable (chmod +x sync.sh
)
Linux and MacOS
#!/bin/bash
msg=$(git status --porcelain)
if [ ${#msg} -ne 0 ]; then
git add --all
git commit -m "${msg}"
git pull origin main
git push origin main
fi
#!/bin/bash
git pull origin main
#!/bin/bash
git stash
git pull origin main
git stash pop
Windows
Don’t forget to update the paths in Obsidian to use Powershell 5 (instead of cmd)
sync.ps1
$msg = git status --porcelain
if(($msg | Measure-Object).Count -ne 0){
git add --all
git commit -m "${msg}"
git pull origin main
git push origin main
}
pull.ps1
git pull origin main
Images




IPhone Setup
Yuo must buy an application in order to sync the git repository and a local folder on your IPhone. You’ll have to do some manual steps in order to sync everything.
The application is Working Copy (https://workingcopyapp.com/)
The link to buy/try is : https://apps.apple.com/us/app/working-copy/id896694807?ign-mpt=uo%3D6
It works great ! like very great, the application does a lot for us and prevent mistakes.
I’ll continue using the free 10 days trial and setup everything, and I might buy the pro version if my testing goes well.
Conclusion
The next step is to integrate automated backup of this solution, I think any solution will be a good fit, mostly because Obsidian generate text files and Gitea has volumes for the important stuff.