Deploying npubcash-server with fly.io: A Step-by-Step Guide

Disclaimer: Beware, there be dragons... Deploying your own version of npubcash-server is highly experimental. Do not use this in production yet. If you do deploy it, please make sure to leave your feedback with me.

Prerequisites

Before we dive in, you'll need a few things:

1. Blink API Key: npubcash-server uses Blink API for payment callbacks. If you don’t have a Blink account yet, sign up here.
2. Postgres: npubcash-server utilizes a Postgres database for storage.
3. fly.io Account and flyctl: While you can deploy npubcash-server anywhere, this guide focuses on fly.io and its CLI tool, flyctl.

Setup

Step 1: Clone the Repository

First, clone the npubcash-server repository, specifically the migrations branch, as it contains the necessary deployment scripts. Don’t forget to clone all submodules recursively.

git clone -b migrations --recurse-submodules https://github.com/cashubtc/npubcash-server.git
cd npubcash-server

Step 2: Create fly.toml Configuration

Next, create your fly.toml file to configure your deployment.

nvim fly.toml

Here's a sample configuration. Adjust the environment variables to match your setup:

app = "npubcash-server"
primary_region = "ams"

[build]

[http_service]
internal_port = 8000
force_https = true
auto_stop_machines = true
auto_start_machines = true
min_machines_running = 0
processes = ["app"]

[[vm]]
memory = "512mb"
cpu_kind = "shared"
cpus = 1

[env]
NODE_ENV = "production"
PGUSER = "<Postgres Username>"
PGPASSWORD = "<Postgres Password>"
PGHOST = "<Postgres Hostname>"
PGDATABASE = "<Postgres Database>"
PGPORT = "<Postgres Port>"
MINTURL = "<Default Mint URL>"
BLINK_API_KEY = "<Blink API Key>"
BLINK_WALLET_ID = "<Blink Wallet ID>"
BLINK_URL = "https://api.blink.sv/graphql"
HOSTNAME = "<Hostname of npubcash-server including protocol>"
JWT_SECRET = "<Secret used for username purchases>"
ZAP_SECRET_KEY = "<Nostr hex secret key for zap provider>"
LNURL_MIN_AMOUNT = "<min amount in msats>"
LNURL_MAX_AMOUNT = "<max amount in msats>"
NPC_SERVER_URL = "<Hostname of npubcash-server including protocol>"

Note: fly.io offers additional security for sensitive environment variables through secrets, which are encrypted and never exposed directly. Consider using secrets for sensitive data like your Blink or Nostr key. Learn more here.

Deploying

With your configuration ready, it’s time to deploy!

fly launch

When prompted, choose to use the existing fly.toml file by inputting y. Fly.io might suggest deploying a Postgres instance, but since we're using an external Postgres instance, adjust the settings as needed through their web interface. Watch the build logs in your terminal, and once completed, your instance of npubcash-server is live. Congrats!

Setting Up a Custom Domain

To fully utilize npubcash-server as an LNURL server, you’ll need a custom domain. Here’s how to set it up:

1. Get the IP Address: Use flyctl to list your IP addresses.

   fly ips list
   

   Copy the IPv4 and IPv6 addresses.

2. Create DNS Records: Set up an A record with your domain provider using the IPv4 address and a AAAA record using the IPv6 address.

3. Request an SSL Certificate: For encrypted traffic, request a Let’s Encrypt certificate.

   fly certs add <your domain name>
   

Note: DNS propagation can take some time. Ensure your machine is running and try connecting to the domain once the DNS records are updated. Fly.io will verify the DNS setup when traffic starts coming in.

Wrapping up

That is it... Hopefully by now your very own instance of npubcash-server is running and reachable on your own domain. If you got this far, please reach out to me and let me know. Now please go ahead and try to break it. If you do, please open an issue so that I can fix it :)