Notesnook Sync Server: running the note sync backend yourself, without docs

The whole Notesnook backend is in the repository, which is why the licence is AGPL

The repository contains the full source code of the Notesnook Sync Server, and it is published under AGPLv3. The licence file itself states that the project is part of the Notesnook Sync Server project, with copyright held by Streetwriters Private Limited, and that it is free software under the Affero GNU General Public License, either version 3 of the License or any later version.

AGPL is the important detail for anyone thinking about a deployment. It is a strong copyleft licence, and the network use clause matters here: the project is a server, and the Affero variant exists precisely to cover software that users interact with over a network rather than by copying the binary. If you run a modified version as a service for other people, the licence's terms on source availability reach that situation. This is not legal advice, and the LICENSE file in the repository is the text that governs, but the practical takeaway is that forking this server for a hosted product is a decision that needs a lawyer, while running it for yourself is a much easier question.

The rest of the tree explains what the server actually is. There are separate projects for the API, the Identity server, the Messenger for server sent events, an Inbox API, and shared libraries named Streetwriters.Common and Streetwriters.Data, all tied together in Notesnook.sln.

The intended user is a Notesnook user who wants their notes on their own infrastructure, and it is worth being direct that this is a path the project itself calls alpha, since the description says self-hosting is in alpha.

Docker Compose is the practical route, and the required variables are checked for you

The documented quick path is Docker Compose, and it starts by fetching two files from the master branch of the repository.

wget https://raw.githubusercontent.com/streetwriters/notesnook-sync-server/master/docker-compose.yml
wget https://raw.githubusercontent.com/streetwriters/notesnook-sync-server/master/.env

You then edit .env and set at least NOTESNOOK_API_SECRET, and the .env file is where all configuration options live. After that the stack comes up with a single command.

docker compose up

That brings up MongoDB, MinIO and the Notesnook services together, so the database and the S3-compatible object store are part of the same deployment. The compose file also carries a validate service that runs before the stack and fails fast if something is missing. It checks for INSTANCE_NAME, NOTESNOOK_API_SECRET, DISABLE_SIGNUPS, AUTH_SERVER_PUBLIC_URL, NOTESNOOK_APP_PUBLIC_URL, MONOGRAPH_PUBLIC_URL, ATTACHMENTS_SERVER_PUBLIC_URL and NOTESNOOK_API_PUBLIC_URL, and it prints which variable is missing before exiting.

The stack has three internal services with fixed ports and hostnames. The API listens on 5264 as notesnook-server, the Identity server on 8264 as identity-server, and the SSE server on 7264 as sse-server. SELF_HOSTED is set to 1, and the public URLs are wired through the environment file.

Three optional services sit behind a compose profile, themes-server, cors-proxy and inbox-api, and they are started with the extras profile rather than by default.

docker compose --profile extras up

If you would rather point at storage you already run, the examples directory holds configurations for external MongoDB, external MinIO, and Garage as an S3 alternative.

SMTP is the setting people miss, and the compose file warns about it

The compose file contains a warning block that is worth reading carefully, because it describes a failure that only shows up for new users.

If SMTP_HOST, SMTP_PORT, SMTP_USERNAME and SMTP_PASSWORD are not all set, the validation service prints a warning saying that SMTP is not configured, and that email-based two factor codes and password reset emails will not be sent. It goes on to say that newly created users must switch two factor authentication to an authenticator app, under Settings, Auth, Change 2FA method.

This is a real operational trap rather than a formality. The server starts happily, accounts can be created, and the failure appears later as a user who cannot receive a code. The fix is to configure the SMTP variables in .env before the first registration, or to accept that every new account has to set up an authenticator app by hand.

The same pattern of a documented default applies elsewhere. DISABLE_SIGNUPS appears in the list of required variables, which suggests signup control is treated as a required decision rather than an optional extra for a self hosted instance.

If you deploy this, the first thing to verify after the stack is up is that a test account can complete a signup and a login, and that the second factor behaves the way you intended.

Building from source means three .NET projects and one solution file

The source route needs .NET 8 and git, and the steps are the standard ones for a .NET solution.

git clone https://github.com/streetwriters/notesnook-sync-server.git

# change directory
cd notesnook-sync-server

The restore step is the slow one, and the documentation warns that it might take a while to complete.

# this might take a while to complete
dotnet restore Notesnook.sln

Then all the projects are built.

dotnet build Notesnook.sln

Each service runs on its own. The API is the main entry point for the clients.

dotnet run --project Notesnook.API/Notesnook.API.csproj

The Messenger and Identity server have their own project files and are started the same way.

dotnet run --project Streetwriters.Messenger/Streetwriters.Messenger.csproj
dotnet run --project Streetwriters.Identity/Streetwriters.Identity.csproj

Note that all three are separate processes, so a source deployment means running three services, plus MongoDB and MinIO which the compose file supplies but a source build does not. That is the main reason the Docker route is the documented fast path.

Pointing the client apps at your own server requires v3.0.18 or later

A backend is useless without clients that talk to it, and the project tracks the client requirement explicitly. One of the completed items on the self hosting checklist is adding settings to change server URLs in the Notesnook client apps, starting from v3.0.18. That is the version floor for anyone who wants to connect a phone or desktop client to an instance they run.

The self hosting checklist in the project page is worth reading as a status report. The open source of the Sync server, of the Identity server and of the SSE messaging infrastructure are all marked done, as is fully Dockerizing all services, using self-hosted MinIO for S3 storage, and publishing on DockerHub. The one remaining item is writing the self hosting docs, and the accompanying note is blunt: self hosting the Notesnook Sync Server is now possible, but without support, documentation will be provided at a later date, and the work is ongoing to enable full on-premise self hosting.

So the honest summary of the project state is that the code is public and the deployment is documented well enough for someone comfortable reading a compose file, while the tutorial, the support commitment and the production hardening story are not there yet. The homepage for the project is notesnook.com, and the same services run there, so the client apps work against both.

The gap is documentation, not capability, and that distinction matters if you are deciding whether to wait.

AGPL, a beta tag from October 2025, and commits that continue past it

The licence discussion above has a practical counterpart in how the project ships. The recent releases are v1.0-beta.2, v1.0-beta.3 and v1.0-beta.4, dated 2025-08-18, 2025-08-18 and 2025-10-07. Two beta tags on the same day in August, then a final one in October, and nothing tagged since.

The repository is not archived and the last push was on 2026-10-17, so work continues on the tree well past the newest tag. That gap between the latest release and the head of the branch is the thing to plan around. Running master gets you the current state of the code but no tagged artifact to point at, and running v1.0-beta.4 gives you a fixed reference that predates a year of commits.

For a self hosted deployment this is a normal operating decision rather than a crisis, but it should be a deliberate one. If you pin the tag, you pin the compose file you download too, since the wget commands in the documentation fetch from master and would otherwise drift with the branch.

The repository layout is conventional and easy to navigate: the service projects at the top level, docker-compose.yml and .env in the root, the cors-proxy service in its own directory, an examples directory for external storage setups, and standard files such as AUTHORS, CODE_OF_CONDUCT.md, LICENSE and a .vscode directory. Nothing here suggests a project in decline; the gap is the documentation task that is still unchecked on the list.

Editorial conclusion

Adopt the Notesnook Sync Server if you want to run the Notesnook backend on your own hardware, with MongoDB and MinIO under your control, and you are prepared to read the compose file for the configuration the documentation does not yet cover. Do not adopt it for production use that needs a support contract, because the project states that self hosting is possible but without support and that the self hosting documentation is still an open task. Before deploying, set NOTESNOOK_API_SECRET and the other required environment variables, configure SMTP so two factor codes and password reset emails work, and pin the version you run, since the newest tag is v1.0-beta.4 from 2025-10-07.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. streetwriters/notesnook-sync-server on GitHub