Install your own Noodle server

The Noodle server keeps your devices in step: the Mac app, your phone and any browser all see the same pages, updated as you type. The same address also serves Noodle in the browser, the server backs itself up, and if you like it can connect AI assistants such as Claude. It runs in Docker on a machine you own, so your data stays there and never passes through an outside service.

You need an always-on machine with Docker and Docker Compose: a mini PC, a NAS that supports Docker, a virtual machine at home or a rented server (VPS). 1 GB of RAM and a few GB of disk are enough, plus room for attachments and backups.

The Noodle app's interface is in Italian for now, so this guide quotes its labels in Italian with an English translation alongside.

01Before you start

What you need

• An always-on machine with Docker and Docker Compose v2 (the command is docker compose, with a space). If Docker isn't installed, follow the official instructions for your system.
• The server package: the noodle-server-<version>.zip file on the Download page. It contains a noodle-server/ folder with server/, apps/web/, shared/, deploy/ and an ISTRUZIONI.md file, written for an AI assistant but readable by anyone (it is in Italian; an assistant will handle it fine). The Mac app can save the same package: on first launch, choose "Il mio server" (My server), then "Devo installarlo" (I need to install it), then "Salva il pacchetto..." (Save the package).
• Optional but recommended: an HTTPS address, through a domain or through Tailscale. Noodle works without it on your local network, but in the browser passkeys (fingerprint and face unlock) and push notifications need HTTPS.

Five questions to ask yourself

1. Where will the server run? A computer at home, a NAS or a VPS. Is Docker already installed?
2. Where will you use it from? Only at home, away from home through Tailscale or a VPN, or from the internet with a domain.
3. Do you already have an HTTPS proxy (Nginx Proxy Manager, Caddy, Traefik) or a domain?
4. Do you want to connect AI assistants such as Claude or Codex? You can decide later.
5. Where will backups be copied off the machine: a NAS, an external drive, a cloud service?

The answers only affect sections 6, 7 and 8. The basic installation is the same for everyone.

02Two ways to install it

You can have an AI assistant working in your terminal guide you through it, or follow this page by hand. The result is the same.

I want to install the Noodle server. This folder (noodle-server) is the package downloaded from the website.
The server should run on: [for example "this computer", "the mini PC at home, reachable with ssh user@192.168.1.10", "my NAS"].

Read ISTRUZIONI.md in full (it is in Italian; talk to me in English) and follow it phase by phase, from start to finish:
- first ask me the opening questions, one at a time, and explain in plain words what you are about to do;
- if the ready-made image can't be pulled, go straight to path B (from source: docker compose up -d --build in the deploy folder);
- before changing anything that already exists on the machine (firewall, proxy, other containers), show me what you will do and wait for my go-ahead;
- after each phase run the check it describes and only move on if it passes; if it fails, look for the cause in the logs before trying again;
- generate the tokens directly inside the .env file, without showing them in the chat or copying them into other files; just tell me how to read them so I can save them in my password manager.

For Docker, Dockge and Nginx Proxy Manager details use deploy/README.md; use deploy/MCP.md only if I decide to connect assistants.
When you finish, give me a summary: the address to open Noodle, where the data and backups live, how to update, and the final security checks, verified one by one.

03Installation

For now the way in is the downloadable package, from which Docker builds the image on your machine. Further down is the ready-made image route, for when the image is published to a registry.

From the downloadable package

Copy the zip to the server machine. From your computer, for example:

$ scp ~/Downloads/noodle-server-*.zip user@192.168.1.10:~

Then, on the server machine, unzip the package into /opt and prepare the configuration:

$ sudo unzip ~/noodle-server-*.zip -d /opt
$ sudo chown -R "$USER": /opt/noodle-server
$ cd /opt/noodle-server/deploy
$ cp .env.example .env && chmod 600 .env
$ openssl rand -base64 32
# paste the output into NOODLE_TOKEN, then fill in the rest (see the table below)
$ nano .env

If unzip is missing, install it (sudo apt install unzip on Debian and Ubuntu).

The .env variables

.env.example describes all of them (the comments are in Italian). These are enough to get started:

Everything else has sensible defaults: attachments up to 200 MB, a backup every 6 hours keeping the last 30, plus one a day for 30 days. The SMTP_* variables are only needed if you want the server to send email (invitations, forgotten passwords); without them, invitation links are copied by hand.

Starting it

$ mkdir -p data && sudo chown 1000:1000 data
$ docker compose up -d --build
# the first time it builds the image: a few minutes
$ docker compose logs -f
# Ctrl+C to leave the logs (the server keeps running)

The first time a new version starts, the server may take a few minutes to prepare the data. That's normal, and Docker only reports it as healthy afterwards.

$ curl http://127.0.0.1:4455/api/health

With Dockge

If you manage containers with Dockge: create a stack called noodle, paste the contents of deploy/docker-compose.yml, and in the .env section paste .env.example, filled in as above. NOODLE_SRC must be the absolute path of the package folder (for example /opt/noodle-server), because the Dockge stack lives in a different folder. Prepare the stack's data folder, then press Deploy:

$ sudo mkdir -p /opt/stacks/noodle/data
$ sudo chown 1000:1000 /opt/stacks/noodle/data

With the ready-made image

Once the image is published to a registry, or if someone has already given you the image, there's nothing to build: all you need is the package's deploy/immagine/ subfolder. Copy it to the machine, for example to /opt/noodle, and run the script:

$ cd /opt/noodle
$ sh installa.sh

The script creates the .env with a random admin token and gateway token, prints the admin token once (save it in your password manager straight away), pulls the image, starts the server and waits for it to respond. Running it again is safe: it leaves an existing .env and your data alone. If the image can't be pulled but is already on the machine, it uses that; otherwise it stops and points you to the package route.

On this route the data lives in the noodle-data Docker volume. If you'd rather have an ordinary folder, which is easier to copy, set NOODLE_DATA in the .env before the first start (the folder must be writable by uid 1000). Then check PUBLIC_URL and TZ, and after any change to the .env run docker compose up -d.

04First account

1. In a browser, open http://192.168.1.10:4455/ with your machine's address. You'll see the "Crea il tuo account" (Create your account) screen.
2. Enter the admin token (the one in NOODLE_TOKEN), a username and a password of at least 10 characters; a long phrase works well. This first account is the administrator.
3. Straight away, go to Impostazioni > "Sicurezza" (Settings > Security) and turn on a second factor: Face ID or Touch ID in the apps, a passkey in the browser over HTTPS, or an authenticator app with 6-digit codes. Without a second factor you can't connect assistants or protect notes.
4. Save the 10 recovery codes in your password manager. Each one works once and lets you in without your phone.
5. You create the other accounts yourself in Impostazioni > "Amministrazione" (Administration), either with an invitation or with a temporary password that each person changes when they first sign in.

You don't need the admin token day to day: after the first account you sign in with a username and password. Keep it anyway, because the /admin/ panel asks for it.

05Connecting the apps

Browser

Open the server's address and sign in. Noodle in the browser is served by the server itself, so it's already set up. Your pages are also kept in the browser and catch up when the connection comes back.

iPhone and Android

In Safari, open the server's address, then tap Share > Add to Home Screen: Noodle then opens like an app. On Android, Chrome only offers "Install app" when the address uses HTTPS. When the iPhone app becomes available, iOS will ask for permission to access the local network the first time: allow it, otherwise the app can't see a server at home.

Mac app

On first launch choose "Il mio server" (My server) and enter the address; if you're already using the app, go to Impostazioni > "Dati" > "Collega un server" (Settings > Data > Connect a server). The address takes the websocket prefix:

• ws://192.168.1.10:4455 on your local network, without HTTPS;
• wss://noodle.yourdomain.com with HTTPS.

Then press "Accedi" (Sign in) and enter your username and password. Under Impostazioni > "Avanzate" (Advanced), "Verifica connessione" (Check connection) tells you whether the server is responding. Pages you created on the Mac before having a server are uploaded automatically the first time you sign in.

06Reaching it away from home

Pick based on the second question in section 1. If in doubt, Tailscale is the safest option for the least work.

$ sudo tailscale serve --bg 4455

client_max_body_size 210m;
proxy_request_buffering off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

noodle.yourdomain.com {
    reverse_proxy 127.0.0.1:4455
}

07Assistants over MCP

This part is optional. The MCP gateway is a separate container that brings your pages and your Brain into Claude.ai, Claude Code, Codex and any other assistant that speaks MCP. Each assistant only sees what you grant it, vault by vault, read-only or with write access.

How it's protected

• The gateway doesn't mount the server's data and never receives the admin token. It only talks to the server through an internal entry point, using a service token with limited permissions.
• It runs in a hardened container: read-only file system, no privileges, capped memory and processes, no access to the outside network.
• No password ever passes through the gateway: every connection is approved in the Noodle app, with two-step verification.
• An assistant can't change databases, can't delete anything permanently (it moves pages to the bin) and can't create more than 200 pages a day. Revoking access takes effect within half a minute.

Turning it on

In the .env, set:

COMPOSE_PROFILES=mcp
MCP_SERVICE_TOKEN=
MCP_PUBLIC_URL=https://mcp.yourdomain.com

MCP_SERVICE_TOKEN takes a random string, which you can get with openssl rand -hex 32 (on the ready-made image route the script has already generated it). MCP_PUBLIC_URL is the gateway's public HTTPS address, with no trailing slash and no /mcp; you'll choose it in the next step. Then restart the stack:

$ docker compose up -d --build
# with the ready-made image, this is enough: docker compose up -d
$ curl -s http://127.0.0.1:4456/.well-known/oauth-authorization-server

The last command should reply with JSON. The gateway only listens on 127.0.0.1:4456, so your local network can't see it.

Making it reachable

Cloud assistants have to reach the gateway from the internet over HTTPS on port 443 (other ports, such as 8443, may not work). You need something on the host that forwards to 127.0.0.1:4456:

• Tailscale Funnel: sudo tailscale funnel --bg 4456 publishes the gateway at https://<machine>.<tailnet>.ts.net. After switching it on, the certificate can take a minute, so wait before testing.
• Caddy on the host, with a dedicated subdomain:

  mcp.yourdomain.com {
      reverse_proxy 127.0.0.1:4456
  }

  Copy

Put the resulting address in MCP_PUBLIC_URL and run docker compose up -d again. Then, from outside your home network, open the gateway's address followed by this path in a browser:

https://mcp.yourdomain.com/.well-known/oauth-authorization-server

Connecting assistants

• Claude.ai: Settings > Connectors > Add custom connector, with the address Noodle shows under Impostazioni > "Assistenti AI" (Settings > AI assistants; it's MCP_PUBLIC_URL followed by /mcp). A page opens with a pairing code, for example K7QM-4F2T. In Noodle, under Impostazioni > "Assistenti AI", a request appears with the same code: choose what it may see and press "Approva" (Approve). Only approve if you've just started the connection yourself and the codes match.
• Claude Code: Impostazioni > "Assistenti AI" > "Crea chiave" (Create key) gives you a key, shown only once, and the command to paste into a terminal:

  $ claude mcp add --transport http noodle https://mcp.yourdomain.com/mcp --header "Authorization: Bearer <key>"

  Copy
  Claude Code can also connect without a key, through the same code-based approval as Claude.ai.
• Codex and other MCP clients: same address and same key; the details are on the Integrations page.

Never paste the key into notes, chats or repositories: whoever holds it can read and change whatever it has been granted.

08Backup and restore

Automatic backups

The server takes a backup every 6 hours (BACKUP_INTERVAL_HOURS) and keeps the last 30, plus one a day for 30 days. Each .tar.gz archive holds the database, the attachments and a readable export of your pages. You'll find them:

• in deploy/data/backups/ on the package route;
• in the noodle-data Docker volume, or in the backups/ folder under NOODLE_DATA, on the ready-made image route.

A copy off the machine

A backup on the same disk as the server won't save you from a disk failure. The backup folder is an ordinary path on the host, so copy it elsewhere with a scheduled job. For example, with crontab -e, every night at 3 a.m. to a mounted NAS:

0 3 * * * rsync -a /opt/noodle-server/deploy/data/backups/ /mnt/nas/noodle-backup/

rclone to a cloud service works just as well as rsync. Alternatively the server can run a command after every backup through BACKUP_HOOK; there are examples in .env.example.

The admin panel

At the server's /admin/ address (for example https://noodle.yourdomain.com/admin/) you'll find the server status, disk usage, recent sign-ins and the backups, with buttons to create one now, download them and restore them. It asks for the admin token and keeps it only in the open tab.

Restoring

In the panel, press "Ripristina" (Restore) next to the backup you want. Before restoring, the server automatically creates a pre-restore backup so you can go back. To restore an archive that isn't in the list, for instance on a new machine, copy it into the backup folder under its original name (noodle-YYYYMMDD-HHMMSS-reason.tar.gz) and reload the panel.

09Updating

Before updating it's worth pressing "Crea backup ora" in the /admin/ panel. Updating doesn't touch your data, and when the container stops the server saves every open document.

From the package

Download the new noodle-server-<version>.zip, copy it to the machine, unzip it into a temporary folder and copy the files over the old installation. The package contains neither .env nor data, so your configuration and data stay where they are.

$ rm -rf /tmp/noodle-new && unzip ~/noodle-server-*.zip -d /tmp/noodle-new
$ cp -R /tmp/noodle-new/noodle-server/. /opt/noodle-server/
$ cd /opt/noodle-server/deploy
$ docker compose up -d --build

With Dockge, once the files are copied, press Update on the stack to rebuild the image.

With the ready-made image

$ cd /opt/noodle
$ docker compose pull && docker compose up -d

If you pinned a version with NOODLE_VERSION in the .env, change the number first.

The first time a new version starts, the server may take a few minutes to prepare the data. The check is the same as at install time: curl http://127.0.0.1:4455/api/health should show the new version.

10Final security checks

Tick each item once you've verified it. The boxes are remembered in this browser.

11Troubleshooting

The first place to look is always the log, from the compose folder:

$ docker compose ps
$ docker compose logs --tail=100