{"id":20697960,"url":"https://github.com/fly-apps/fly-laravel-litefs","last_synced_at":"2025-04-22T21:29:32.907Z","repository":{"id":65354281,"uuid":"585554883","full_name":"fly-apps/fly-laravel-litefs","owner":"fly-apps","description":"Guide on deploying multiple instances of a Laravel Fly app and integrating LiteFS and fly-replay to allow syncing SQLite database across the instances. ","archived":false,"fork":false,"pushed_at":"2024-06-04T16:37:03.000Z","size":124,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-29T19:02:07.747Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fly-apps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-01-05T13:22:40.000Z","updated_at":"2024-12-24T09:06:58.000Z","dependencies_parsed_at":"2024-06-04T16:33:32.470Z","dependency_job_id":"de6540b2-f249-4f15-b4a3-ba09c8bfd9db","html_url":"https://github.com/fly-apps/fly-laravel-litefs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fly-apps%2Ffly-laravel-litefs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fly-apps%2Ffly-laravel-litefs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fly-apps%2Ffly-laravel-litefs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fly-apps%2Ffly-laravel-litefs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fly-apps","download_url":"https://codeload.github.com/fly-apps/fly-laravel-litefs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250327800,"owners_count":21412502,"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":[],"created_at":"2024-11-17T00:21:05.528Z","updated_at":"2025-04-22T21:29:32.886Z","avatar_url":"https://github.com/fly-apps.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi-instance Laravel-SQLite with LiteFS\nYou can run multiple instances of your [Laravel Fly Application](https://fly.io/docs/laravel/) with SQLite as primary database. You'll just have to make sure that each node's SQLite database is in-sync with each other. This is easily achievable by configuring your Laravel Fly App with [LiteFS](https://fly.io/docs/litefs/)! \n\n[`LiteFS`](https://fly.io/docs/litefs/how-it-works/) is a distributed file system that enables you to sync SQLite data across instances of your application.\n\nThis repository is a sample Laravel Fly-configured, LiteFS-configured application for reference.\n\n## Requirements\n1) Make sure you have a [Laravel Fly App](https://fly.io/docs/laravel/) deployed and running\n2) Make sure you have [more than one](https://fly.io/docs/flyctl/scale-count/#usage) instance of your Laravel Fly App\n3) Allocate [volumes](https://fly.io/docs/reference/volumes/) (with the same name) for each region you'll be deploying your instances in\n4) You've attached consul to the Laravel Fly App by running `fly consul attach`\n\n## Repository Overview\n\u003cb\u003eThis repository provides a reference for the minimal requirements to get started with integrating LiteFS:\u003c/b\u003e\n1. Fly.io, Volumed-SQLite, and LiteFS configuration in [`Dockerfile`](https://github.com/fly-apps/fly-laravel-litefs/blob/main/Dockerfile) | [`fly.toml`](https://github.com/fly-apps/fly-laravel-litefs/blob/main/fly.toml) | [`.fly/entrypoint.sh`](https://github.com/fly-apps/fly-laravel-litefs/blob/main/.fly/entrypoint.sh) and the [`etc`](https://github.com/fly-apps/fly-laravel-litefs/tree/main/etc) folder\n\n\n\u003cb\u003eAlong with additional bonuses for the complete experience:\u003c/b\u003e\n1. A sample [model](https://github.com/fly-apps/fly-laravel-litefs/blob/main/app/Models/Post.php), [controller](https://github.com/fly-apps/fly-laravel-litefs/blob/main/app/Http/Controllers/PostController.php), [view](https://github.com/fly-apps/fly-laravel-litefs/blob/main/resources/views/posts/create.blade.php), and route for creating and listing Post entries \n\n\n# LiteFS Configuration\n\nOnce you have a running Laravel Fly application, certain changes need to be done to your project's files:\n\n### 1. SubFolders\nFirst create a subfolder `database` inside the `storage` folder. We'll later mount a volume to this subfolder to persist data on it: the sqlite file our app will use, and the files litefs will store. It will contain two sub-subfolders: \"`database/app`\" to hold the sqlite file used by our Laravel app, and \"`database/litefs`\" for litefs to use in storing its files:\n```\n# We mount a volume to this later\n# to persist data it contains\nmkdir storage/database\n\n# To hold our sqlite file\nmkdir storage/database/app\n\n# For litefs' to store its files\nmkdir storage/database/litefs\n```\n\n\n### 2. [fly.toml](https://github.com/fly-apps/fly-laravel-litefs/blob/main/fly.toml)\nOur `fly.toml` file contains configuration for how our Laravel Fly app is set up. \n\nFirst, in its `env` section, we set an env variable pointing to the path of our Laravel Fly app's sqlite file. We'll point it to the sub-subfolder `storage/database/app`:\n```\n[env]\n    ...\n    DB_CONNECTION='sqlite'\n    DB_DATABASE='/var/www/html/storage/database/app/database.sqlite'\n```\n\nThen, we add a `mount` section to mount a volume on the `/var/www/html/storage/database` subfolder to persist data on it:\n```\n[[mounts]]\n  source = 'litefs'\n  destination = '/var/www/html/storage/database'\n```\n\n\n### 3. [etc/litefs.yml](https://github.com/fly-apps/fly-laravel-litefs/blob/main/etc/litefs.yml)\n\nThis file serves as the configuration reference LiteFS will use on `litefs mount` above. You can find a whole reference on it [here](https://fly.io/docs/litefs/config/#config-file-search-path). This section highlights the Laravel-config relevant parts of the [file](https://github.com/fly-apps/fly-laravel-litefs/blob/main/etc/litefs.yml) we've created for this repository.\n\n\n```yml\nfuse:\n    # This is the folder our database.sqlite is located in, as we've specified in our fly.toml file's env.DB_DATABASE attribute \n    dir: \"/var/www/html/storage/database/app\"\n    allow-other: true\n\ndata:\n  # This is the folder that litefs will use\n  dir: \"/var/www/html/storage/database/litefs\"\n\nexec: \n  - cmd: \"php /var/www/html artisan migrate --force\"\n  - cmd: \"supervisord -c /etc/supervisor/supervisord.conf\"\n\n```\n\n\u003cb\u003e1. The fuse.dir\u003c/b\u003e - Your Laravel application will make database transaction requests to the specified connection in your DB_DATABASE env. LiteFS needs to know where these transactions are happening, and so we specify the directory of our DB_DATABASE value in `fuse.dir`.\n\n\u003cb\u003e2. The fuse.allow-other\u003c/b\u003e - Once LiteFS has mounted the fuse in the fuse.dir, that directory's ownership gets updated to root. In order to allow none-root users to access the database.sqlite file found in that directory, include a `fuse.allow-other:true` option.\n\n\u003cb\u003e4. The data.dir\u003c/b\u003e - This is the directory LiteFS will use for its transactions. \n\n\u003cb\u003e5. The exec\u003c/b\u003e - Finally, we arrive at the `exec` block. We can use this subprocess to run our migrations, and most importantly start our server! \n\nOf course it still has the lease section which you shouldn't forget to add in, as well as the proxy section below that's useful for forwarding write requests. See our whole configuration for the etc/litefs.yml file [here](https://github.com/fly-apps/fly-laravel-litefs/blob/main/etc/litefs.yml).\n\n**Forwarding Write Requests to the Primary Node**\n\nWe want to forward write transactions to the primary node and not replica nodes. We can use LiteFS's built in proxy layer for forwarding write requests to the primary node.\n\nWe can do this by adding the proxy section in our etc/litefs.yml file:\n\n```yml\nproxy:\n  # This is the port the proxy will use\n  addr: \":8081\"\n  # This is where our Laravel app will serve, should match the internal_port with the http_service specified in fly.toml\n  target: \"localhost:8080\"\n  # This is the sqlite file it will handle transactions for, so make sure it's the same file used by the app\n  db: \"database.sqlite\"\n  passthrough: \n    - \"*.ico\"\n    - \"*.png\"\n```\n**NOTES:**\n1. Please make sure the target port matches with the internal_port we've specified in the internal_port of the http_service specified in fly.toml. \n\n2. For the db value, please make sure to provide the full name of the sqlite database used by our Laravel app. Which we've specified in our fly.toml file.\n\n\n### 4. [etc/fuse.conf](https://github.com/fly-apps/fly-laravel-litefs/blob/main/etc/fuse.conf)\n\nThe etc/fuse.conf file is required to enable the etc/litefs.yml's fuse.allow-other option to work. It only contains one line:\n\n```\nuser_allow_other\n```\n\nFinally, we revise files generated for our app by Fly.io during `fly launch` to use LiteFS with our app:\n\n### 5. [Dockerfile](https://github.com/fly-apps/fly-laravel-litefs/blob/main/Dockerfile)\n\nIn your dockerfile you'll need to retrieve the LiteFS image, install packages required by LiteFS, and copy litefs configuration files to the [proper location](https://fly.io/docs/litefs/config/#config-file-search-path) in your running container:\n```\n# LITEFS Dependencies\nRUN apt-get update -y \u0026\u0026 apt-get install -y ca-certificates fuse3 sqlite3\n\n# LITEFS Binary\nCOPY --from=flyio/litefs:0.5 /usr/local/bin/litefs /usr/local/bin/litefs\n\n# LITEFS config file move to proper location at /etc\nCOPY etc/litefs.yml /etc/litefs.yml\nCOPY etc/fuse.conf /etc/fuse.conf\n```\n\n### 6. [.fly/entrypoint.sh](https://github.com/fly-apps/fly-laravel-litefs/blob/main/.fly/entrypoint.sh) \nThis is our ENTRYPOINT in our Dockerfile, and the script that runs startup scripts and afterwards our server. We'll need to revise this file to ensure we run LiteFS instead of starting our server--once LiteFS successfully runs, it should also handle starting our server:\n```\nexec litefs mount\n```\n\n---\n\n\n### ERRORS!\nIf you encounter errors in your logs regarding litefs, you can follow steps in the [official recovery page](https://fly.io/docs/litefs/disaster-recovery/) to possibly fix your error.\n\nIn this Laravel setup, you might experience the following:\n\n1.**\"cannot become primary, local node has no cluster ID and \\\"consul\\\" lease already initialized with cluster ID ...\"**\n- to fix this, you'll have resolve your cluster id. This can be done two ways, with the easiest way being an [update of the string value](https://fly.io/docs/litefs/disaster-recovery/#easy-option-change-the-consul-key) specified in your litefs.yml file's `lease.consul.key` value to a unique value you've not yet specified for your current app. \n\n```\n# i.e\n\n# Update your existing key from an old value:\nlease\n  consul:\n    key: \"litefs/${FLY_APP_NAME}\"\n\n---------------------------------------------------------\n\n# TO something different:\nlease:\n  consul:\n    key: \"litefs/${FLY_APP_NAME}-2\" \n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffly-apps%2Ffly-laravel-litefs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffly-apps%2Ffly-laravel-litefs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffly-apps%2Ffly-laravel-litefs/lists"}