Linux

Installing on Linux

Install the controller (the panel) on Debian, Ubuntu or the RHEL family (amd64 or arm64), or in Docker, then finish the configuration in your browser. For a new server or VM, use the Linux appliance instead: Ubuntu 24.04 with NGCP already on it.

Before you start

Download the package for your system (all files: Packages) and check it against SHA256SUMS:

sha256sum -c SHA256SUMS --ignore-missing

What has been tested so far is listed in Requirements.

Install the package

# Debian / Ubuntu (pulls in PostgreSQL)
sudo apt install ./ngcp-controller_X.Y.Z_amd64.deb

# RHEL / Rocky / Alma (pulls in postgresql-server)
sudo dnf install ./ngcp-controller-X.Y.Z-1.x86_64.rpm

The package:

• creates the system user ngcp and the systemd unit ngcp-controller (hardened: read-only system, writable only /etc/ngcp and /var/lib/ngcp-controller);
• starts PostgreSQL if it is installed locally and creates the role and database ngcp, reached over the Unix socket with peer authentication (no password anywhere);
• puts the configuration in /etc/ngcp/controller.env (mode 0600, owner ngcp).

If a firewall is active, open TCP 8080 and 8443, for example:

sudo ufw allow 8080/tcp
sudo ufw allow 8443/tcp
# or
sudo firewall-cmd --permanent --add-port=8080/tcp --add-port=8443/tcp && sudo firewall-cmd --reload

Then finish the setup in a browser.

Install with Docker

The repository’s deploy/docker folder holds an image definition and a compose file that runs the controller with PostgreSQL 16. This setup has not yet been run on a Docker host in testing.

cd deploy/docker
echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" > .env
docker compose up -d --build

The container starts in setup mode with its configuration on the volume /etc/ngcp. In the setup choose Existing database and enter:

postgres://ngcp:<POSTGRES_PASSWORD>@db:5432/ngcp?sslmode=disable

Agents are not run in Docker: install them on the game-server machines.

Finish the setup in a browser

Until the setup is done the controller serves only the setup page and its API.

1. Open http://<server>:8080/setup.

   • On the server itself no token is needed.
   • From another computer the page asks for the setup token:

     Install	Where the token is
     Package	sudo ngcp-controller setup-url prints the address with the token (or sudo cat /etc/ngcp/setup-token.txt)
     Docker	docker compose exec controller cat /etc/ngcp/setup-token.txt

2. Database: Built-in or Existing.

   • Built-in uses the local database the package prepared.
   • Existing: a URL such as postgres://ngcp:[email protected]:5432/ngcp. The page tests the connection first.

3. Administrator: user name, e-mail and password of the first SuperAdmin. Turn on two-factor sign-in right after the first sign-in.

4. Address: the public URL browsers and nodes use, for example https://panel.example.com or http://203.0.113.10:8080, and, if different, the agent address (host:8443). By default the agent address is the public URL’s host name with port 8443. Nodes must be able to resolve and reach both.

5. TLS: None (trusted network, or TLS ends at a reverse proxy), Certificate files (must be readable by the user ngcp) or Self-signed (testing; browsers warn). See TLS and reverse proxies.

6. Game servers on this server (shown only when the NGCP agent is installed on the same computer, as with the appliance’s Panel and game servers): leave This server runs game servers too ticked, optionally with a node name (default: the computer name). The setup leaves a one-time join file for the agent (local-node.json in the configuration folder, valid for 24 hours); the agent joins within seconds, deletes it and appears under Nodes in the datacenter Default.

7. Finish. The controller writes its configuration and a new master key, creates the database schema, the SuperAdmin and a datacenter named Default, and switches to normal operation without a restart. Sign in at the public URL.

The setup token is deleted when the setup finishes, and the setup API answers 404 afterwards. If the setup fails halfway you can run it again; it keeps what it already created.

Files and folders

Settings are in /etc/ngcp/controller.env; see the controller.env reference. Running, upgrading and removing the panel on Linux: Linux notes.

Next: add a Linux node.