Memos

Overview

Short notes that stay on your server

Memos is a web notebook for Markdown, checklists, tags, search, and attachments. It suits a personal knowledge log, household references, reading notes, and small shared spaces. It replaces the short-note workflow of Google Keep; it is not a full office suite. The browser interface supports English and Russian, light and dark themes, and installable web-app use. Third-party native clients are outside this recipe.

The official neosmemo/memos:0.31.0 image uses SQLite and local attachment storage in one persistent volume. Plan for one CPU core, 256 MB RAM (512 MB recommended), and 1 GB plus attachments; these are planning estimates, not a load benchmark. amd64 was exercised; arm64 is available in the image but untested here.

Privacy and authentication

Image CVEs have not been scanned; the manifest records this as unknown. SMTP, SSO, remote storage, and reverse-proxy integration were not exercised.

The recipe mounts upstream-supported deployment configuration: instance access is PRIVATE and public registration is disabled. The first visitor can still create the administrator. Complete that step through loopback or an SSH tunnel before opening the HTTPS proxy. Administrators add later accounts.

Private notes are not end-to-end encrypted. Instance administrators can read and manage private notes, and a share token can grant access to its holder. Protect the volume, restrict administrator accounts, and encrypt off-server backups. OAuth2 providers, including providers using OpenID scopes, are supported natively; this recipe configures password login only. It does not supply SAML, native two-factor authentication, or proxy-header login.

Operations and limits

Backups stop writers and preserve the complete data volume: SQLite, local attachments, and persistent instance secrets. A personal export omits other users and instance configuration and is not a server backup. The full amd64 smoke test creates an administrator and a private memo, uploads a file, checks anonymous access is refused, removes the volume, and restores usable notes and file bytes.

Memos is MIT licensed. Version 0.31 changes APIs, removes RSS, and expands administrator access; read release notes before upgrading. Keep a pre-upgrade archive and matching version for rollback. This 0.x recipe uses a 30-day recheck interval because API and permission behavior can change between minor releases.

Sources: documentation, v0.31.0 notes, deployment configuration, license. The local SVG mark comes from the official favicon, recolored for the catalog tile.

Step-by-step guide

Requirements and preparation

Use 64-bit Ubuntu 22.04+ or Debian 12+ with Docker Engine and Compose v2.24+. Plan for one CPU core, 256 MB RAM (512 MB recommended), and 1 GB disk plus notes and attachments.

mkdir -p ~/services/memos
cd ~/services/memos
# Copy all recipe files, including config/, proxy/, and the scripts here.
cp .env.example .env
chmod 600 .env
# These two policy files contain no secrets and must be readable by UID 10001.
chmod 755 config
chmod 644 config/memos-instance-setting-*.json

The scripts source .env as trusted shell configuration. Keep it private. config/ contains two deployment-owned settings: GENERAL disables registration and ACCESS makes the instance private. They override database/UI settings and require a container restart after changes. Keep this directory with the recipe.

Start and create the administrator

docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 300
curl --fail http://127.0.0.1:5230/healthz

From another computer, first run ssh -L 5230:127.0.0.1:5230 user@server. Open http://localhost:5230, create the first account, and choose a unique password before exposing the proxy. The first account is administrator; there is no default password. Public registration stays disabled afterward. Add later users in administrator settings. Choose the interface language and theme in account settings.

The official entrypoint fixes volume ownership and drops to UID/GID 10001. The root filesystem is read-only; the data volume and /tmp are writable. SMTP, SSO, AI providers, remote storage, and webhooks are not configured.

VPS

Complete administrator setup through the tunnel first. Set MEMOS_URL=https://notes.example.com, configure an HTTPS proxy, and allow only SSH/HTTP/HTTPS through the host firewall. Keep port 5230 on loopback. Encrypt backups and store a copy off-server.

Trusted local network

Use the SSH tunnel for personal access. Shared LAN access should use an HTTPS proxy. If you change the published address to a private IP, restrict it with a firewall and keep MEMOS_TRUSTED_PROXIES=none unless a trusted header-rewriting proxy is actually in the path. Set the canonical URL to the address users open.

Domain and HTTPS

Use one sample from proxy/: Caddy obtains certificates, Nginx needs certificate paths, and Traefik needs the websecure entry point and letsencrypt resolver. Samples run on the host and forward to 127.0.0.1:5230; containerized proxies need a shared network and internal port 5230.

Set the external MEMOS_URL. Trust only the proxy’s IP/CIDR; private also trusts loopback and private ranges, so use it only with the loopback binding and a proxy that overwrites forwarded headers. Restart with docker compose up -d --wait --wait-timeout 300. The Nginx sample allows 50 MB requests; Memos separately defaults to a 30 MB upload limit.

Backup

./backup.sh

Writers stop while the script archives the complete volume, active .env, Compose file, and config/. The single private archive is backups/memos-<timestamp>.tar. A running app is restarted; an already stopped app stays stopped. Encrypt the archive and copy it off-server: it contains accounts, notes, attachments, and instance/session secrets. Do not copy only a live SQLite file or substitute a personal export.

Restore

Restore replaces the entire app volume. Use only trusted archives and the matching app version. On a fresh host, copy the recipe and compare archived configuration.env and config.tar.gz with the active .env and config/ first. Archived configuration is not activated automatically.

docker compose up -d --wait --wait-timeout 300
./restore.sh ./backups/memos-TIMESTAMP.tar
curl --fail http://127.0.0.1:5230/healthz

The script validates the payload before replacement and creates a safety backup. A replacement failure leaves the app stopped. Sign in, open a private memo, and download an attachment after recovery. The amd64 smoke removes the original volume before restoring and verifies those operations.

Update

Read release notes, create a backup, and copy it off-server. Set MEMOS_VERSION to the reviewed exact tag, then:

docker compose pull
docker compose up -d --wait --wait-timeout 300
docker compose logs --tail=100 memos

Migrations run at startup. The 0.x API can change between minor versions: check client/integration compatibility. Version 0.31 removes RSS and expands administrator access. Never use latest or assume an older client works with a new API.

Rollback

Do not start an older image on a migrated database. Keep a pre-update backup, stop the app, set the old exact version in .env, pull, and recreate without starting:

docker compose stop memos
# Edit MEMOS_VERSION and compare the matching config/ now.
docker compose pull memos
docker compose create memos
./restore.sh ./backups/memos-BEFORE-UPDATE.tar

The safety backup can read the stopped container’s volume without starting the old app on new data. Restore the complete matching archive, then verify login, a memo, and a file.

Stop and remove

docker compose down removes containers and retains the volume. After verifying an encrypted off-server backup, docker compose down --volumes permanently removes accounts, notes, and attachments. Deleting the recipe directory also deletes local backups and configuration.

Sources: deployment, v0.31.0, configuration provisioning.

Report a recipe problem

Tell us how it went on your server

Opens a prefilled GitHub issue. A GitHub account is required; submitting the issue makes it public.

Troubleshooting

Container does not become healthy

Run docker compose ps, docker compose logs --tail=100 memos, and docker compose config --quiet. Check the exact image tag, free disk space, and whether config/ was copied as a directory. Invalid deployment JSON stops startup. The native health endpoint is /healthz and answers Service ready..

Setup or registration looks unavailable

The first account is created at the initial setup page. After that, public registration is deliberately disabled; administrators add users in settings. File-backed GENERAL and ACCESS settings are read-only in the UI. Edit the matching JSON and restart only when you intend to change that policy.

Wrong URLs or rate limits behind a proxy

Check MEMOS_URL, the proxy headers, and MEMOS_TRUSTED_PROXIES. The canonical URL does not make the instance public. Trust only real proxy addresses; never accept arbitrary client-supplied forwarded headers. Keep port 5230 on loopback.

Notes or files are missing after recovery

Use the same version and the complete volume archive. A personal export or an SQLite file without its attachments is not a full backup. Check active config/ and .env; archived configuration is not activated. Re-login and verify the attachment bytes. Administrators can inspect private notes; privacy does not imply encryption.

Permission or SQLite errors

The official entrypoint normally sets the data owner to UID/GID 10001. Check docker compose logs, df -h, and the volume mount with docker inspect. Use local storage and one writer instance; do not put SQLite on an unreliable network filesystem or manually edit the live database. Preserve the original volume while investigating.

Sources: docs, deployment configuration.