> For the complete documentation index, see [llms.txt](https://docs.bosonnetwork.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bosonnetwork.io/deploy-a-node/planning.md). # Planning a Deployment This page helps you decide what kind of node to run and what it needs before you install anything. It covers requirements and trade-offs only; the step-by-step procedures are in [Installation](/deploy-a-node/installation.md). *** ## Choose a deployment Boson supports three deployment scenarios. Pick the one that matches what the node is for. | | Bootstrap node | Personal or small-community super node | Public super node | | ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------- | | **What it runs** | A DHT node only | The Director, a DHT node, and the four layer-2 services | The same super node, behind PostgreSQL, nginx and a real certificate | | **Who it is for** | Operators who want to strengthen DHT reachability or seed a private network | You, your devices, or a small group you know | A node other people rely on | | **Installed with** | The `boson-bootstrap` DEB package | The `boson` DEB package | The one-command setup tool, `install-super-node.sh` | | **Reachable as** | An IP address and UDP port | An IP address and ports, self-signed TLS | `https://your.domain/`, a publicly trusted certificate | | **Database** | SQLite | SQLite | PostgreSQL | | **Reverse proxy** | None | None | nginx | | **Domain name** | Not needed | Not needed | Required | The two super node deployments are configured differently **by design**, and neither is a degraded version of the other. The DEB package is built to work on a fresh machine with nothing else installed: it uses SQLite, binds every service to all interfaces, and generates its own certificate. A public node needs a real certificate, a domain, and a reverse proxy that keeps internal ports off the Internet, and at that point several packaged defaults become the wrong answer. That is what the setup tool changes. {% hint style="info" %} **You do not need a super node to use Boson.** Apps, devices behind NAT and browsers connect to super nodes as clients. If you only want to use the network, pick a node from the [public node list](https://github.com/bosonnetwork/public-boson-nodes). If you are building an application, the SDKs are on Maven Central and need no local install; see [Build Applications](/build-applications/build-apps.md). {% endhint %} *** ## Hardware These figures are starting points. A node's real load depends on its users, how much they store, and how much traffic it relays. | | Minimum | Recommended | | ----------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------- | | **Bootstrap node** | 1 vCPU, 512 MB RAM, 8 GB disk | 1 vCPU, 1 GB RAM, 10 GB disk | | **Personal / small-community super node** | 1 vCPU, 1 GB RAM, 10 GB disk | 2 vCPU, 2 GB RAM, 20 GB disk or more | | **Public super node** | 2 vCPU, 2 GB RAM, 20 GB disk | 4 dedicated vCPU, 8 GB RAM, 100 GB disk, plus a separate volume for Ion Store objects | The public setup tool asks you to confirm before continuing on a server with less than 4 GB of RAM or 20 GB of disk. A few things drive these numbers and are worth understanding before you buy a server: * **The DHT cost does not scale down with users.** The shipped node configuration sizes the routing table and lookup concurrency for a well-connected node, so a node with ten users and one with three thousand pay a similar fixed DHT cost. That floor is why a public node is sized at four cores. * **Prefer dedicated vCPUs for a public node.** Every DHT packet is encrypted and signed. Burstable instances throttle exactly when DHT traffic spikes. * **Disk grows with Ion Store.** Each user's objects count against their plan quota and expire after the plan's object lifetime, so storage is a rolling window rather than an ever-growing archive. Budget separately for objects cached on behalf of federated peers. * **Bandwidth can cost more than the server.** A super node relays traffic: Active Proxy carries proxied connections both ways, and Ion Store downloads are free to anyone who has an object's id. On a provider that meters egress, check the egress price first. Boson runs everything in a single JVM process. The package sizes the heap at 50% of RAM, adjustable in `/etc/default/boson`; see [Operations](/operate-a-node/operations.md) for tuning. *** ## Network ### A publicly reachable address Other nodes must be able to reach a bootstrap node or super node directly, so it needs a **public IPv4 address that is reachable without address translation of its source port and address**. * **UDP 39001 cannot be proxied.** The DHT speaks UDP directly to peers; it cannot sit behind an HTTP proxy, a CDN, or a load balancer. * **A NAT that rewrites source addresses does not work.** A 1:1 NAT, as used by many cloud providers, does work, provided the node announces its public address rather than its private one. [Installation](/deploy-a-node/installation.md) covers how each scenario handles that. * **A home connection** can host a personal node only if it has a stable public IP (or dynamic DNS) and you forward every port listed below. Carrier-grade NAT, common on mobile and some residential connections, cannot host a node at all. * **IPv6** is supported alongside IPv4 on the same port. ### Ports Open these ports to the Internet for the scenario you chose. **Bootstrap node** | Port | Protocol | Purpose | | ----- | -------- | ------- | | 39001 | UDP | DHT | **Personal or small-community super node** - every service is reached directly, each terminating its own TLS: | Port | Protocol | Purpose | | ------------------------ | -------- | ----------------------------------------------------------- | | 39001 | UDP | DHT | | 9000 | TCP | Director: REST API, admin dashboard, user portal, home page | | 9001 | TCP | Web Gateway | | 9080 | TCP | Ion Store | | 9083 | TCP | Photon Messaging (MQTTS) | | 9084 | TCP | Photon Messaging federation | | 9090 | TCP | Active Proxy control | | 10000-10099, 32768-65535 | TCP | Active Proxy mapped ports, one per proxied connection | **Public super node** - only these are public; every other service listens on loopback behind nginx: | Port | Protocol | Purpose | | ----- | ----------- | ------------------------------------------------------ | | 80 | TCP | HTTP redirect and certificate challenges | | 443 | TCP | APIs, consoles, home page, and Active Proxy sessions | | 9083 | TCP | Photon Messaging (MQTTS) | | 9090 | TCP | Active Proxy control | | 39001 | UDP | DHT | | 53 | TCP and UDP | Only if the node serves its own DNS zone with PowerDNS | Provider-level firewalls (security groups, cloud firewalls) are yours to open in every scenario. The public setup tool can configure a host firewall for you. *** ## DNS and names **Bootstrap and personal nodes** need no domain. Peers and clients reach them by IP address. If the server's public IP has a reverse DNS name, the setup wizard uses it in the endpoints the node announces. **A public super node** needs a domain you control. Choose the name the node is known by: * A domain used only for the node: use it directly, for example `example.com`. * A domain that also hosts a website: give the node its own name, for example `node.example.com`. Two `A` records, both pointing at the server, cover everything: ``` node.example.com. A 203.0.113.10 *.node.example.com. A 203.0.113.10 ``` | Name | Serves | | ---------------------- | ----------------------------------------------------------------------------------------------- | | `node.example.com` | The APIs, the admin dashboard and user portal, and the service endpoints announced into the DHT | | `www.node.example.com` | The node's home page. Reserved, so it cannot be the node's own name | | `*.node.example.com` | Active Proxy sessions, one name per connected device | Plan for three constraints: * **The wildcard record is required.** An Active Proxy session name is not known until the session opens, so a name that has not been handed out yet must already resolve to the node. * **Leave both records unproxied (DNS only).** The node's name carries the endpoints peers connect to directly and the addresses its rate limits are keyed on; a CDN proxy in front of it breaks both. Only the `www` home page may safely sit behind a CDN. * **If your DNS provider cannot store a `*` record,** run the node's own DNS server instead (PowerDNS on the same host) and delegate the zone to it with `NS` and glue records at your registrar. *** ## TLS certificates | Scenario | Certificate | What clients see | | ------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- | | Bootstrap node | None. DHT traffic is encrypted and signed at the protocol level | - | | Personal super node | Self-signed, generated at startup and bound to the node's identity | Boson clients verify it by pinning the node's identity. Browsers show a warning | | Public super node | A wildcard certificate from Let's Encrypt, or one you already have | A publicly trusted certificate | A public node needs a **wildcard** certificate, because every Active Proxy session is a name under the domain. Let's Encrypt issues wildcards only through a DNS-01 challenge, so plan which way you will answer it: * **A certbot DNS plugin for your provider** (recommended). Renews unattended. Needs an API token for your zone. Cloudflare, Route 53, DigitalOcean, Linode, OVH, deSEC, netcup and others are supported. * **Manual.** You add a `TXT` record by hand. **This cannot renew unattended**, so it suits a trial, not a node people depend on. * **PowerDNS on the node.** The challenge is answered locally; nothing to configure at a provider. * **An existing wildcard certificate** that covers both the node's name and `*.` under it. *** ## Database | Scenario | Database | | ------------------- | ------------------------------------------------------------------------ | | Bootstrap node | SQLite, embedded | | Personal super node | SQLite, one file per component, no server to install | | Public super node | PostgreSQL 15 or later: one `boson` database with a schema per component | SQLite is the right choice when a node serves a handful of users. A public node should use PostgreSQL for concurrent writes and standard backups; the setup tool installs and tunes it. See [Databases](/configure-a-node/databases.md). *** ## Reverse proxy Bootstrap and personal super nodes run **without** a reverse proxy: each HTTP service listens on its own port and terminates its own TLS. A public super node runs **nginx** in front of every HTTP service, for three reasons: 1. **TLS terminates once**, with the node's real certificate. 2. **Internal ports stay off the Internet.** The Director, Web Gateway, Ion Store and the Active Proxy mapped port range listen on loopback only. 3. **Active Proxy sessions get names.** A device's service is reached at `https://.node.example.com` instead of an IP address and port number. Name access needs nginx from **nginx.org**, with its `njs` module; the njs module in Ubuntu's own packages lacks a feature it depends on. The setup tool installs the right one. MQTTS (9083) and Active Proxy control (9090) are not HTTP, so they remain directly exposed. *** ## Operating system | Package | Platforms | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DEB (bootstrap and super node) | Ubuntu LTS (tested) and other Debian-based distributions, `amd64` and `arm64` | | Public setup tool | A fresh Ubuntu 24.04 or 26.04 LTS, or Debian 12 or 13, with `root` or `sudo` and `python3` | | ZIP archive | macOS (Apple Silicon and Intel), Linux (`x86_64` and `aarch64`), Windows (`x86_64`). Suited to trying Boson out or development; it has no service manager integration | Every package includes its own Java runtime, so there is nothing else to install. *** ## Plan your backups now A node's identity is a set of private keys generated at install time. **They cannot be regenerated**: a node that loses them becomes a different node, and every peer, bootstrap list and federation partner that knew the old one loses track of it. * **All scenarios:** back up `/etc/boson` (or `/etc/boson/bootstrap` for a bootstrap node) as soon as the node is installed. * **Public super node:** also back up `/var/lib/boson-setup/answers`, which holds the generated database passwords and API keys, and the PostgreSQL database. See [Operations](/operate-a-node/operations.md) for the full backup procedure. *** ## Before you install **Bootstrap node** * [ ] A server with a public IPv4 address * [ ] UDP 39001 open **Personal or small-community super node** * [ ] A server with a public IPv4 address, or a home connection with port forwarding * [ ] The ports above open **Public super node** * [ ] A fresh Ubuntu LTS or Debian server, sized per the table above, with a static public IPv4 address * [ ] A domain you control, with the apex and wildcard `A` records in place and unproxied * [ ] A way to answer the DNS-01 challenge: a provider API token, or PowerDNS on the node * [ ] Ports 80, 443, 9083, 9090 and UDP 39001 open at your provider Ready? Continue to [Installation](/deploy-a-node/installation.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bosonnetwork.io/deploy-a-node/planning.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.