This is a quick step-by-step guide to setting up the self-hosted version from scratch.

Step 1: Acquire hardware

• If you have a laptop, desktop, or Raspberry Pi to run this on, you're good to go
• If you want to use a server instead, Ubuntu on DigitalOcean is a reasonable choice

Step 2: Download release

• Purchasing the self-hosted version gives you access to download releases from https://checklists.fyi/releases
• Pick your target platform and download a release

Step 3: Unpack release

You should now have a tar.gz file. Unarchive it:

# untar the archive
$ tar zxvf checklists-fyi-selfhost-linux-amd64.bin.tar.gz

# make sure we now have a .bin file
$ ls
checklists-fyi-selfhost-linux-amd64.bin

# rename it to something a bit less unwieldy
$ mv checklists-fyi-selfhost-linux-amd64.bin checklists.fyi

The executable that results is a static binary that contains the entire app, including the frontend & API

Step 4: License

Provide your license to unlock your copy of checklists.fyi self-hosted:

$ checklists.fyi license --email "<email address>" --key "<license key>"
License valid...this installation of checklists.fyi is now ready to use.

Step 5: Configuration

Provide a signing secret for authentication tokens via the JWT_SECRET environment variable:

$ export JWT_SECRET="$(uuidgen)-$(uuidgen)"

Next up, email. checklists.fyi uses email for authentication (OTP login) and notifications, and needs to be connected to an email provider. Here are instructions to set it up for each supported provider that is currently available:

File (Trivial)

• Set --email-provider=file
• Appends all emails to a local file on disk
• Suitable for single-user and/or offline-only installations
• Pass a filename/path via the --email-file command-line flag

Mock (Trivial)

• Set --email-provider=mock
• Writes each email to a temporary HTML file and open it in a local browser
• Suitable for single-user and/or offline-only installations

SMTP (Easy)

• Set --email-provider=smtp
• Pick an SMTP provider; your current personal email provider likely supports it, as does Mailchimp and SendGrid
• Determine your SMTP provider's hostname and port, as well as your credentials (sender email and password)
• As an example, GMail uses smtp.gmail.com as the hostname, 587 as the port, and an app password as the password
• Provide this data to the app via the --email-sender, --smtp-host, --smtp-port, and --smtp-password command-line flags

Amazon SES (Advanced)

• Set --email-provider=ses
• Register for an AWS account if you don't have one already
• Set up SES on the AWS console by adding your domain and setting up a verified identity
• Use IAM to create a user that has full access to SES
• Download credentials (access key ID, secret key) for this user
• Provide these credentials to the app via the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, as well as the --email-sender command-line flag

Step 5: Start it up!

This section assumes you're using Gmail via the SMTP email provider

Use this incantation to start checklists.fyi:

$ ./checklists.fyi serve \
    --data-dir <empty directory for database storage> \
    --email-sender <your gmail address> \
    --email-provider smtp \
    --smtp-host smtp.gmail.com \
    --smtp-password <gmail app password>
       _                  _     _  _       _             __         _
      | |                | |   | |(_)     | |           / _|       (_)
  ___ | |__    ___   ___ | | __| | _  ___ | |_  ___    | |_  _   _  _
 / __|| '_ \  / _ \ / __|| |/ /| || |/ __|| __|/ __|   |  _|| | | || |
| (__ | | | ||  __/| (__ |   < | || |\__ \| |_ \__ \ _ | |  | |_| || |
 \___||_| |_| \___| \___||_|\_\|_||_||___/ \__||___/(_)|_|   \__, ||_|
                                                              __/ |
                                                             |___/

checklists.fyi config:
- Version: 0.0.1
- Environment: production
- Build Time: 2022-09-30T19:33:37
- Self hosted: true

2022/09/30 19:47:51 Migrating databases...
2022/09/30 19:47:51 Migrated databases in 0.139192 seconds
2022/09/30 19:47:51 Starting web server at 127.0.0.1:8080
2022/09/30 19:47:51 Starting metrics endpoint at 127.0.0.1:9999

And that's it! Navigate to http://localhost:8080 to get started.

Step 6: Tips

• Use a reverse proxy like Caddy that proxies to the checklists.fyi webserver
• All data in the --data-dir is stored in SQLite databases; backing them up is easy
• A very relaxed CORS policy is used by default; use the --allowed-origins flag to tighten this up
• The command-line interface is well documented and has more features that are out of scope here. Start exploring at ./checklists.fyi --help and go from there

Prev: Introduction to self-hosting checklists.fyi