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 Whereis API Keys

Generate any Whereis API keys so you or other users can use this service

# 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 Logistics 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/"
   

   In Fly.io, set the following as secrets:

   • GRAFANA_USER
   • GRAFANA_API_KEY

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

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.