{"id":20128661,"url":"https://github.com/hu3rror/memos-on-fly","last_synced_at":"2025-07-08T22:05:25.002Z","repository":{"id":104296001,"uuid":"580275081","full_name":"hu3rror/memos-on-fly","owner":"hu3rror","description":"✍ Run memos on fly.io. Backup the memos DB to cloud storage with litestream. ","archived":false,"fork":false,"pushed_at":"2024-05-31T03:37:48.000Z","size":73,"stargazers_count":62,"open_issues_count":0,"forks_count":12,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-02T21:31:16.520Z","etag":null,"topics":["flyio","litestream","memos"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hu3rror.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-20T06:39:32.000Z","updated_at":"2025-01-31T17:01:41.000Z","dependencies_parsed_at":"2024-05-22T09:31:41.454Z","dependency_job_id":"9b94b506-dae9-4b48-9317-ff2eb00905f7","html_url":"https://github.com/hu3rror/memos-on-fly","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hu3rror/memos-on-fly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hu3rror%2Fmemos-on-fly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hu3rror%2Fmemos-on-fly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hu3rror%2Fmemos-on-fly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hu3rror%2Fmemos-on-fly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hu3rror","download_url":"https://codeload.github.com/hu3rror/memos-on-fly/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hu3rror%2Fmemos-on-fly/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264357296,"owners_count":23595576,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flyio","litestream","memos"],"created_at":"2024-11-13T20:28:42.384Z","updated_at":"2025-07-08T22:05:24.975Z","avatar_url":"https://github.com/hu3rror.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Memos Deployment Guide\n\nEnglish | [中文](README_zh-CN.md)\n\nDeploy the self-hosted memo service, [memos](https://github.com/usememos/memos), on [fly.io](https://fly.io/). Automate database backups to [B2](https://www.backblaze.com/b2/cloud-storage.html) using [litestream](https://litestream.io/).\n\nAcknowledgments to [linkding-on-fly](https://github.com/fspoettel/linkding-on-fly) for inspiring this project.\n\n## Important Notice!\n\n- 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](README_no_litestream.md) directly.\n- If you want to set up locally (including Litestream functionality) instead of on fly.io, you can refer to [hu3rror/memos-litestream](https://github.com/hu3rror/memos-litestream).\n- [hu3rror/memos-on-fly-build](https://github.com/hu3rror/memos-on-fly-build) is deprecated, and the new project image maintenance updates will be transferred to [hu3rror/memos-litestream](https://github.com/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:\n\n  ```diff\n  [build]\n  - image = \"hu3rror/memos-fly:latest\"\n  + image = \"ghcr.io/hu3rror/memos-litestream:stable\"\n  ```\n- 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](https://github.com/usememos/telegram-integration). If you need this feature, you could change the image tag to `ghcr.io/hu3rror/memos-litestream:stable-memogram`, like this:\n\n  ```diff\n  [build]\n  - image = \"ghcr.io/hu3rror/memos-litestream:stable\"\n  + image = \"ghcr.io/hu3rror/memos-litestream:stable-memogram\"\n  ```\n  And add a new environment variable `BOT_TOKEN` to flyctl secrets in fly.io and deploy again.\n  ```sh\n  flyctl secrets set BOT_TOKEN=\"your_bot_token\"\n  ```\n  ⚠️ The `stable-memogram` tag version is still in the testing phase, please back up your database before use.\n\n## Prerequisites\n\n- [fly.io](https://fly.io/) account\n- [Backblaze](https://www.backblaze.com/) account or another B2 service account\n- Follow [the instructions](https://fly.io/docs/getting-started/installing-flyctl/) to install fly's command-line interface `flyctl`.\n- [Log into flyctl](https://fly.io/docs/getting-started/log-in-to-fly/).\n\n  ```sh\n  flyctl auth login\n  ```\n\n- *[Optional]* If building your docker image, clone the repository from [hu3rror/memos-litestream](https://github.com/hu3rror/memos-litestream).\n\n\n## Launch a fly application\n\n\u003e **Do not** set up Postgres and **do not** deploy yet!\n\n```sh\nflyctl launch\n```\n\nThis command creates a `fly.toml` file.\n\n## Edit your `fly.toml`\n\nUse [fly_example.toml](fly_example.toml) in this repository as a reference and modify according to the comments.\n\n### Details of manual modifications\n\n#### 1. Add a `build` section.\n\n```toml\n[build]\n  image = \"ghcr.io/hu3rror/memos-litestream:stable\"\n```\n\n#### 2. Add an `env` section.\n\n```toml\n[env]\n  LITESTREAM_REPLICA_BUCKET = \"To_be_filled_in_later.\"  # change to your litestream bucket name\n  LITESTREAM_REPLICA_ENDPOINT = \"To_be_filled_in_later\"  # change to your litestream endpoint URL\n  LITESTREAM_REPLICA_PATH = \"memos_prod.db\"  # keep the default or change to whatever path you want\n```\n\n#### 3. Configure litestream backups\n\n\u003e ℹ️ If you want to use another storage provider, check litestream's [\"Replica Guides\"](https://litestream.io/guides/) section and adjust the config as needed.\n\n1. Log into B2 and [create a bucket](https://litestream.io/guides/backblaze/#create-a-bucket). Instead of adjusting the litestream config directly, add storage configuration to `fly.toml`.\n2. Set the values of `LITESTREAM_REPLICA_ENDPOINT` and `LITESTREAM_REPLICA_BUCKET` to your `[env]` section.\n3. Create [an access key](https://litestream.io/guides/backblaze/#create-a-user) for this bucket. Add the key to fly's secret store.\n\n```sh\nflyctl secrets set LITESTREAM_ACCESS_KEY_ID=\"your_key_Id\" LITESTREAM_SECRET_ACCESS_KEY=\"your_application_Key\"\n```\n\n#### 4. Add a persistent volume\n\n1. Create a [persistent volume](https://fly.io/docs/reference/volumes/). 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.\n\n```sh\nflyctl volumes create memos_data --region your_region --size size_in_GB\n```\n\nFor example:\n\n```sh\nflyctl volumes create memos_data --region hkg --size 1\n```\n\n2. Attach the persistent volume to the container by adding a `mounts` section to `fly.toml`.\n\n```toml\n[[mounts]]\n  source = \"memos_data\"\n  destination = \"/var/opt/memos\"\n```\n\n#### 5. Add `internal_port` to `[[services]]`\n\n```toml\n[http_service]\n  internal_port = 5230   # change to 5230\n```\n\n#### 6. Deploy to fly.io\n\n```sh\nflyctl deploy\n```\n\nIf all is well, access memos by running `flyctl open`. You should see its login page.\n\n## All done!\n\n🎊 Enjoy using memos!\n\n## Other\n\n### How to update to the latest memos release\n\nCheck the [status](https://github.com/hu3rror/memos-on-fly/actions/workflows/build-and-push-release-image.yml) of memos's docker image built by GitHub Actions.\n\nIf the latest docker image is on Docker Hub, upgrade memos with `flyctl deploy` in your project's folder.\n\n### Custom Domains\n\nIf desired, [configure a custom domain for your install](https://fly.io/docs/app-guides/custom-domains-with-fly/).\n\n### Verify the installation\n\n- Log into your memos instance.\n- Find an initial replica of your database in your B2 bucket.\n- Confirm your user data survives a VM restart.\n\n#### Verify backups / scale persistent volume\n\nLitestream continuously backs up your database by persisting its [WAL](https://en.wikipedia.org/wiki/Write-ahead_logging) to B2, once per second.\n\nTwo ways to verify backups:\n\n1.  Run the docker image locally or on a second VM. Verify the DB restores correctly.\n2.  Swap the fly volume for a new one and verify the DB restores correctly.\n\nFocus on _2_ as it simulates an actual data loss scenario. This procedure can also scale your volume to a different size.\n\nStart by making a manual backup of your data:\n\n1.  SSH into the VM and copy the DB to a remote. If only you use your instance, export bookmarks as HTML.\n2.  Make a snapshot of the B2 bucket in the B2 admin panel.\n\nList all fly volumes and note the id of the `memos_data` volume. Then, delete the volume.\n\n```sh\nflyctl volumes list\nflyctl volumes delete your_vol_id\n```\n\nThis 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.\n\nWhen the application starts, you should see the successful restore in the logs.\n\n```\n[info] No database found, attempt to restore from a replica.\n[info] Finished restoring the database.\n[info] Starting litestream \u0026 memos service.\n```\n\n### Pricing\n\nAssuming one 256MB VM and a 3GB volume, this setup fits within Fly's free tier. [^0] Backups with B2 are free as well. [^1]\n\n[^0]: Otherwise, the VM is ~$2 per month. $0.15/GB per month for the persistent volume.'\n[^1]: The first 10GB are free, then $0.005 per GB.\n\n## Troubleshooting\n\n### Litestream is logging 403 errors\n\nCheck that your B2 secrets and environment variables are correct.\n\n### `fly ssh console` does not connect\n\nCheck the output of `flyctl doctor`. Every line should be marked as **PASSED**. If `Pinging WireGuard` fails, try `flyctl wireguard reset` and `flyctl agent restart`.\n\n### Fly does not pull in the latest version of memos\n\nRun `flyctl deploy --no-cache`.\n\n### Memos Telegram bot does not respond\n\nDue to the fly.toml v2 update, modify your fly.toml like:\n\n```toml\n[http_service]\n  auto_stop_machines = false   # change to `false` if you use the Telegram bot\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhu3rror%2Fmemos-on-fly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhu3rror%2Fmemos-on-fly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhu3rror%2Fmemos-on-fly/lists"}