Fly.io

RequirementsCopy Anchor Link

TopologyCopy Anchor Link

General rules for ports and the node channel certificate: Ports, reverse proxy, and trusted proxies.

MethodsCopy Anchor Link

App creation, image deployment, and upgrades use flyctl; the other steps can be done in the Dashboard, with flyctl as the equivalent.

1. Create the appCopy Anchor Link

fly apps create edgeweir-console --org <organization>

App names are globally unique and set the default host name <app name>.fly.dev.

2. Write fly.tomlCopy Anchor Link

Create fly.toml in an empty directory. Adjust app, primary_region, the image tag, and the app name in the URLs.

app = "edgeweir-console"
primary_region = "nrt"

[build]
  image = "ghcr.io/marvinli001/edgeweir:20260929-a1b2c3d"

[env]
  EDGEWEIR_PUBLIC_URL = "https://edgeweir-console.fly.dev"
  EDGEWEIR_NODE_API_URL = "https://edgeweir-console.fly.dev:8443"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = "off"
  auto_start_machines = true
  min_machines_running = 1

  [[http_service.checks]]
    grace_period = "30s"
    interval = "15s"
    timeout = "5s"
    method = "GET"
    path = "/healthz"

[[services]]
  internal_port = 8443
  protocol = "tcp"
  auto_stop_machines = "off"
  auto_start_machines = true
  min_machines_running = 1

  [[services.ports]]
    port = 8443

  [[services.tcp_checks]]
    grace_period = "30s"
    interval = "15s"
    timeout = "2s"

[[vm]]
  size = "shared-cpu-1x"
  memory = "1gb"

3. Set secretsCopy Anchor Link

1. Generate the master key locally:

   Copy Text

   umask 077
   openssl rand -base64 32 > edgeweir-master-key

2. Dashboard → edgeweir-console → Secrets, add:

   Secret	Value
   EDGEWEIR_MASTER_KEY	Contents of edgeweir-master-key, as is
   DATABASE_URL	postgres://edgeweir:<password>@<host>:5432/edgeweir

3. Keep them staged; do not click Deploy Secrets. The secrets take effect with the deployment in step 4.

flyctl:

fly secrets set --stage \
  EDGEWEIR_MASTER_KEY="$(cat edgeweir-master-key)" \
  DATABASE_URL='postgres://edgeweir:<password>@<host>:5432/edgeweir'

Fly.io does not reveal secret values; store edgeweir-master-key offline, apart from database backups; see Backup and recovery.

4. DeployCopy Anchor Link

In the directory that holds fly.toml:

fly deploy --ha=false

--ha=false creates a single Machine. Because [[services]] has a non-HTTP port such as 8443, the first deployment asks Would you like to allocate dedicated ipv4 and ipv6 addresses now?: answer y to get a dedicated IPv4 (USD 2 a month) and a dedicated IPv6, and no shared IPv4. Answering n, or deploying without a terminal, allocates no address at all and the deployment still completes; add them in step 5.

5. Check the public addressesCopy Anchor Link

fly ips list

Expected: one dedicated IPv4 (v4) and one dedicated IPv6 (v6), no shared IPv4 (shared_v4).

edgeweir-console.fly.dev resolves to the dedicated addresses once DNS caches expire. Do not go back to a shared IPv4: it does not forward 8443.

6. Run setupCopy Anchor Link

An uninitialized console logs the same setup token on every start.

1. Dashboard → edgeweir-console → Logs & Errors → Search logs in Grafana, query "first-run setup". Logs are kept for 7 days.
2. The line's setupToken field is the setup token; its url field is the setup wizard address (<EDGEWEIR_PUBLIC_URL>/setup).
3. Open the wizard and enter the setup token; see Quick start.

flyctl:

fly logs --no-tail | grep setupToken

fly logs --no-tail returns only recent logs; if the line is missing, run fly apps restart edgeweir-console and read it again.

VariablesCopy Anchor Link

A secret takes precedence over an [env] entry with the same name. ROLE, HOST, PORT, and NODE_API_PORT keep the image defaults all, 0.0.0.0, 3000, and 8443, which match internal_port. All variables: Environment variables.

VerificationCopy Anchor Link

openssl s_client -connect edgeweir-console.fly.dev:8443 -servername edgeweir-console.fly.dev </dev/null 2>/dev/null \
  | openssl x509 -noout -text | grep -E 'Issuer:|Subject:|DNS:'

Expected:

        Issuer: CN=Edgeweir Node Channel CA, O=Edgeweir
        Subject: CN=edgeweir-node-api, O=Edgeweir
                DNS:localhost, IP Address:127.0.0.1, IP Address:0:0:0:0:0:0:0:1, DNS:<Machine host name>, DNS:edgeweir-console.fly.dev

Any other issuer means a device in the path terminates TLS.

Custom domainsCopy Anchor Link

Complete this before enrolling nodes.

1. Dashboard → edgeweir-console → Certificates, add console.example.com; create the A (dedicated IPv4) and AAAA records shown there in DNS. flyctl: fly certs add console.example.com.

2. Change [env] in fly.toml:

   Copy Text

   [env]
     EDGEWEIR_PUBLIC_URL = "https://console.example.com"
     EDGEWEIR_NODE_API_URL = "https://console.example.com:8443"

   When a URL is saved under "Node channel" in System settings, it wins over EDGEWEIR_NODE_API_URL: change it there to https://console.example.com:8443. Port 8443 needs no fly certs add, but the name must resolve straight to the dedicated addresses: turn the proxy off (DNS only) in Cloudflare or similar DNS, since Cloudflare's proxy also handles HTTPS on port 8443 and would terminate TLS.

3. Deploy:

   Copy Text

   fly deploy

4. Verify: run the curl and openssl commands from Verification against console.example.com.

Changing the node channel address for enrolled nodes: Node channel URL and certificate.

UpgradeCopy Anchor Link

1. Back up the database; see Backup and recovery.

2. Change [build] image in fly.toml to the new tag.

3. Deploy:

   Copy Text

   fly deploy

4. Verify:

   Copy Text

   curl -fsS https://edgeweir-console.fly.dev/healthz

   Expected: version is the new tag.

Migrations, signature verification, and rollback: Versions, upgrades, and rollback.

LimitsCopy Anchor Link