Running in a Docker container
This guide will show you how to run Litestream within a Docker container either as a sidecar or within the same container as your application. You will need a Docker installed on your machine for this guide.
Docker is a common tool for deploying applications and Litestream can be easily integrated into your workflow. Docker typically recommends running one application per container and Litestream can be run as a sidecar to another container. However, some deployment models do not support this so we’ll show you how to run your application & Litestream in the same container as well.
Running as a sidecar
Litestream provides an official image via Docker Hub. You can use it with a configuration file or with a replica URL.
Using a configuration file
Typically, it’s recommended to run Litestream using a configuration file as it provides more configuration options. First, create your configuration file:
access-key-id: YOUR_ACCESS_KEY_ID secret-access-key: YOUR_SECRET_ACCESS_KEY dbs: - path: /data/db replicas: - url: s3://BUCKET/db
Note that the database
path is using the
/data path in your Docker container.
Also, you can specify access key & secret key via environment variables instead.
Next, you’ll need to attach both your data directory and your configuration file via a volume:
docker run \ -v /local/path/to/data:/data \ -v /local/path/to/litestream.yml:/etc/litestream.yml \ litestream/litestream replicate
You can also use named volumes instead of absolute paths. See Docker’s Use volumes documentation for more information about which one to use.
Now that Litestream is running, you can start your application and mount the same data volume.
Using a replica URL
For basic replication of a single database, you can set your S3 credentials via environment variables, mount a volume to read from, and specify the path and replica as arguments:
docker run \ --env LITESTREAM_ACCESS_KEY_ID \ --env LITESTREAM_SECRET_ACCESS_KEY \ -v /local/path/to/data:/data \ litestream/litestream replicate /data/db s3://BUCKET/db
This command will use the
environment variables in your current session and pass those into your Docker
container. You can also set the values explicitly using the
The command then mounts a volume from your localpath to the
inside the container.
replicate command will replicate data from the
db database file
/data volume to an S3 bucket. You’ll need to replace
BUCKET with the
name of your bucket.
Running in the same container
If you are deploying to a service like Fly.io that only uses a single
container, you can bundle both your application and Litestream together using
Litestream’s built-in process supervision. You can specify your application’s
process and flags by passing them to the
litestream replicate -exec "myapp -myflag myarg"
Or you can pass them in via the config file:
dbs: - path: /path/to/db exec: myapp -myflag myarg
Litestream will monitor your application’s process and automatically shutdown when it closes. You can find an example application in the litestream-docker-example repository.
When you use the
-exec flag, Litestream will pass in the first database path
from your configuration to the child process as the
If you need to monitor multiple application processes, you can also use s6 as a process supervisor. s6 provides a simple init system for managing multiple processes. It is wrapped by the s6-overlay project to provide this service to Docker containers. You can find a small example application in the litestream-s6-example repository.