A step-by-step guide to backing up your Roam Research database

A guide for the technical-but-not-github-literate among us.

Recently I decided to start backing up my Roam Research database, since I realised that the amount of valuable writing in there warranted some form of backup plan, even though I have great confidence in the technical abilities of its founders.

After some research I selected the solution created by MatthieuBizien (roam-to-git), which provides both local as well as cloud based options. As a bonus this will provide you with a clickable directory of all your Roam notes on your mobile. I went for the cloud based option. Since getting it up and running does require some basic knowledge of GitHub, I decided to share the install procedure I followed to make this work for me.

Step 1: Create a GitHub account

If you do not already have a GitHub account, create it at www.github.com

Step 2: Create a new repository for your Roam Research backup

This will create a new repository to host the backup-data. We will create a private repository, so it cannot be accessed by the rest of the world.

Step 3: Configure GitHub secrets

This will configure the secret variables involved in accessing your Roam Research database, such as you username, password and the RR graph name you want to backup.

ROAMRESEARCH_USER="YOUR_EMAIL"
ROAMRESEARCH_PASSWORD="YOUR_PASSWORD"
ROAMRESEARCH_DATABASE="YOUR_DATABASE"
NOTE: You can ignore the instructions that are in the .env file, since they are aimed at a different setup method.
Entering new Secrets in GitHub

If all went well, you will have three ‘Secrets’ showing:

Secrets needed for roam-to-git

Step 4: Create a GitHub Action

Now that we have the variables configured to access your Roam graph, it is time for the final step: making the function that runs the backup.

Location of the ‘New workflow’ feature in GitHub
NB: as of October 21st 2020, this code is broken because of a change at Roam. Github user mbakht has created a temporary fix:locate the following line in the code:
pip install git+https://github.com/MatthieuBizien/roam-to-git.git
and replace it with:
pip install git+https://github.com/mbakht/roam-to-git.git@patch-1

If all went well, the action will now run every hour to create a snapshot of your Roam graph. If you want to tinker with the interval, read up on the ‘cron’ function and change the ‘cron: “0 * * * *”’ part in the code.

Step 5: Verify and access the Roam backup

If you access the ‘Actions’ menu in your GitHub repository, you will start seeing successful execution of the ‘Roam Research backup’ workflow:

If a backup fails for whatever reason, you will get an e-mail informing you. Most of the time this will have to do with a time-out on the Roam website, which is nothing to worry about. As long as regular backups are successful, you’re good.

If you go to the main page for your repository, you will find a successful run has created 3 directories with the contents of your backup.

These directories are clickable and contain all your Roam content as supported by the backup mechanism.

Step 6: Enjoy peace of mind

That’s it. I hope this guide has enabled you to successfully create an automatic cloud-based backup mechanism for your Roam graph. If you have run into trouble because steps were not clear enough, let me know, I’ll see how I can improve it!

Consultant, teacher & coach at the crossroads of innovation, psychology and systems thinking. https://www.lockefeer.com

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store