Deploy to Fly.io

Overview

We use fly.io as a low-cost and developer-friendly cloud service provider. This document serves as an example of the steps required to deploy a usable service to their platform.

Reference: GitHub Discussion #473

---

Deployment Steps

1. Create fly.toml Configuration

Start by copying the template configuration file:

cp config/fly.toml.template fly.toml

Edit fly.toml and ensure the following values are set:

app = "whereis-api-v0-example"   

[[mounts]]
  source = 'whereis_api_vol'
  destination = '/data'

Initialize the fly app without deploying:

fly launch --no-deploy

2. Create a Data Volume

Create a 3GB volume in your preferred region (e.g., sjc):

fly volumes create whereis_api_vol --region sjc --size 3

3. Deploy the Application

Deploy the app on fly.io

make fly-deploy

4. Test the Deployment

Verify the service is running via a simple curl request:

curl https://whereis-api-v0-example.fly.dev/v0/status/eg1-123412341234

You can also SSH into the console to verify the environment and data volume:

fly ssh console -s -u deno -C "ls -lh /data"
# Expected output: -rw-r--r-- 1 deno deno 84K Jun 10 23:34 whereis.sqlite

### Useful commands
fly ssh console -s -u deno -C "df -h /data"
fly ssh console -s -u deno -C "deno task version"
fly ssh console -s -u deno -C 'deno list'
fly ssh console -s -C 'ps -u deno -f'

5. Create API Keys

Generate API keys for different users directly from the console:

# To get a random key generated
fly ssh console -s -u deno -C "deno task api_key"

# To save an existing key 
fly ssh console -s -u deno -C "deno task api_key --user=old --key=sk-MY_OLD_KEY"

6. Add Source API Keys

Import external API keys securely using fly secrets:

cp config/source-api-keys.env.sample source-api-keys.env

# Modify the file

# Load the keys
fly secrets import < source-api-keys.env

7. Test Live FDX Tracking Numbers

Test endpoints using the generated API keys to authorize requests:

curl https://whereis-api-v0-example.fly.dev/v0/whereis/fdx-872516826430 \
  --header 'Authorization: Bearer sk-MY_KEY'

curl https://whereis-api-v0-example.fly.dev/v0/whereis/fdx-872515813308 \
  --header 'Authorization: Bearer sk-MY_KEY'

8. Setup Grafana Logging

Grafana Setup:

1. Configure Grafana variables for logging: GRAFANA_URL, GRAFANA_USER, and GRAFANA_API_KEY.

Example in fly.toml:

[env]
  APP_ENV = "prod"
  DB_TYPE = "sqlite"
  WHEREIS_API_URL = "https://whereis-api-v0-example.fly.dev"
  TINI_SUBREAPER = true
  APP_PULL_INTERVAL = 10
  GRAFANA_URL = "https://logs-prod-001.grafana.net/"

Set these as secretes in fly.io (use cmd or with fly.io web dashboard) GRAFANA_USER GRAFANA_API_KEY

2. On Grafana, make sure the API key has "logs:write" access.

3. Scan logs for warnings like: warn `${whereIsAPI("data_monitor")} Entity ${entity.id} is missing major status: ${status}`,

Known Issues

1. Fly Deployment Cache: Sometimes pushing from GitHub to Fly results in cached old configs. You may need to manually destroy and rebuild the machine, ensuring the Dockerfile and fly.toml are correctly updated to force a fresh deploy.