Getting started

Installing the controller

The controller is the panel. Install it once, on Windows, on Linux or in Docker, then finish the configuration in your browser.

Packages

The controller packages carry every agent package and agent build. Once the panel runs, nodes install the agent straight from it, and the panel can update its agents without internet access.

Check a download before installing:

sha256sum -c SHA256SUMS --ignore-missing

Get-FileHash .\ngcp-controller-X.Y.Z-x64.msi -Algorithm SHA256

Install on Windows

With NGCP Setup (recommended)

NGCP-Setup-X.Y.Z.exe installs everything a Windows server needs. Run it as an administrator (SmartScreen warns because it is not code-signed yet) and choose what this server does:

It appears once in Apps / Programs and Features as NGCP; Repair and Uninstall work on both parts. Uninstalling keeps the panel’s database and settings in C:\ProgramData\NGCP.

Unattended:

.\NGCP-Setup-X.Y.Z.exe /quiet                                  # panel + game servers
.\NGCP-Setup-X.Y.Z.exe /quiet InstallAgent=0                   # panel only
.\NGCP-Setup-X.Y.Z.exe /quiet InstallController=0 ControllerUrl=https://panel.example.com EnrollToken=ngcpe_... CaHash=sha256:...

Add /log setup.log for a log file (the enrollment token is never written to it).

With the controller MSI

1. Run ngcp-controller-X.Y.Z-x64.msi as an administrator. SmartScreen warns because the MSI is not code-signed yet.
2. The installer:
   • installs the program to C:\Program Files\NGCP Controller;
   • keeps configuration in C:\ProgramData\NGCP\Controller (readable only by SYSTEM and Administrators);
   • adds the Windows service NGCP Controller (NGCPController);
   • opens TCP 8080 (web) and 8443 (agents) in Windows Firewall.
3. Leave Open the setup page (http://localhost:8080/setup) ticked on the last page and continue with the setup.

For a silent install:

msiexec /i ngcp-controller-X.Y.Z-x64.msi /qn

Install on Linux

# 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

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
     Windows	C:\ProgramData\NGCP\Controller\setup-token.txt
     Linux	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 on Windows creates a PostgreSQL cluster in C:\ProgramData\NGCP\Controller\postgres\data, listening on 127.0.0.1 only (first free port from 5433), run by the service NGCPPostgreSQL as NetworkService with a random password.
   • Built-in on Linux 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: see below.

6. Game servers on this server (shown only when the NGCP agent is installed on the same computer, as with NGCP Setup’s default or 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.

TLS and reverse proxies

The setup offers three TLS modes:

Certificate files are set with NGCP_TLS_CERT_FILE and NGCP_TLS_KEY_FILE. On Linux the files must be readable by the user ngcp. Automatic certificates (ACME / Let’s Encrypt) are not supported yet. The AgentLink port (8443) always uses its own certificates from the panel’s internal CA, whatever you choose here.

Behind a reverse proxy:

• Set TLS mode None and enter the proxy’s https:// URL as the public URL; the session cookie is then always sent with the Secure flag.
• Forward WebSocket upgrades for /ws.
• Allow request bodies of at least 64 MiB (upload chunks), and long timeouts for uploads.
• Tell the controller which proxy addresses to trust for X-Forwarded-For, so sign-in limits and the admin IP allow-list see real client addresses: NGCP_TRUSTED_PROXIES=127.0.0.1/32.
• Do not proxy port 8443; agents need a direct TCP connection to it.
• Finish the setup before you put a proxy on the same machine in front of the panel: requests from the server itself skip the setup token.

controller.env reference

Every setting can come from the environment or from controller.env. The environment wins. The file uses KEY=value lines; # starts a comment.

After changing the file, restart the controller:

sudo systemctl restart ngcp-controller

Restart-Service NGCPController

Files and folders

Without the packages

The bare binaries still work. Create a key, migrate, create an administrator and serve:

export NGCP_MASTER_KEY="$(ngcpctl gen-master-key)"
export NGCP_DATABASE_URL="postgres://ngcp:[email protected]:5432/ngcp"
ngcpctl migrate
ngcpctl create-admin -email [email protected] -username admin
ngcp-controller serve -listen 0.0.0.0:8080 -public-url https://panel.example.com \
  -grpc-listen 0.0.0.0:8443 -grpc-advertise panel.example.com:8443

Keep the master key: everything sealed with it is unreadable without it. See Command line.

Next: add a node.