Overview
This guide will walk you through the steps of getting a LiteFS cluster up and
running on Fly.io. For a full, working example of a LiteFS application, please see the
litefs-example repository.
Installing LiteFS
Dependencies
The litefs binary is self-contained, but you’ll need to install the fuse3
library so LiteFS is able to mount a local file system. You’ll also need
ca-certificates if you’re connecting to Consul, and you’ll almost certainly
want to install sqlite. This installation depends on your package manager, but
here is a line you can add to your Dockerfile for alpine-based or debian-based images:
Installing LiteFS
LiteFS is meant to run inside your container alongside your application. You
can pull in the litefs binary by copying it from the official Docker image:
It’s recommended that you run LiteFS as root in Docker instead of using the
USER command to change users. If you need to run your application as another
user, use the su command to run your application as a non-root user.
Take a look at the example Dockerfile in the litefs-example repo
for an example.
Configuring LiteFS
Most configuration options for LiteFS are set via a YAML configuration file
called litefs.yml. This file is typically placed in /etc/litefs.yml, but
you can change the path by using the -config flag.
Take a look at
the litefs.yml file
in the litefs-example repo for a full example, or follow along with the
rest of this section for a more detailed explanation!
File system
Let’s first set two fields to tell LiteFS where to mount its file system and
where to store its internal data.
If you’re running on Fly.io, you should create a volume:
And then specify it as a mount in your fly.toml:
Lease configuration
LiteFS only allows a single node to be the primary at any given time. The
primary node is the only one that can write data to the database. The other
nodes are called replicas and they provide a read-only copy.
The primary is determined by using a distributed lease.
In this guide, we’ll be using a Consul lease as it allows the primary to
automatically failover in order to have high write availability. You can add a
Consul URL to your app with:
That will set a FLY_CONSUL_URL secret for the app, which will have the cluster url.
Then in your litefs.yml, set the lease section:
You can find more details in the lease management section of the configuration
guide.
Configuring the proxy
LiteFS requires that all writes occur on the primary node, which means
that applications need to redirect write requests to the current primary. It’s
also possible to issue a write to the primary and then read from a replica
before the change is propagated to that replica.
Most web applications can take advantage of a thin, built-in proxy
inside LiteFS that automatically handles these write redirection and replica
consistency issues. In order to make use of this proxy, your application needs
to follow these rules:
-
GET requests never perform write operations (e.g. INSERT, UPDATE, etc).
-
Clients have cookies enabled.
To configure the proxy, you’ll need to set the proxy section in the config file:
You can find more details on the proxy configuration guide.
Running LiteFS
The main command used to start LiteFS is the litefs mount command. This mounts
a FUSE file system and then starts an API server for LiteFS nodes to
communicate with each other. You can use this as the ENTRYPOINT in your
Dockerfile:
Running as a supervisor
LiteFS can either be run on its own or it can act as a simple supervisor process
for your application. Running as a supervisor lets LiteFS wait to start the
application until after it has connected to the cluster.
You can specify one or more commands in the exec section of your config. If
you set lease.promote to true, then you can specify to run your migration
scripts only on candidate nodes. This means that candidates will automatically
promote to the primary and run the migrations.
Testing your LiteFS instance
Once LiteFS is mounted, you can use SQLite clients or the sqlite3 CLI to
interact with databases on the mount directory:
LiteFS only allows files in the root of the mount and it does not currently
support subdirectories.
Importing your database
If you have an existing database, you can import it using the litefs import
command.
Refer to the litefs import documentation for more details.
You should only interact with SQLite databases on LiteFS through
a SQLite client or through the litefs tooling.
Do not use cp to copy a database into place.
Next steps
Back up your LiteFS cluster.
