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.

Let’s do this!

1. 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

2. 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

3. 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

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.

4. 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

Next steps

Back up your LiteFS cluster.