Install an instance
This page installs a new instance. Moving an existing instance to a new server is a restore, see
Backups and restores.
Requirements
- A Linux server (Ubuntu or Debian, amd64 or arm64) reachable over SSH as root, with a persistent disk.
1 vCPU and 4 GB of RAM run the whole platform; add more for apps and builds.
- A domain you control, and access to its DNS records.
- Inbound ports 80 and 443 for HTTPS and 22 for administration. If something else already
owns 80 and 443 on that server, plan how its names will be preserved before installing.
- An e-mail address for Let's Encrypt.
- Optional: a Cloudflare API token limited to the instance's zone (Zone → DNS → Edit). With it, xvii
gets wildcard certificates through DNS-01; without it, certificates are issued one by one over HTTP.
Point DNS at the server
Create these records for your domain (shown for example.com and the server 203.0.113.7):
| Name |
Type |
Value |
example.com |
A |
203.0.113.7 |
*.example.com |
A |
203.0.113.7 |
The wildcard covers every service (id.example.com, pages.example.com, …) and user content such as
*.pages.example.com. If you prefer explicit records, create one per service you install, plus
wildcards for pages, apps, tunnel and hooks.
Keep the records DNS only (no Cloudflare proxy) while certificates are first issued. The installer
checks that the names resolve to the server before it continues.
Install the CLI
The installer is part of the xvii CLI. On your laptop:
curl -fsSL https://xvii.network/install.sh | sh
It prints where it put the binary; add that folder to PATH if needed. To choose the folder:
curl -fsSL https://xvii.network/install.sh | XVII_INSTALL_DIR="$HOME/.local/bin" sh
Run the installer
xvii server install root@203.0.113.7
It asks for the domain, the ACME e-mail, the optional Cloudflare token and the first superuser's name,
then over SSH:
- installs PostgreSQL, Caddy and
xvii-node;
- downloads id and home from the release store, checks their SHA-256 and starts them;
- writes Caddy's configuration and obtains certificates;
- prints a one-time link that creates the first passkey.
For automation, pass everything as flags (the token can come from XVII_CLOUDFLARE_TOKEN):
xvii server install root@203.0.113.7 \
--domain example.com --email admin@example.com --user alice --yes
Without USER@HOST it sets up the machine it runs on (as root). Running it again is safe: it converges
to the same state.
The first-user link is a credential. Don't paste it into chats, tickets or logs.
Create your account
Open the link, choose a passkey (Touch ID, Windows Hello, a phone or a security key) and you are signed in
to id as the instance's first superuser. Then open https://example.com: that is home.
Add services
In home → Services, install the services you want from the release store. A sensible order:
- notify, so failures reach you;
- backups, and configure a destination right away;
- pages, env, apps (then add a node, see Nodes);
- domains before attaching custom names;
- anything else: status, errors, analytics, tunnel, hooks, ai, share, config, docs.
mail needs a server whose IP can send mail (outbound port 25, settable reverse DNS); see the
mail guide before installing it.
The same from the server's shell:
xvii-node install pages # the newest version in the store
xvii-node install apps v1.4.2 # a given version
xvii-node status
Check it
xvii login example.com
xvii whoami
curl -fsS https://id.example.com/api/v1/health
Then deploy something small (first site), set up backups and test a restore before
you trust the instance with real data.
What the installer owns
| Path |
What |
/etc/xvii/instance.env |
domain, ACME e-mail, DNS token (root only) |
/etc/xvii/platform.json |
which services run, at which versions, with which settings |
/etc/xvii/<service>/env |
each service's generated settings; change them in home, not by hand |
/var/lib/xvii/<service>/ |
each service's data, including encryption keys |
/var/lib/xvii/releases/ |
the release store: manifests, binaries and checksums |
/usr/local/lib/xvii/<service>/<version>/ |
installed binaries, current points at the running one |
xvii-node.service, xvii-<service>.service |
systemd units |
/etc/caddy/conf.d/xvii.caddy |
the platform's sites in Caddy |
Back up the keys under /var/lib/xvii together with the databases: a database restored without its
sealing key has secrets nobody can open. The backups service does both.
Next: install the CLI on your laptop, or read about updates.