Introduction
A few weeks ago I stumbled upon Roam Research. At first glance it's just another note-taking tool like Notion and Evernote.
But after a few minutes I realized how powerful this type of note-taking could be.
This is how Roam Research describes their own product:
A note-taking tool for networked thought.
As easy to use as a document. As powerful as a graph database. Roam helps
you organize your research for the long haul.
Basically, what Roam Research does differently is the ability to have bi-directional
links between notes and see the relation between these notes in a graph. Why this is such a
powerful feature and to get a pretty good understanding of the power
of such a tool, I suggest you watch this YouTube video by Nat Eliason:
There's a problem with Roam and the other apps I've mentioned though:
No privacy because these services can see the contents of all my notes.
I've been using Notion for the past 2+ years now and it's such a good product that I tried to ignore this problem. But due to the fact that Notion struggles with (performance) issues lately and the discovery of Roam, I decided that it's time to find a way for me to get back full
control of my data without storing my most private data on servers I have no control over.
The Alternatives
There are a couple of other note taking apps that try to replicate the functionality of Roam Research.
•
•
Yes, Notion itself can be a (although basic) alternative to Roam as they've implemented the backlinking functionality into Notion in September 2020
•
Doesn't solve our problem though
•
•
Privacy friendly as the data is only stored locally
•
App is closed source though which I don't like
•
No official way to take notes on mobile yet
•
•
Open source, can be selfhosted (though in very early stage)
•
I don't want to use Java-ish stuff
•
•
Open source, can be selfhosted (in early stage)
•
more focused on you storing all your notes on Github, which gets us back to my initial
problem
•
Again, Java world
•
•
Open Source, selfhosted
•
Notes are just Markdown files
•
You can use Git to version control your notes and have a history of the changes you make
to the notes
•
built on Visual Studio Code (the majority of us are probably using it anyway)
•
this fact alone probably makes you realize how much potential this has
•
full control of the data
•
Early development stage, but already very functional and promising
•
•
Check out the Update section at the bottom of this post
You probably already guessed it. In this post we're going to look at Foam as well as how to install
and configure it so that it becomes platform independent and can be used on every relevant platform: Windows, Mac, Linux, iOS and Android. Because as you know, VSCode is not available on mobile.
Installation and Configuration
You probably know VSCode as the Desktop application that is used by so many developers around the world. VSCode is open source and is built with JavaScript (TypeScript to be more precise).
So there are ways to make it run on the Web (read: in the browser). One such way is the
project code-server.
It's literally VSCode that you know from Desktop running in the browser (pretty cool, right?).
Now you should already have a pretty good understanding about how we're going to accomplish
the cross platform functionality.
We're going to use Docker (and docker-compose) to install code-server.
If you're not familiar with Docker yet, there are already countless posts about that topic on the internet. It's out of scope for this post.
I have code-server (and Foam) installed on my server, but it will also without a problem
run on something like a Raspberry Pi that you have lying around at home.
I'm going to assume you have Docker and docker-compose already installed.
So let's finally start with the steps required to get Foam installed and configured.
1.
Create a new folder for this project on your server (I'm going to call it **code-server**)
2.
In that folder create the following folder structure:
1.
mkdir -p config/.config
2.
mkdir {notes,code}
3.
Create the docker-compose.yml file in the just created code-server
folder with the following content:
version: "2.1"
services:
code-server:
image: ghcr.io/linuxserver/code-server
restart: unless-stopped
container_name: code-server
ports:
- 8443:8443
volumes:
- ./config:/config
- ./notes:/notes # where our notes will be stored
- ./code:/code # optional, if you want to also use this VSCode instance as your dev environment
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/Berlin
- PASSWORD=MyPassword # optional, password protect your web based VSCode instance
- SUDO_PASSWORD=MyRootPassword # optional, for root access on the terminal of the Docker container
# open-vsx.org extension marketplace
# the default extension marketplace in code-server is not that great (very outdated extensions and slow)
# this one is much better, but has also some outdated stuff
- SERVICE_URL=https://open-vsx.org/vscode/gallery
- ITEM_URL=https://open-vsx.org/vscode/item
# Microsoft extension marketplace
# gray area, Microsoft officially only allows its own products to use this marketplace
#- SERVICE_URL=https://marketplace.visualstudio.com/_apis/public/gallery
#- ITEM_URL=https://marketplace.visualstudio.com/items
# optional, if you also want to use this browser based VSCode instance as your dev environment (I can highly recommend you test it out).
# For other available mods check out the image's Docker Hub page
# https://hub.docker.com/r/linuxserver/code-server
- DOCKER_MODS=linuxserver/mods:code-server-golang|linuxserver/mods:code-server-nodejs|linuxserver/mods:code-server-php8|linuxserver/mods:code-server-python3
YAML
docker-compose.yml file for our web based VSCode
4. (Optional) You can also run it behind a reverse proxy like Traefik or nginx, but this it out of scope for this post. Check out Nginx Proxy Manager for a very easy to manage way
to use nginx as your reverse proxy.
5. Pull the Docker image and start the code-server container (you must be in the
code-server directory you created in the first step)
docker-compose up -d
(you can stop the container with docker-compose down)
You should now have a running version of VSCode in the browser on http://localhost:8443
(give it some time, especially if you're using the `DOCKER_MODS`). You can check the logs of this
container by running docker logs -f code-server to see once it's ready.
If you used the env var PASSWORD then you should log in with this password (there are also ways
to store your password as a hash in the compose file).
The difficult part is already done, now we only need to get Foam up and running in our browser
based VSCode and configure some settings.
For this you can check out the Foam Getting Started guide.
But basically, you need to either git clone or just download the zip file and unzip it in the
folder you want to use for your notes (the ./notes subfolder in this example).
After opening this folder within your code-server instance (that's why we've created the notes subfolder and added it as a volume to our container), VSCode should display a message about
recommended extensions to install for Foam. Install (or review before installing) them.
Other extensions I'd recommend:
•
•
better Git integration
•
•
Allows you to automatically and periodically commit (and push) the changes to your notes
to a Git repository of your choice
•
•
Automatically format your notes, e.g. wrap long lines on Save etc.
•
•
A web clipper like Notion has that turns websites into Markdown and stores them in notes.
•
•
If you're a vim enthusiast like me and need your vim keybindings pretty much everywhere
Here are the global VSCode settings that I've set for myself, feel free to use them to get a good starting point.
{
"workbench.startupEditor": "newUntitledFile",
"terminal.integrated.shell.linux": "/bin/bash",
"files.autoSave": "off",
"window.autoDetectColorScheme": true,
"editor.tabSize": 2,
"editor.matchBrackets": "always",
"editor.minimap.enabled": true,
"breadcrumbs.enabled": true,
"editor.renderControlCharacters": true,
"workbench.sideBar.location": "left",
"workbench.colorTheme": "Default Dark+",
"gitdoc.autoCommitDelay": 300000,
"workbench.editor.enablePreview": false,
"workbench.editor.enablePreviewFromQuickOpen": false,
"foam.openDailyNote.directory": "journal",
"prettier.enable": true,
"prettier.printWidth": 100,
"prettier.proseWrap": "always",
"editor.formatOnSave": true,
"[markdown]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"vscodeMarkdownNotes.newNoteDirectory": "WORKSPACE_ROOT"
}
JSON
VSCode settings.json
If you're done with all these steps, you can start getting to know and using Foam by opening the
getting-started.md file in the notes folder.
•
Tip: After you got a good understanding of Foam and deleted the test files (like readme.md, getting-started.md etc.), you can git init that folder.
With the GitDoc extension every change will be periodically commited (and optionally pushed). That way you have unlimited revisions of your private knowledge base.
Conclusion
Now you're all set with a fully working, cross platform VSCode and your own privacy respecting and open source Roam Research alternative.
Coding on an Android tablet / iPad (with vim)? Coding on every computer without having to re-configure your environment? Of course you can now also take your notes on every platform.
The possibilities are endless.
Thank you very much for reading. I hope you're going to have as much fun with your cross platform dev environment and powerful as well as privacy friendly note taking app as me.
I'm a Berlin based Software Engineer, mainly working with C++, Go and JS in the medical industry. If you want to follow or chat with me, you can find me on Twitter @5hay.
Update
A few days after writing this blog post, I discovered a new player: Dendron. It's similar to Foam because it also uses VSCode as the foundation. And it seems to be further into development than Foam. Most of the steps of this post should also work for Dendron, I haven't done the move yet though.