Speedrun: Add LiteFS to your app

This guide will get your app up and running with LiteFS on Fly.io as fast as possible. If you run into any issues with this guide, or you’d like some more details or a slower pace, check out the Getting Started doc instead.

You can also take a look at the docs for your framework to see if LiteFS is supported by fly launch.

This guide assumes you already have a working Dockerfile for your app. If not, get that working (with regular sqlite), and then come back here!

Let’s do this!

1. Create a LiteFS Cloud cluster

Create a LiteFS Cloud cluster in the LiteFS section of the fly.io dashboard. Take note of your auth token (you’ll need it later).

LiteFS Cloud is optional, but highly recommended if your data is important to you!

2. Configure litefs.yml

Copy the sample litefs.yml file from the litefs-example repo, and make the following updates:

Update from 8081 in proxy.target to whatever port your app listens on
Update exec[0].cmd to the command that runs your app

3. Update your Dockerfile

Install LiteFS dependencies:

    # for alpine-based images
RUN apk add ca-certificates fuse3 sqlite
# or for debian/ubuntu-based images
RUN apt-get update -y && apt-get install -y ca-certificates fuse3 sqlite3

  

Copy in the LiteFS binary:

COPY --from=flyio/litefs:0.5 /usr/local/bin/litefs /usr/local/bin/litefs

Update the ENTRYPOINT (or CMD):

ENTRYPOINT litefs mount

4. Set up & deploy to the Fly Platform

Create a volume:

fly volumes create litefs --size 10

Create your app config, but don’t deploy it (say no when it asks):

fly launch

Configure consul (this sets the FLY_CONSUL_URL secret for your app, which is required for LitefS leases):

fly consul attach

Add the LiteFS Cloud secret (replace yoursecrettoken with the actual token value):

    fly secrets set LITEFS_CLOUD_TOKEN=yoursecrettoken

  

Update your fly.toml file to mount your volume:

    [mounts]
  source = "litefs"
  destination = "/var/lib/litefs"

  

Deploy your app:

fly deploy

TADA! You (hopefully) now have an app running with LiteFS! If you’re having trouble, you can ask for help in the Fly community.

5. Add some replicas in other regions

LiteFS isn’t super useful if you’re running only one node. So, add some more nodes in more regions!

    # Add a clone in London
fly m clone --select --region lhr
# Add a clone in Sydney
fly m clone --select --region syd

  

Edit this page on GitHub