Fiber node setup for Backr

1. Install and run FNN

Follow Run a Fiber Node. Typical path:

1. Download fnn, fnn-cli, and fnn-migrate from GitHub Releases (match your OS/arch, e.g. fnn_v0.8.0-x86_64-linux-portable.tar.gz on many VPS), or build from the fiber repo.
2. Copy config/testnet/config.yml (or mainnet when you operate there) into your node directory.
3. Start with a strong password in FIBER_SECRET_KEY_PASSWORD:

FIBER_SECRET_KEY_PASSWORD='your-strong-password' RUST_LOG=info ./fnn -c /path/to/config.yml -d /path/to/data-dir

Quick health check (local RPC):

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"node_info","params":[]}' \
  http://127.0.0.1:8227/

For production, run FNN under systemd so it survives reboots. Default RPC in docs is often http://127.0.0.1:8227 — keep it local and put nginx/Caddy + TLS in front for the public URL you paste into Backr.

Proxy tip: if fnn-cli or curl fails with 503 locally, try export NO_PROXY=127.0.0.1,localhost.

2. Keys and the -d data directory

Export a CKB private key with ckb-cli per the official guide. FNN expects ckb/key inside the data directory you pass to -d (e.g. /var/lib/fnn/ckb/key), not only next to the binary. The file must be one line: 64 hex characters, no 0x prefix.

# Example: after export, copy first line only into ckb/key under your -d tree
mkdir -p /var/lib/fnn/ckb
head -n 1 ./exported-key > /var/lib/fnn/ckb/key
chmod 600 /var/lib/fnn/ckb/key

Fund the corresponding testnet address (faucet in Fiber docs), then proceed to peers and channels.

3. Peers, channels, and liquidity

Invoices and send_payment only work when your node has a viable path on the channel graph. Use:

• Connect to peers
• Open a channel
• Basic transfer (prove end-to-end)
• Testnet bootstrap: Connect public nodes
• Stablecoins on testnet: Transfer stablecoins

• Creators need enough inbound capacity so supporters can pay your invoices.
• Supporters need outbound capacity so your node can honor send_payment when Backr triggers checkout or renewal.

If you see routing errors right after opening a channel, wait for gossip to catch up (Fiber docs note this for Failed to build route).

4. Expose JSON-RPC so Backr can call your node

Backr's server POSTs JSON-RPC to the base URL you save (no path after host/port). Examples: https://fiber.example.com, or http://127.0.0.1:8227 only when Backr runs on the same machine as FNN (local dev).

Production pattern: bind RPC to loopback on the VPS, run nginx (or Caddy) with HTTPS on a hostname, proxy to 127.0.0.1:8227, and add firewall + rate limits / allowlists where you can. RPC can move funds—treat it like a signing endpoint; do not leave it wide open without controls.

Optional: same Tailnet as a self-hosted Backr → private URL (e.g. http://100.x.y.z:8227). Hosted Backr (e.g. Vercel) needs a URL reachable from the public internet unless you add a tunnel/proxy you control.

Method reference: Fiber RPC README.

5. Creators — checklist

1. Run FNN with funded wallet and testnet/mainnet config you intend to use.
2. Connect peers and open channels; confirm you can receive (inbound liquidity).
3. Expose a stable HTTPS base URL to your RPC (recommended) or a controlled internal URL if your hosting allows it.
4. In Backr, open Creator → Settings → Basic and paste Your Fiber node JSON-RPC URL. Without it, supporters cannot complete checkout for your tiers.
5. Create tiers and test a small subscription with a second account that has its own FNN.

6. Supporters — checklist

1. Run your own FNN (or one you fully control) with keys and data dir set correctly.
2. Fund the wallet; connect peers; open channels with outbound capacity for payments.
3. Expose RPC the same way as creators (HTTPS + reverse proxy is typical).
4. In Backr, open Dashboard → Settings → Basic and save Your Fiber node JSON-RPC URL. Backr requires this for paying creators; there is no shared custodial patron node in the product model.
5. Visit a creator, choose a tier, and use Support — your node will execute send_payment.

7. What happens on subscribe and renewal

First checkout: Backr (server) asks the creator's FNN for a tier invoice via new_invoice, then asks your FNN to send_payment. Your browser only triggers the request; it does not sign Fiber calls.

If the node returns Created or Inflight, the Backr server keeps calling get_payment until the payment reaches Success or Failed (or until a configurable timeout — see below).

Renewals: the app's cron job repeats a similar flow on the schedule your host configures. If your Fiber URL is missing or your node cannot pay, that renewal may be skipped until you fix liquidity or settings.

8. Server trust, RPC safety, and optional payment tuning

Treat your JSON-RPC URL like a signing surface: use HTTPS, firewalls, and allowlists where you can (see section 4). Backr only stores the URL you provide and calls it from the server.

Private last hops: set hop_hints via FIBER_SEND_PAYMENT_HOP_HINTS or sendPaymentOptions on POST /api/fiber/pay (Fiber RPC README).

Tuning env vars are listed in .env.example (poll interval, max wait, fee caps). FIBER_INVOICE_API_ENABLED gates the invoice-only debug route (off by default; requires sign-in when on).

9. Troubleshooting

• Creator not set up / payment failed — ensure the creator saved a reachable URL and FNN is running; check nginx/TLS and firewall.
• Supporter must add Fiber URL — save the URL in Dashboard → Basic; verify node_info via curl from another machine hits your public URL.
• Route / payment errors — wait for channel graph sync; confirm channel is ChannelReady; check balances and peer connectivity (Fiber docs). For private last hops, configure hop_hints (env or sendPaymentOptions).
• Checkout times out while Fiber still settling — increase FIBER_PAYMENT_MAX_WAIT_MS and/or FIBER_SEND_PAYMENT_TIMEOUT_SECONDS; ensure your host allows long enough function duration for /api/fiber/pay (Backr sets a high maxDuration for this route).
• Wrong key path — key file must live under the same -d directory as ckb/key, be a single hex line, and match the password you set for FNN.