This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
What Memos does and what it needs
Memos is a self-hosted note-taking app built around a personal timeline. Each memo is timestamped, Markdown-capable, and taggable, so short thoughts and longer entries live in one searchable stream. You control visibility per memo: private, shared with specific users, or public on the web. The app ships as a single Go binary with an embedded SQLite store by default, which makes it one of the lighter services to run on a VPS.
The upstream project does not publish a minimum RAM figure. Practical sizing depends on workload: an idle instance with a handful of users and a few thousand memos runs comfortably in a small container, while heavy attachment uploads, large media libraries, and many concurrent users push memory and disk usage up. Watch the volume size more than the RAM line.
Everything Memos keeps lives under /var/opt/memos inside the container. That directory holds the SQLite database, uploaded attachments, and generated thumbnails. Back it up as a unit.
Prerequisites, ports, and volume constraints
- Docker Engine 24+ and the Compose v2 plugin (
docker compose version). - A hostname with an A/AAAA record pointing at the server if you want HTTPS. You can test on
127.0.0.1:5230first. - Port
5230is the documented HTTP port. Bind it to localhost and let a reverse proxy terminate TLS. - One named volume,
memos_data, mounted at/var/opt/memos. Do not use a bind mount to an arbitrary host path; a named volume keeps ownership and permissions consistent across image upgrades. - The image is
neosmemo/memos. Tags:stablefollows stable releases, a month tag like26.10pins to that month's stable release, andcanaryfollows development builds. Usestableunless you have a reason not to.
Memos does not need a separate database or cache container for a standard deployment. SQLite is embedded. If you later move to an external database, that is a configuration change, not a Compose dependency you need on day one.
Production Docker Compose setup
Create a working directory and write the Compose file and environment file.
mkdir -p ~/memos && cd ~/memos
cat <<'EOF' > compose.yml
services:
memos:
image: neosmemo/memos:${MEMOS_TAG:-stable}
container_name: memos
restart: unless-stopped
ports:
- "127.0.0.1:${MEMOS_PORT:-5230}:5230"
environment:
TZ: ${TZ:-UTC}
volumes:
- memos_data:/var/opt/memos
volumes:
memos_data:
EOF
Generate the environment file. Memos itself does not require a secret in the container environment for a single-instance SQLite deployment; the first account you create becomes the admin. Keep the file for timezone, port, and image tag so the stack is reproducible.
cat <<EOF > .env
TZ=UTC
MEMOS_PORT=5230
MEMOS_TAG=stable
EOF
Start the stack:
docker compose up -d
docker compose logs -f memos
You should see the server bind on 5230. Open http://127.0.0.1:5230 from the host, or tunnel it from your laptop:
ssh -L 5230:127.0.0.1:5230 user@your-server
Then visit http://localhost:5230 locally. The first account you register is the admin. Do that before you expose the instance publicly.
Reverse proxy, HTTPS, and first-run hardening
Memos is a normal HTTP app behind a proxy. The important details:
- Forward
HostandX-Forwarded-Protoso generated links and the web UI use the correct scheme. - Allow WebSocket upgrades. The UI uses them for live updates; a proxy that strips
Upgrade/Connectionheaders will cause reconnect loops. - Set a request body limit large enough for image attachments. 25 MB is a reasonable starting point; raise it if you upload large files.
- Do not cache API responses. Memos is stateful and per-user.
Caddy example (/etc/caddy/Caddyfile):
memos.example.com {
encode zstd gzip
request_body {
max_size 25MB
}
reverse_proxy 127.0.0.1:5230 {
header_up X-Forwarded-Proto {scheme}
header_up Host {host}
}
}
Nginx example:
server {
listen 443 ssl http2;
server_name memos.example.com;
client_max_body_size 25m;
location / {
proxy_pass http://127.0.0.1:5230;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
First-run hardening checklist:
- Register the admin account immediately after the container starts, before DNS points at the server or before you open the firewall.
- In the admin settings, turn off public sign-up unless you actually want strangers creating accounts. Memos lets you invite users individually.
- Review the default visibility for new memos. Private is the safe default; switch individual memos to public when you mean it.
- If you expose the instance publicly, keep the admin account behind a strong password and consider putting the login path behind your proxy's rate limiting.
Updating, backups, and common pitfalls
Update the image and restart:
cd ~/memos
docker compose pull
docker compose up -d
docker compose logs -f memos
Back up the data volume. Stop the container first so SQLite is not mid-write:
docker compose stop memos
docker run --rm \
-v memos_memos_data:/data \
-v "$PWD":/backup \
alpine tar czf /backup/memos-$(date +%F).tar.gz -C /data .
docker compose start memos
The volume name is <project>_memos_data; if your directory is ~/memos, the project name is memos, so the volume is memos_memos_data. Confirm with docker volume ls.
Two pitfalls worth knowing from the docs:
-
Upgrades from pre-v0.31.0. If you are coming from a release older than v0.31.0, run the v0.31.0 image once before jumping to a current tag. The migration notes in
store/migration/README.mdexplain why; skipping it can leave the database in a state the current image will not open. -
Tag drift.
stablemoves. If you need reproducible deploys, pinMEMOS_TAGto a month tag such as26.10and bump it deliberately.canaryis for testing, not for the instance holding your notes.
One more operational note: attachments live inside the same volume as the database. A backup that copies only the SQLite file will restore your memos without their images. Archive the whole /var/opt/memos tree, as the command above does.
Measured in our sandbox run: total memory 18.5 MB (sum of per-container peaks over a 30s idle window after startup) across 1 container; largest container 18.5 MB; published port(s) 5230; HTTP probe returned 200. The run took 41.5s including the image download.
Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.
Originally published with full interactive benchmark metrics and server sizing notes at https://vpsfolio.pages.dev/self-host-memos-docker-compose/.
Top comments (0)