
Deploy Joplin Server | (Just Updated) Notes Sync Server With Postgres, Admin Password Generated At First Boot
Joplin Server note sync server with Postgres, REST API and volume
postgres
Just deployed
/var/lib/postgresql
joplin
Just deployed
Deploy and Host Joplin Server on Railway
Built for an LLM agent to deploy and use. The deploy form has nothing to fill in: the admin password is generated, public sign-up is closed, notes and attachments live in a Postgres database on a volume, and a redeploy keeps them. Joplin Server is the open-source sync server for the Joplin note-taking apps (desktop, mobile and terminal), with a REST API, a web admin and optional note sharing.
About Hosting Joplin Server
This template runs two services: joplin, the upstream Joplin Server image (version 3.7.5) pinned by digest, and postgres, a private Postgres 17 database with its volume mounted at /var/lib/postgresql. Joplin Server keeps notes, attachments and users in that database, so the joplin service needs no volume of its own.
No default login. A stock Joplin Server creates its admin as admin@localhost with the password admin, which on a public domain is a login anyone knows. The upstream create migration reads DEFAULT_ADMIN_PASSWORD, so here the generated secret is the admin password from the very first start; the admin password is never valid. SIGNUP_ENABLED is false, so a visitor cannot register an account. DEFAULT_ADMIN_PASSWORD only seeds the admin on first boot: if you change the password in the web admin later, the variable no longer matches it.
What the template fixes for Railway. The server listens on Railway's injected PORT, and APP_BASE_URL is the service's own https address, which Joplin needs because it answers 404 Invalid origin to any request whose host is not that address. For the same reason the template has no HTTP healthcheck: Railway's probe sends the host healthcheck.railway.app, which Joplin refuses, so a healthcheck would fail a server that is serving normally. The start command waits for Postgres before the first migration.
Using it. Open the service domain and sign in as admin@localhost with DEFAULT_ADMIN_PASSWORD (read it from the joplin service variables). In a Joplin app choose Joplin Server (self-hosted) as the sync target, enter the service URL and the same login. You can add your own user in the admin and change the admin e-mail and password there. For an agent, use the REST API as in the contract below.
Agent contract
- Public URL:
APP_BASE_URLon thejoplinservice (the generated https address of the service) - Private URL:
http://joplin.railway.internal:8080 - Credentials: the variable
DEFAULT_ADMIN_PASSWORDon thejoplinservice is the password of the useradmin@localhost(the user name is not a template variable);POSTGRES_PASSWORDis the database password (thepostgresservice is private) - Auth:
POST /api/sessionswith a JSON body holdingemailandpasswordreturns a session id; send it on every other call in the headerX-API-AUTH. A wrong login answers403, and a request with no session or a wrong one answers403, sowrite without key: 403 - Health:
GET /api/pingreturns 200 (a Railway healthcheck cannot be used, see above)
#!/bin/sh
# needs: APP_BASE_URL, DEFAULT_ADMIN_PASSWORD (variables of the joplin service); also curl
# signup: none - SIGNUP_ENABLED is false and the one admin login (admin@localhost) is seeded at first boot from DEFAULT_ADMIN_PASSWORD
R="$APP_BASE_URL"; J="Content-Type: application/json"; ID=00000000000000000000000000000001
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/api/ping")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/api/ping"
SID=$(curl -s -H "$J" -d "{\"email\":\"admin@localhost\",\"password\":\"$DEFAULT_ADMIN_PASSWORD\"}" "$R/api/sessions" | sed -n 's/.*"id":"\([^"]*\)".*/\1/p')
if [ -n "$SID" ]; then echo "login: session issued"; else echo "login: FAILED"; fi
A="X-API-AUTH: $SID"
note() { printf 'railway check\n\nid: %s\nparent_id: \ncreated_time: 2026-01-01T00:00:00.000Z\nupdated_time: 2026-01-01T00:00:00.000Z\nis_conflict: 0\nlatitude: 0.00000000\nlongitude: 0.00000000\naltitude: 0.0000\nauthor: \nsource_url: \nis_todo: 0\ntodo_due: 0\ntodo_completed: 0\nsource: joplin\nsource_application: net.cozic.joplin-desktop\napplication_data: \norder: 0\nuser_created_time: 2026-01-01T00:00:00.000Z\nuser_updated_time: 2026-01-01T00:00:00.000Z\nencryption_cipher_text: \nencryption_applied: 0\nmarkup_language: 1\nis_shared: 0\nshare_id: \nconflict_original_id: \nmaster_key_id: \nuser_data: \ndeleted_time: 0\ntype_: 1' "$ID"; }
# write with the session: store a note item, read it back, delete it
note | curl -s -o /dev/null -w "write note: %{http_code}\n" -X PUT -H "$A" -H "Content-Type: application/octet-stream" --data-binary @- "$R/api/items/root:/$ID.md:/content"
curl -s -H "$A" "$R/api/items/root:/$ID.md:/content" | head -1 | sed 's/^/note read back: /'
curl -s -o /dev/null -w "delete note: %{http_code}\n" -X DELETE -H "$A" "$R/api/items/root:/$ID.md:"
# refusals
curl -s -o /dev/null -w "login wrong secret: %{http_code}\n" -H "$J" -d '{"email":"admin@localhost","password":"wrong"}' "$R/api/sessions"
curl -s -o /dev/null -w "login upstream default admin/admin: %{http_code}\n" -H "$J" -d '{"email":"admin@localhost","password":"admin"}' "$R/api/sessions"
curl -s -o /dev/null -w "read without key: %{http_code}\n" "$R/api/items/root:/:/children"
note | curl -s -o /dev/null -w "write without key: %{http_code}\n" -X PUT -H "Content-Type: application/octet-stream" --data-binary @- "$R/api/items/root:/$ID.md:/content"
note | curl -s -o /dev/null -w "write wrong key: %{http_code}\n" -X PUT -H "X-API-AUTH: wrong" -H "Content-Type: application/octet-stream" --data-binary @- "$R/api/items/root:/$ID.md:/content"
curl -s -o /dev/null -w "public signup: %{http_code}\n" -H "$J" -d '{"email":"visitor@example.com","password":"visitor-pass-1"}' "$R/api/users"
curl -s -o /dev/null -w "public signup form: %{http_code}\n" -d email=visitor@example.com -d password=visitor-pass-1 -d password2=visitor-pass-1 -d full_name=visitor "$R/signup"
A fresh deploy prints health: 200, login: session issued, write note: 200, note read back: railway check and delete note: 200. The refusals print login wrong secret: 403, login upstream default admin/admin: 403, read without key: 403, write without key: 403, write wrong key: 403, public signup: 403 and public signup form: 403: nothing is stored or created without the login.
Why Deploy Joplin Server on Railway?
Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
By deploying Joplin Server on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
- Agent-ready - generated admin password, a contract block and one script that proves login, a note write, read and delete, and the refusal of a read and a write with no session or a wrong one.
- No default login - the upstream
adminpassword never exists, and sign-up is closed. - Data survives redeploys - notes, attachments and users sit in Postgres on a volume.
- Pinned - the upstream image is pinned by digest.
Common Use Cases
- Self-hosted note sync - keep Joplin notes in sync across desktop, phone and terminal without a third-party cloud.
- Private notebook for a team or family - add users and share notebooks from the admin.
- Evernote and OneNote alternative - open-source, end-to-end encrypted notes under your control.
- Notes for AI agents - an agent reads and writes notes over the REST API.
Dependencies for Joplin Server Hosting
- The
joplinservice and a privatepostgresservice with a/var/lib/postgresqlvolume, both created by the template. Nothing else is required.
Deployment Dependencies
Template Content
postgres
postgres:17joplin
joplin/server:3.7.5