Repository files navigation

🔖 Run the self-hosted bookmark servicelinkding onfly.io. Automatically backup the bookmark database toBackblaze B2 withlitestream.

Assuming one 256MB VM and a 3GB volume, this setup fits within Fly's free tier.¹ Backups with Backblaze B2 are free as well.²

• Afly.io account
• ABackblaze account
• flyctl CLI installed.³

Instructions below assume that you have cloned this repository to your local computer:

git clone https://github.com/fspoettel/linkding-on-fly.git&&cd linkding-on-fly

Log intoBackblaze B2 andcreate a bucket. Once created, you will see the bucket's name and endpoint. You will use these later to populateLITESTREAM_REPLICA_BUCKET andLITESTREAM_REPLICA_ENDPOINT in thefly.toml configuration.

Next, createan application key for the bucket. Once created, you will see thekeyID andapplicationKey. You will add these later to Fly's secret store, save them for step 3 below.

Note
If you want to use another storage provider, check litestream's"Replica Guides" section and adjust the config as needed.

1. Login toflyctl:

   flyctl auth login

2. Generate fly app and create thefly.toml:

   Alternative: Generating from template

   You can generate thefly.toml from thetemplate provided in this repository.

   1. Installenvsubst if you don't have it already:

      # macOSbrew install gettext

   2. Copy the.env.sample file to.env, fill in the values and source them:

      cp .env.sample .env# vim .envsource .env

   3. Generate thefly.toml from the template:

      envsubst< templates/fly.toml> fly.toml

   4. Proceed to step 3.

   # Generate the initial fly.toml# When asked, don't setup Postgres or Redis.flyctl launch

   Next, open thefly.toml and add the followingenv andmounts sections (populatingLITESTREAM_REPLICA_ENDPOINT andLITESTREAM_REPLICA_BUCKET):

   [env]# linkding's internal port, should be 8080 on fly.LD_SERVER_PORT="8080"# Path to linkding's sqlite database.DB_PATH="/etc/linkding/data/db.sqlite3"# B2 replica path.LITESTREAM_REPLICA_PATH="linkding_replica.sqlite3"# B2 endpoint.LITESTREAM_REPLICA_ENDPOINT="<Backblaze B2 endpoint>"# B2 bucket name.LITESTREAM_REPLICA_BUCKET="<Backblaze B2 bucket name>"[mounts]source="linkding_data"destination="/etc/linkding/data"

3. Add the Backblaze application key to fly's secret store

   flyctl secretsset LITESTREAM_ACCESS_KEY_ID="<keyId>" LITESTREAM_SECRET_ACCESS_KEY="<applicationKey>"

4. Create apersistent volume to store thelinkding application data:

   # List available regions via: flyctl platform regionsflyctl volumes create linkding_data --region<region code> --size 1

   Note
   Fly's free tier includes3GB of storage across your VMs. Sincelinkding is very light on storage, a1GB volume will be more than enough for most use cases. It's possible to change volume size later. A how-to can be found in the"Verify Backups / Scale Persistent Volume" section below.

5. Add thelinkding superuser credentials to fly's secret store:

   flyctl secretsset LD_SUPERUSER_NAME="<username>" LD_SUPERUSER_PASSWORD="<password>"

6. Deploylinkding to fly:

   flyctl deploy

   Note
   TheDockerfile contains overridable build arguments:ALPINE_IMAGE_TAG,LINKDING_IMAGE_TAG andLITESTREAM_VERSION which can overridden by passing them toflyctl deploy like--build-arg LITESTREAM_VERSION=v0.3.11 etc.

That's it! 🚀 - If all goes well, you can now accesslinkding by runningflyctl open. You should see thelinkding login page and be able to log in with the superuser credentials you set in step 5.

If you wish, you canconfigure a custom domain for your install.

• You should be able to log into your linkding instance.
• There should be an initial replica of your database in your B2 bucket.
• Your user data should survive a restart of the VM.

Litestream continuously backs up your database by persisting itsWAL to the Backblaze B2 bucket, once per second.

There are two ways to verify these backups:

1. Run the docker image locally or on a second VM. Verify the DB restores correctly.
2. Swap the fly volume for a new one and verify the DB restores correctly.

We will focus on2 as it simulates an actual data loss scenario. This procedure can also be used to scale your volume to a different size.

Start by making a manual backup of your data:

1. SSH into the VM and copy the DB to a remote. If only you are using your instance, you can also export bookmarks as HTML.
2. Make a snapshot of the B2 bucket in the B2 admin panel.

Now list all fly volumes and note the id of thelinkding_data volume. Then, delete the volume:

flyctl volumes listflyctl volumes delete<id>

This will result in adead VM after a few seconds. Create a newlinkding_data volume. Your application should automatically attempt to restart. If not, restart it manually.

When the application starts, you should see the successful restore in the logs:

[info] No database found, attempt to restore from a replica.[info] Finished restoring the database.[info] Starting litestream & linkding service.

Check that your B2 secrets and environment variables are correct.

Check the output offlyctl doctor, every line should be marked asPASSED. IfPinging WireGuard fails, tryflyctl wireguard reset andflyctl agent restart.

• Override theDockerfile build argumentLINKDING_IMAGE_TAG:flyctl deploy --build-arg LINKDING_IMAGE_TAG=<tag>
• Runflyctl deploy with the--no-cache option.

If you have never used fly's SSH console before, begin by setting up fly's ssh-agent:

flyctl ssh establish# use agent if possible, otherwise follow on-screen instructions.flyctl ssh issue --agent

Then, runflyctl ssh console to get an interactive shell in your running container. You can now create a superuser by running thecreatesuperuser command and entering a password.

cd /etc/linkdingpython manage.py createsuperuser --username=<your_username> --email=<your_email>exit