kjvstudy.org/FLY_DEPLOYMENT.md

Fly.io Deployment Guide

This document describes how to deploy kjvstudy.org to Fly.io.

Prerequisites

• Fly.io CLI installed
• Fly.io account created

Configuration

The app is configured for optimal performance on Fly.io:

Memory & CPU

• Memory: 2GB (to handle 139MB uncompressed interlinear data in memory)
• CPUs: 2 shared CPUs
• Auto-scaling: Machines stop when idle, start automatically on requests

Health Checks

• Endpoint: /health
• Interval: Every 15 seconds
• Timeout: 10 seconds
• Grace period: 30 seconds for startup

Data Optimization

• Interlinear Bible data compressed to 13.5 MB (from 139 MB)
• Cache warming on startup - data preloaded for fast first requests
• Production logging with error handling
• Configurable via PRELOAD_INTERLINEAR environment variable

Deployment Steps

Initial Setup

# Login to Fly.io
fly auth login

# Deploy the app
fly deploy

Viewing Logs

# Stream logs
fly logs

# View specific number of log lines
fly logs -n 100

Monitoring

# Check app status
fly status

# View app info
fly info

# Open the app in browser
fly open

Scaling

# Scale memory if needed
fly scale memory 4096

# Scale CPUs
fly scale count 2

Important Files

• fly.toml - Fly.io configuration
• Dockerfile - Multi-stage build with uv
• .dockerignore - Excludes large uncompressed files
• kjvstudy_org/interlinear_data.py.gz - Compressed interlinear data (13.5 MB)
• kjvstudy_org/interlinear_loader.py - Lazy loader with error handling

Performance Notes

Memory Usage

• Base app: ~200-300 MB
• Interlinear data (loaded): ~139 MB
• Total: ~400-500 MB
• Allocated: 2 GB (comfortable headroom)

Startup Time

• Docker build: ~30-60 seconds
• With preload enabled (default):
  • App startup: ~7-10 seconds (loads data on startup)
  • All requests: <100ms (cache is warm)
• With preload disabled:
  • App startup: ~5 seconds
  • First interlinear request: ~2-3 seconds
  • Subsequent requests: <100ms

Auto-Scaling

• Machines stop after 5 minutes of inactivity
• First request after sleep: ~5-10 seconds (cold start + data load)
• Consider keeping 1 machine always running for production:

  fly scale count 1 --max-per-region 1
  

Configuration Options

Disable Preload (if needed)

If you want faster startup at the cost of slower first interlinear request:

1. Edit fly.toml:

[env]
PRELOAD_INTERLINEAR = "false"  # Disable cache warming

2. Deploy:

fly deploy

When to disable:

• Testing/development environments
• If startup time is critical
• If interlinear feature is rarely used

When to keep enabled (default):

• Production environments
• When users frequently access interlinear verses
• When you want consistent fast performance

Troubleshooting

Data Loading Errors

Check logs for interlinear data loading:

fly logs | grep -i interlinear

Should see:

Loading interlinear data from /app/kjvstudy_org/interlinear_data.py.gz...
Successfully loaded 31031 verses

Memory Issues

If OOM errors occur, increase memory:

fly scale memory 4096

SSL/HTTPS

Fly.io automatically provides SSL certificates. The force_https = true setting ensures all HTTP requests redirect to HTTPS.

URLs

• Production: https://kjvstudy.fly.dev
• Health check: https://kjvstudy.fly.dev/health
• Interlinear Bible: https://kjvstudy.fly.dev/interlinear

Support

For Fly.io specific issues, see:

• Fly.io Documentation
• Fly.io Community