Deploy to Fly.io

why pick Fly.io

• Global edge — Fly deploys your app to regions close to your users. Usually overkill for a single-user webhook service, but it's free on the hobby plan.
• Plain Node runtime — runs the same @astrojs/node standalone output as Railway; no Docker authoring required, Fly generates a Dockerfile with fly launch.
• Upstash Redis addon — one-command provision (fly ext create upstash-redis), auto-injects REDIS_URL into the app.
• Stays cheap at idle — machines auto-stop when unused and auto-wake on request (set auto_stop_machines = "stop" in fly.toml).

prerequisites

• A Fly.io account — sign up at fly.io. Hobby plan is free with a small per-month credit.
• flyctl installed — brew install flyctl on macOS, or curl -L https://fly.io/install.sh | sh.
• Node 22+ locally for the initial build.

1 · launch the app

1. Log in to Fly

   fly auth login

2. Launch from the neuromast directory

   cd neuromast
   fly launch --no-deploy

   Wizard prompts: pick a region close to your Mac, skip the Postgres and "add a database" questions (we'll add Redis separately), and accept the generated Dockerfile. Fly writes a fly.toml with your app name.

3. Set ADAPTER=node as a build-time arg

   Edit the generated Dockerfile — add ENV ADAPTER=node before the npm run build line so Astro picks the Node adapter instead of Cloudflare:

   ENV ADAPTER=node
   RUN npm run build

4. Add Upstash Redis

   fly ext create upstash-redis

   Pick a region matching your app's. Fly creates the database and adds REDIS_URL as a secret on your app. Neuromast's storage factory auto-detects it.

5. Set the bearer + HMAC secrets

   fly secrets set POLL_TOKEN="$(openssl rand -hex 32)"
   fly secrets set SHARED_SECRET="$(openssl rand -hex 32)"    # optional
   fly secrets set HOOK_SCHEME_GITHUB=github HOOK_SECRET_GITHUB=<your-webhook-secret>

6. Deploy

   fly deploy

   Builds the Docker image, pushes to Fly's registry, runs a health check, switches traffic. First deploy takes ~2 minutes; subsequent ones are faster.

7. Probe the endpoints

   export AXOL_CLOUD_URL=https://<your-app>.fly.dev
   export POLL_TOKEN='the-bearer-you-set'
   export SHARED_SECRET='the-shared-key-you-set'
   
   curl -X POST "$AXOL_CLOUD_URL/app/api/hooks/smoke?key=$SHARED_SECRET" \
     -H 'content-type: application/json' \
     -d '{"title":"hello","body":"from fly"}'

2 · connect the local forwarder

AXOL_CLOUD_URL="$AXOL_CLOUD_URL" \
AXOL_POLL_TOKEN="$POLL_TOKEN" \
./lateral-line/install.sh

day-2 operations

Redeploying

fly deploy

For continuous deployment, Fly has an official GitHub Action (superfly/flyctl-actions). Add a FLY_API_TOKEN repo secret and a workflow that runs flyctl deploy --remote-only.

Rotating secrets

fly secrets set NAME=newvalue overwrites and triggers an automatic restart. Machines pick up the change within seconds.

Cost

Hobby: ~$5/month credit, covers a single small machine + Upstash Redis idle. Auto-stop reduces idle bill to near-zero; cold start adds ~2 s to the first request.

troubleshooting

• Deploy fails with "Cannot find module '@astrojs/node'"

  The Dockerfile ran npm ci with NODE_ENV=production, which skipped devDeps. Move @astrojs/node to dependencies (already done in neuromast's package.json — check your fork).

• Health check failing: "ECONNREFUSED" to Redis

  fly secrets list should show a REDIS_URL managed by upstash-redis. If missing, re-run fly ext create upstash-redis.

• 401 on every request

  fly secrets list to confirm POLL_TOKEN is set. Secrets are per-app — adding them to the wrong app is a common first-time mistake.

• App sleeping too aggressively

  Set auto_stop_machines = "off" in fly.toml to keep machines warm. Trade-off: higher idle bill. Alternatively, lower min_machines_running.