📚 Documentation Issue Summary

The documentation currently lacks a guide for deploying MCP Gateway to Fly.io, a developer-friendly platform for running apps globally with built-in TLS, persistent volumes, and Postgres services.

📍 Location of the Problem

Suggested location: docs/docs/deployment/fly-io.md

✏️ Type of Issue

• Missing explanation or example
• Unclear deployment coverage

💡 Suggested Fix or Clarification

Create a new deployment guide following the format used in docs/docs/deployment/ibm-code-engine.md. Include both a Fly Launch (guided) path and a manual CLI workflow.

✅ Overview

• Explain Fly.io as a global app platform for containers.
• Emphasize free-tier availability and built-in TLS with fly.dev subdomain.
• Mention support for Postgres (via fly postgres create).

🛠 Prerequisites

• Fly.io account (https://fly.io)
• Fly CLI (brew install flyctl or see docs)
• Docker or Podman (for local image builds, optional)
• .env file with secure values (JWT_SECRET_KEY, DATABASE_URL)
• fly.toml config file

⚙️ Setup Steps

1. Initialize Fly project

fly launch --name mcpgateway --image mcpgateway:latest --no-deploy

2. Create volume (optional, for SQLite)

fly volumes create mcpgw_data --region ord --size 1

3. Create Fly Postgres (for production)

fly postgres create --name mcpgw-db --region ord
fly postgres attach --app mcpgateway --postgres-app mcpgw-db

4. Set secrets

fly secrets set JWT_SECRET_KEY=$(openssl rand -hex 32)
fly secrets set BASIC_AUTH_USER=admin BASIC_AUTH_PASSWORD=changeme
fly secrets set DATABASE_URL=postgresql://...

5. Deploy

fly deploy

🔒 Auth & Access

Generate a token locally:

python -m mcpgateway.utils.create_jwt_token -u admin

Then access:

curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     https://mcpgateway.fly.dev/tools

📝 Features to Document

• Persistent volume for SQLite (ephemeral vs. persistent)
• Using fly secrets to inject .env values
• TLS support by default
• Optional: custom domain setup with certs
• Restart/scale config (fly scale)

🧩 Additional Notes

See https://fly.io/docs for volume limitations and app restart behavior. Mirror structure from IBM Code Engine doc where possible for consistency.