Monograph

How to selfhost Notesnook

2024-08-07 08:28

Minimum system requirements:

  1. Linux

  2. Single core CPU (x86 or ARM)

  3. 1 GB RAM (512MB will also do but 1 GB is recommended for a seamless experience)

  4. 20 GB free disk space

These self hosting instructions are targeted towards single-user use-case i.e. it is expected that only 1 user (with multiple devices) will use the self hosted instance. While multiple users can signup and use the server, it is considered out-of-scope for this guide. Business/enterprise is NOT the target audience of this guide (although they can still use it without any restrictions and/or guarantees).

Prior knowledge:

  1. Linux command line

  2. Docker

  3. Docker Compose

By the end of this guide, you should have a working self-hosted of Notesnook with the official web, desktop, & mobile clients connected to it.

Disclaimer: How you secure or setup your server is up to you, and this guide will NOT provide any recommendations outside what is directly relevant to Notesnook.

Getting started

The purpose of this guide is to provide streamlined self hosting instructions that even a beginner can understand and implement.

Step 1: Installation

It is assumed that you have a working Linux server that you can SSH into. Root access is NOT a requirement if you can install Docker & Docker Compose without it.

Run the following commands in a Linux terminal:

# 1. Make a directory
mkdir notesnook-server
cd notesnook-server

# 2. Download the docker-compose.yml file
wget https://raw.githubusercontent.com/streetwriters/notesnook-sync-server/master/docker-compose.yml

# 3. Download the .env file
wget https://raw.githubusercontent.com/streetwriters/notesnook-sync-server/master/.env

You should end up with a file structure that looks like this:

  • notesnook-server

    • docker-compose.yml

    • .env

Open the .env file in nano or any other text editor (e.g. VS Code or Notepad++). The .env file is how you configure various parameters of the Notesnook servers. You'll find documentation for each separate environment variable inside the file. The required variables are marked with Required: yes and they must be filled out for the Notesnook servers to function properly.

Once you are done configuring the server, you can start it up as follows:

docker compose up -d
# You can exclude the -d argument to run the container in foreground for debugging purposes.

If everything goes well, you should have 3 services up and running. To quickly check the health of the services, run:

curl http://localhost:5264/health
curl http://localhost:7264/health
curl http://localhost:8264/health

If you want to access your notes and other data outside the computer/device running this server, you have to expose all these services to the Internet (or the internal network) via a reverse proxy (e.g. Nginx) or something like Cloudflare Tunnel (in case if you don't have a static IP). You can easily find documentation and tutorials on how to set up either of those.

You have to expose the following ports:

  • 5264 - Notesnook Sync Server

  • 7264 - SSE server

  • 8264 - Authentication server

  • 9000 - Attachments server

Step 2: Connecting the clients

In order to connect the Notesnook clients, your self hosted instance must be exposed on either the local network or over the Internet (e.g. if you are hosting on a VPS).

HTTP or HTTPS?

You don't actually need HTTPS, but Android/iOS do not allow HTTP traffic, so you won't be able to use your self-hosted instance on these platforms without HTTPS. Using a self-signed HTTPS certificate is also not recommended nor supported as it is really flaky across platforms. For most stable results, purchase your own domain (any TLD will do) and use Let's Encrypt or Cloudflare for HTTPS. Another option is to just use a subdomain provided by various hosting providers.

  1. To connect the web/desktop clients, go to Settings > Servers.

  2. In each field, enter the URL for the relevant server. Make sure there are no trailing slashes e.g. https://api.notesnook.com is correct but https://api.notesnook.com/ is not.

  3. Once all the fields are filled out, click on the Test connection button. If everything goes well, you should see something like Connected to all servers successfully.

  4. Click on the Save button and wait for the app to reload.

Step 3: Create an account

After connecting the clients, you will have to create a new account. All accounts created on a self-hosted instance automatically receive a Pro subscription.

You must use a valid email address because you'll receive 2FA codes on the same email on every login.

Step 4 (optional): Migrating your data from the managed instance

You can easily migrate your existing notes & attachments from the official Notesnook instance to your own self-hosted instance:

  1. Login to your account on the official Notesnook instance

  2. Go to Settings > Backup and export

  3. Click on Backup with attachments and wait for the backup to download.

  4. You should now have a .nnbackupz file containing all your data.

  5. Logout and switch to the self-hosted instance (or just login on a different browser).

  6. Login to your account on the self-hosted instance.

  7. Go to Settings > Backup and export

  8. Click on Restore and select the .nnbackupz file.

  9. Wait for the restoration to complete

  10. Done!

Troubleshooting

I am getting The URL you have given (<url>) does not point to the X server error

This usually means you are putting a URL that points to a different server (e.g. you entered URL for the Identity server in the field for the Sync server). Double check your ports & domains, and input the correct URL for the relevant server.