Installation

Debian / Ubuntu (apt)

One line on the server does everything — adds the signed APT repository, fetches anything missing (curl, gpg), and installs the package:

curl -fsSL https://apt.xcon-db.com/install.sh | sudo sh

The script refuses to run anywhere but Debian/Ubuntu — pasting it into your laptop's terminal by mistake just prints where to run it. It is safe to re-run, and upgrades keep coming through plain apt upgrade afterwards.

Prefer to see every step? The script does exactly this, and you can do it by hand instead:

# trust the repository signing key
curl -fsSL https://apt.xcon-db.com/KEY.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/xcon-db.gpg

# add the repository
echo "deb [signed-by=/usr/share/keyrings/xcon-db.gpg] https://apt.xcon-db.com stable main" \
  | sudo tee /etc/apt/sources.list.d/xcon-db.list

sudo apt update
sudo apt install xcon-db

The package installs the xcon-db-server binary, a xcondb system user, and a systemd service that starts immediately. On a fresh install there is no config yet, so the node comes up in setup mode and waits — nothing is stored until you finish the wizard. The installer prints where to go and the one-time key to get in:

xcon-db installed. Finish setup in your browser:

    http://<this-server-ip>:8086/
    setup key:  T43-PAA-8TYC

systemctl status xcon-db        # active, in first-run setup

First-run setup wizard

The node with no config serves a one-time setup wizard on port 8086 instead of the console. Because most installs are on a remote machine, it is reachable over the network — open http://<server>:8086/ in your browser and enter the setup key the installer printed.

The wizard has no login of its own — it is the thing that sets the admin password — so that one-time key guards it while it is exposed. The key is unambiguous uppercase (XXX-XXX-XXXX) so it types cleanly from a server console; it also lives in /etc/xcon-db/setup-token (root/xcondb only) and is deleted the moment setup completes.

• Skip the typing: open the full link the installer also prints, http://<server>:8086/?key=T43-PAA-8TYC, and you go straight in.
• Local only? From loopback the key is not required, so an SSH tunnel (ssh -L 8086:127.0.0.1:8086 you@server, then http://127.0.0.1:8086) reaches the wizard without it.

The wizard has four steps, each with what it needs and nothing more:

1. Data — the directory where the node keeps its databases, WAL and logs (default /var/lib/xcon-db-server). A Test writable button confirms it before you continue.
2. Network — the pg-wire listen address (the database port every PostgreSQL driver speaks, default :5432) and the console address (this web UI — it stays on the port you are already looking at).
3. Admin — the admin user and password. The node guarantees this user exists at every start (the postgres/sa pattern); every database and database user is created later over SQL as this admin.
4. Finish — the wizard writes the config to /etc/xcon-db/xcon-db.toml, deletes the setup key, and the node restarts into normal operation. The console returns on the same address, now a login.

After this, the config file is the single source of truth, exactly as if you had written it by hand — the wizard is just the first thing that writes it. To reconfigure later, edit the TOML and restart the service.

Other platforms

xcon-db is a single static binary with no runtime dependencies. Where apt is not available, run it directly:

# fetch the binary for your platform, then:
xcon-db-server -sample-config > xcon-db.toml
# edit xcon-db.toml: set root and the listen addresses (no credentials in here)
xcon-db-server -config xcon-db.toml
# create the first admin (password on stdin, never argv):
printf '%s' 'secret' | xcon-db-server -config xcon-db.toml -reset-admin xcon

Started with a -config path that does not exist, the binary offers the same setup wizard on -setup-listen (default 0.0.0.0:8086). It generates a setup key and logs it — read it from the journal (journalctl -u xcon-db) or from setup-token beside the config — then open http://<host>:8086/?key=…. With a config present it skips all this and boots straight into the node. See Configuration for every key.

Upgrading

sudo apt update && sudo apt install --only-upgrade xcon-db

The config file and data directory are left untouched; what you installed keeps running across upgrades.