DEV Community

konsongong
konsongong

Posted on Edited on Originally published at vpsfolio.pages.dev

Self-Host Memos with Docker Compose: A Production Setup Guide

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:5230 first.
  • Port 5230 is 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: stable follows stable releases, a month tag like 26.10 pins to that month's stable release, and canary follows development builds. Use stable unless 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Start the stack:

docker compose up -d
docker compose logs -f memos
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 Host and X-Forwarded-Proto so 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/Connection headers 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}
    }
}
Enter fullscreen mode Exit fullscreen mode

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";
    }
}
Enter fullscreen mode Exit fullscreen mode

First-run hardening checklist:

  1. Register the admin account immediately after the container starts, before DNS points at the server or before you open the firewall.
  2. In the admin settings, turn off public sign-up unless you actually want strangers creating accounts. Memos lets you invite users individually.
  3. Review the default visibility for new memos. Private is the safe default; switch individual memos to public when you mean it.
  4. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.md explain why; skipping it can leave the database in a state the current image will not open.
  • Tag drift. stable moves. If you need reproducible deploys, pin MEMOS_TAG to a month tag such as 26.10 and bump it deliberately. canary is 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)