Skip to content
Lockpad
Install

Install Lockpad

Lockpad runs on a computer you own: a NAS, a mini PC, an old laptop, a Raspberry Pi. Pick a path below and follow it through. Most people are done in about ten minutes. You don’t need to know how to code for either path here, though both involve a terminal. The point-and-click paths are on the way, and the picker below says where they stand.

Before you start, you need:

  • A computer that stays on. Your notes live there instead of in someone’s cloud, so it has to be awake when you want them. Your everyday laptop works, but your notes are only reachable while it is.
  • Docker, installed and running. The install script checks for it and tells you what’s missing before it changes anything on your machine.
  • A free Tailscale account, if you want your notes away from home and do not already have your own way to reach a server remotely. Skip it if Lockpad will only ever run on your home network, or if you already run a VPS or a reverse proxy. The sections below cover both.

One more thing worth knowing before you start: Lockpad is a single-person app. One password for the whole thing, no user accounts to manage.

Pick how you want to install it

All three paths below end up in the same place: Lockpad running on your own hardware, ready to open. The difference is how much runs on its own versus how much you type yourself. Open one to see its steps.

The install scriptOne command. Generates its own secrets, pulls the images, starts everything.Recommended

Fetches what it needs, invents your database password and session secret so you never have to, asks two questions, and starts the app.

On the machine that will run Lockpad:

curl -fsSL https://raw.githubusercontent.com/Colbysdovi/Lockpad-Public/main/install.sh | bash

It will ask for a login password (leave it blank to skip one, with a warning), and whether Lockpad should be reachable only from this machine or from your whole home network. Either question can be answered by pressing Enter for the recommended default.

When it finishes, it prints the address to open and the handful of commands worth keeping: watching logs, stopping the app, updating later. Read the script first if curl | bash is not something you do lightly: install.sh on GitHub(opens in a new tab).

From sourceClone the repo and build the images yourself. For anyone who’d rather compile it and read the code on the way past.

Builds the images locally instead of pulling them, so nothing here depends on the published ones.

Clone the repo and copy the example config:

git clone https://github.com/Colbysdovi/Lockpad-Public.git
cd Lockpad-Public
cp .env.example .env

Open .env and set POSTGRES_PASSWORD to a long random string, the same string inside DATABASE_URL, APP_PASSWORD to the password you want to log in with, and SESSION_SECRET to the output of openssl rand -hex 32. Every variable in the file is commented with what it does. Then:

docker compose up -d --build

DEPLOY.md(opens in a new tab) is the full version of this path, covering production compose overlays, the Tailscale sidecar and the LAN-TLS option below. It is the source of truth when it and this page disagree.

Install with ClaudePaste one prompt and it runs the script path for you, then checks it worked.

If you already pay for Claude, it can do this for you. Lockpad ships with instructions Claude reads on arrival, so it follows the real, tested steps rather than improvising.

What you need is Claude Code(opens in a new tab), which comes with a paid Claude plan, installed on the machine that will run Lockpad. Like both paths above, this one needs terminal access to that machine. If you can SSH into it, you can do this.

Start Claude Code on that machine and paste this:

Install Lockpad on this machine. Clone https://github.com/Colbysdovi/Lockpad-Public and follow the install-lockpad skill it ships with.

It asks the same two questions the script does, a login password and whether Lockpad should be reachable from your whole home network, then prints the address to open. It sets your database password and session secret without ever showing them, and it will not take your login password in the chat: you type that into the installer's own prompt, on the terminal, where it is never echoed. Ask for Tailscale in the same breath and it will set that up too, once you give it a key you generate yourself.

The instructions it follows are readable before you run anything: the install-lockpad skill on GitHub(opens in a new tab).

Reaching your notes from your phone

Lockpad is running on a machine in your house. Your phone, when you’re out, is not. The usual way to bridge that gap is port forwarding, which tells your home router to let the internet reach that machine, and the opening it makes is open to everyone rather than only to you. It is the part of self-hosting that goes wrong most often. Both paths below get you there without it. Open the one that matches what you already run.

Set up TailscaleA private network only your own devices can join. Free for personal use, and it is what turns the lock button on.Recommended

Tailscale(opens in a new tab) skips the opening entirely. It builds a small private network (a tailnet) that only devices you’ve signed in can join. Your phone then talks to the machine at home directly, as though both were on your home wifi, wherever you actually are. Nothing about Lockpad is published to the public internet; there is no address for anyone else to visit, because there is no public address at all. It’s free for personal use: make an account, install it on the machine running Lockpad and on your phone and laptop, then sign all of them in.

Front the app with it once Lockpad is running:

tailscale serve --bg 127.0.0.1:5173

Your notes now live at an address ending in .ts.net, reachable from any of your signed-in devices and from nowhere else. This step also unlocks the lock button. Browsers only hand out the cryptography per-note locking needs over HTTPS or localhost, and tailscale serve is what gives the app HTTPS on your tailnet. Plain http://<home-ip> has no such thing to offer, so the lock icon has nothing to encrypt with until you’ve done this (or the LAN-TLS alternative in DEPLOY.md §9(opens in a new tab), if you’d rather stay off Tailscale and only need this at home).

The two words that matter: Lockpad uses serve, which publishes to your tailnet only, never funnel, which would publish to the whole internet. If an instruction anywhere ever tells you to run funnel, it’s wrong for this app.

Worth knowing: a Tailscale outage doesn’t cut off a connection that already works. Once two of your devices have been introduced, they talk peer to peer, over your own network when you’re home, and Tailscale steps out of the way. Check it yourself:

tailscale status

The Lockpad line should say direct, not relay. To tighten it further, Lockpad ships an example ACL that restricts access to devices you tag rather than to every device on your tailnet. Worth doing if you share a tailnet with family. See DEPLOY.md(opens in a new tab), or the app’s privacy claims for what this is backing up.

Already have a server exposedA VPS, a Cloudflare Tunnel, or a reverse proxy you already run. Three settings rather than new infrastructure.

If you already run a VPS, a Cloudflare Tunnel, or your own reverse proxy, you do not need Tailscale to try Lockpad. You probably have everything you need running today. Lockpad does not care which reverse proxy sits in front of it: it needs three settings pointed at your own setup, rather than a new piece of infrastructure to adopt.

In .env, bind the frontend to every interface instead of localhost only, set CORS_ORIGINS to the address you will actually use, and turn on COOKIE_SECURE once your proxy is serving HTTPS.

The three settings, in .env:

FRONTEND_BIND=
CORS_ORIGINS=https://notes.yourdomain.com
COOKIE_SECURE=true

Point your reverse proxy’s upstream at the frontend container and let it handle the certificate. There is no new compose file to run: the same docker-compose.public.yml as every other install path.

The fuller deployment reference, covering health checks, backups and updates, is DEPLOY.md(opens in a new tab).

If something goes wrong

The page won’t load. What do I check?

In order, because each one rules out the next:

  • Is the machine running Lockpad on and awake? A NAS that has gone to sleep is the most common cause, and the least interesting.
  • Is Docker actually running it? On that machine, in the folder you installed into: docker compose ps. All three of postgres, backend and frontend should say running. If one doesn’t, docker compose logs -f says why.
  • Using the .ts.net address? Tailscale has to be switched on on the device you’re browsing from too. Both ends need to show as connected.
  • Check from a different device than the one running Lockpad, not from that machine itself. A machine can always reach itself, so testing from there can look healthy while everything else is locked out.

The full version, with the health-check command(opens in a new tab).

I forgot my password. Now what?

Depends which password. The app’s login password can be reset: edit APP_PASSWORD in .env on the machine running Lockpad, then docker compose up -d. Nothing is lost: that password guards the app, it doesn’t encrypt anything.

A passphrase on a locked note is different, and there is no reset. Its contents are encrypted with a key derived from that passphrase alone, and the server never had a copy to fall back on. That’s the same property that keeps a locked note private from everyone else, and it cuts both ways. Put note passphrases in a password manager, the same as the login one.

Why can’t I lock a note?

Almost certainly because the page is loaded over plain http://. Locking a note runs on the browser’s Web Crypto API, which browsers only hand out over a secure context, meaning HTTPS or localhost. Over http://<some-ip> that API simply isn’t there, so the lock button has nothing to encrypt with.

Tailscale’s serve gives the app HTTPS on your tailnet, which is why it’s the recommended path below rather than a LAN address on its own. Locking notes over http is not a Lockpad limitation to work around, it is what keeps that encryption meaningful.

How do I back up my notes?

Nobody else is holding a copy, which is the point and also the part that’s on you. Two ways, for two different things:

  • Settings → Data → Export all notes, from inside the app. One file with every note, folder, tag and note-to-note link, and every embedded image inside the file itself rather than linked back to the server. Locked notes are skipped. The export lists which ones, since their contents can’t be read without their own passphrase.
  • The included script, if you installed from a checkout: ./scripts/backup.sh dumps the whole database to backups/. Restore with ./scripts/restore.sh <file>. Worth putting on a nightly cron rather than remembering it, and worth copying those files somewhere that isn’t the same machine. A backup that lives on the disk it dies with isn’t one.
How do I update?

Export your notes first (Settings → Data), every time rather than only before the risky-looking ones. Then, from the folder Lockpad was installed into:

docker compose pull && docker compose up -d

Database migrations run themselves as the backend starts. There’s no second command to remember, and an instruction telling you to run one separately is out of date. Settings → About shows the version you land on.

Do I lose my notes if I restart or rebuild the containers?

No. Notes live in a Docker volume that survives both docker compose down and a rebuild. The only thing that deletes them is deliberately removing that volume.

Does it run on a Raspberry Pi, or other ARM hardware?

The published images are built for both arm64 and amd64, so there’s no architectural reason it shouldn’t. Worth being straight about the gap: nobody has run it on ARM hardware and confirmed it back. It’s expected to work, not yet known to.

Can I use it on my phone?

Yes, in the phone’s browser, over Tailscale or on your home network. There’s no native app. Lockpad ships a web manifest, so adding it to your home screen opens it without browser chrome, which is close enough that most people stop noticing the difference.

Can other people in my house have their own notes?

Not as separate accounts. Lockpad is single-user by design: one password for the whole app, and anyone who has it sees every unlocked note. Locking individual notes with their own passphrase is the only per-note privacy there is. Better to know that before installing than after.

Does it phone home, ever?

No. No analytics, no telemetry, no error reporting, no externally hosted fonts or scripts, no update check running on its own. “Check for updates” in Settings is a link your own browser follows. The server makes no request of its own, on this point the same as the site you’re reading this on (see the privacy page).