Replicating to Linode Object Storage

This guide will show you how to use Linode Object Storage as a database replica path for Litestream. You will need a Linode account to complete this guide.

Setup

Create a bucket

In the Linode Console, click on “Object Storage” from the navigation and click the “Create Bucket” button. You may need to enable Object Storage on your account if you have not already.

Enter a globally unique name for your bucket and choose a region. Then click the “Submit” button.

Screenshot of Linode create bucket UI

After your bucket is created, you’ll see a hostname for the bucket in the format of BUCKETNAME.REGION.linodeobjects.com. You’ll need to use that later when configuring Litestream.

Create an access key

You’ll need to create a key to authenticate Litestream to your account so it can access the bucket. In the Object Storage console, click the Access Keys tab in the top navigation and then click the “Create an Access Key” button.

Enter a name for your key. You can enable Limited Access if you want to restrict the key to only certain buckets. Otherwise, click the “Submit” button.

Screenshot of Linode access key creation UI

You’ll be presented with the Access Key and Secret Key. You will need to copy those for use later.

Screenshot of Linode access key and secret key after creation

Usage

Command line usage

You can replicate to Linode Object Storage from the command line by setting environment variables with the credentials you obtained after creating your key:

export LITESTREAM_ACCESS_KEY_ID=xxxxxxxxxxxxxxxxxxxx
export LITESTREAM_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Then you can specify your replica hostname as a replica URL on the command line. For example, you can replicate a database to your bucket with the following command. Note that your region may be different.

litestream replicate /path/to/db s3://BUCKETNAME.us-east-1.linodeobjects.com/db

You can later restore your database from Linode Object Storage to a local my.db path with the following command.

litestream restore -o my.db s3://BUCKETNAME.us-east-1.linodeobjects.com/db

Configuration file usage

Litestream is typically run as a background service which uses a configuration file. You can configure a replica for your database using the url format. Note that your region may be different.

access-key-id: xxxxxxxxxxxxxxxxxxxx
secret-access-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxx

dbs:
  - path: /path/to/local/db
    replicas:
      - url: s3://BUCKETNAME.us-east-1.linodeobjects.com/db

Or you can expand your configuration into multiple fields:

dbs:
  - path: /path/to/local/db
    replicas:
      - type: s3
        bucket:   BUCKETNAME
        path:     db
        endpoint: https://us-east-1.linodeobjects.com
        region:   us-east-1   # set to your region

You may also specify your key credentials on a per-replica basis:

dbs:
  - path: /path/to/local/db
    replicas:
      - url: s3://BUCKETNAME.us-east-1.linodeobjects.com/db
        access-key-id: xxxxxxxxxxxxxxxxxxx
        secret-access-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx