Memos Deployment Guide

English | 中文

Deploy the self-hosted memo service, memos, on fly.io. Automate database backups to B2 using litestream.

Acknowledgments to linkding-on-fly for inspiring this project.

Important Notice!

• If you want to deploy Memos on Fly.io but do not need Litestream to automatically back up your database to your S3/B2, skip the following part of this document and read README_no_litestream directly.

• If you want to set up locally (including Litestream functionality) instead of on fly.io, you can refer to hu3rror/memos-litestream.

• hu3rror/memos-on-fly-build is deprecated, and the new project image maintenance updates will be transferred to hu3rror/memos-litestream. If you have used this image before, you can simply delete the old image in the build image section of your fly.toml and replace it with the new image, like this:

  [build]
  - image = "hu3rror/memos-fly:latest"
  + image = "ghcr.io/hu3rror/memos-litestream:stable"

• After updating to Memos v0.22.0, the Telegram Bot will no longer be built into Memos but will be started externally as telegram-integration. If you need this feature, you could change the image tag to ghcr.io/hu3rror/memos-litestream:stable-memogram, like this:

  [build]
  - image = "ghcr.io/hu3rror/memos-litestream:stable"
  + image = "ghcr.io/hu3rror/memos-litestream:stable-memogram"

  And add a new environment variable BOT_TOKEN to flyctl secrets in fly.io and deploy again.

  flyctl secrets set BOT_TOKEN="your_bot_token"

  ⚠️ The stable-memogram tag version is still in the testing phase, please back up your database before use.

Prerequisites

• fly.io account

• Backblaze account or another B2 service account

• Follow the instructions to install fly's command-line interface flyctl.

• Log into flyctl.

  flyctl auth login

• [Optional] If building your docker image, clone the repository from hu3rror/memos-litestream.

Launch a fly application

Do not set up Postgres and do not deploy yet!

flyctl launch

This command creates a fly.toml file.

Edit your fly.toml

Use fly_example.toml in this repository as a reference and modify according to the comments.

Details of manual modifications

1. Add a build section.

[build]
  image = "ghcr.io/hu3rror/memos-litestream:stable"

2. Add an env section.

[env]
  LITESTREAM_REPLICA_BUCKET = "To_be_filled_in_later."  # change to your litestream bucket name
  LITESTREAM_REPLICA_ENDPOINT = "To_be_filled_in_later"  # change to your litestream endpoint URL
  LITESTREAM_REPLICA_PATH = "memos_prod.db"  # keep the default or change to whatever path you want

3. Configure litestream backups

ℹ️ If you want to use another storage provider, check litestream's "Replica Guides" section and adjust the config as needed.

1. Log into B2 and create a bucket. Instead of adjusting the litestream config directly, add storage configuration to fly.toml.
2. Set the values of LITESTREAM_REPLICA_ENDPOINT and LITESTREAM_REPLICA_BUCKET to your [env] section.
3. Create an access key for this bucket. Add the key to fly's secret store.

flyctl secrets set LITESTREAM_ACCESS_KEY_ID="your_key_Id" LITESTREAM_SECRET_ACCESS_KEY="your_application_Key"

4. Add a persistent volume

1. Create a persistent volume. Fly's free tier includes 3GB of storage across your VMs. Since memos is very light on storage, a 1GB volume will be more than enough for most use cases. Change the volume size later if needed. Find instructions in the "scale persistent volume" section below.

flyctl volumes create memos_data --region your_region --size size_in_GB

For example:

flyctl volumes create memos_data --region hkg --size 1

2. Attach the persistent volume to the container by adding a mounts section to fly.toml.

[[mounts]]
  source = "memos_data"
  destination = "/var/opt/memos"

5. Add internal_port to [[services]]

[http_service]
  internal_port = 5230   # change to 5230

6. Deploy to fly.io

flyctl deploy

If all is well, access memos by running flyctl open. You should see its login page.

All done!

🎊 Enjoy using memos!

Other

How to update to the latest memos release

Check the status of memos's docker image built by GitHub Actions.

If the latest docker image is on Docker Hub, upgrade memos with flyctl deploy in your project's folder.

Custom Domains

If desired, configure a custom domain for your install.

Verify the installation

• Log into your memos instance.
• Find an initial replica of your database in your B2 bucket.
• Confirm your user data survives a VM restart.

Verify backups / scale persistent volume

Litestream continuously backs up your database by persisting its WAL to B2, once per second.

Two ways to verify backups:

1. Run the docker image locally or on a second VM. Verify the DB restores correctly.
2. Swap the fly volume for a new one and verify the DB restores correctly.

Focus on 2 as it simulates an actual data loss scenario. This procedure can also scale your volume to a different size.

Start by making a manual backup of your data:

1. SSH into the VM and copy the DB to a remote. If only you use your instance, export bookmarks as HTML.
2. Make a snapshot of the B2 bucket in the B2 admin panel.

List all fly volumes and note the id of the memos_data volume. Then, delete the volume.

flyctl volumes list
flyctl volumes delete your_vol_id

This will result in a dead VM after a few seconds. Create a new memos_data volume. Your application should automatically attempt to restart. If not, restart it manually.

When the application starts, you should see the successful restore in the logs.

[info] No database found, attempt to restore from a replica.
[info] Finished restoring the database.
[info] Starting litestream & memos service.

Pricing

Assuming one 256MB VM and a 3GB volume, this setup fits within Fly's free tier. ¹ Backups with B2 are free as well. ²

Troubleshooting

Litestream is logging 403 errors

Check that your B2 secrets and environment variables are correct.

fly ssh console does not connect

Check the output of flyctl doctor. Every line should be marked as PASSED. If Pinging WireGuard fails, try flyctl wireguard reset and flyctl agent restart.

Fly does not pull in the latest version of memos

Run flyctl deploy --no-cache.

Memos Telegram bot does not respond

Due to the fly.toml v2 update, modify your fly.toml like:

[http_service]
  auto_stop_machines = false   # change to `false` if you use the Telegram bot

Footnotes

1. Otherwise, the VM is ~$2 per month. $0.15/GB per month for the persistent volume.' ↩

2. The first 10GB are free, then $0.005 per GB. ↩