Installing NetEnds | NetEnds docs

Overview

You install NetEnds from a release NetEnds sends you. After you request it, a person at NetEnds emails you:

Private download links for two files — the platform, and the Gia package, which is by far the larger because it carries the model.
The SHA-256 checksum of each file.
The release public key, netends-release.pub, printed at the end of the email with its fingerprint.
A one-paste installer that does everything below for you.

There are two ways to install, and both end in the same place:

Quick install — paste the installer from the email on a host that can reach the download server, and run one command.
Step by step — download the files yourself, move them to the host by any means, and run the installer inside them. This is the route for an air-gapped host.

Either way, NetEnds installs to /opt/netends, verifies the files before anything is loaded into Docker, and is safe to run again to upgrade.

Set up backups on day one — see Backup & restore, especially the encryption-key escrow step. Losing that key is the one thing a backup cannot recover from.

Prerequisites

Host — Linux x86_64, bare metal or VM. See System requirements & sizing for profiles, and for what Gia adds.
Docker — Docker Engine 24 or newer with the Compose v2 plugin (docker compose version must work). The installer does not install Docker for you.
Standard tools — bash, curl, tar, sha256sum, openssl and zstd. The quick installer names any that are missing and the package to install.
Administrator rights — run as root, or as a user who may use sudo.
Free disk space — the release email states how much the install needs. The quick installer checks it before downloading anything.
Network position — the host must reach your nodes (SSH, SNMP, vendor APIs), and your nodes must be able to send syslog, flows and traps to the host.
Nothing else to install. The database, event store, ingest pipeline, Gia’s model server and the Lab runtime all ship inside the release.

Ports

Port	Protocol	Purpose	Exposure
443	TCP	Web UI and API (HTTPS)	Public
80	TCP	Redirects to HTTPS; answers `/health` for checks on the host	Public
514	UDP and TCP	Syslog ingest	Public
2055	UDP	NetFlow v5/v9	Public
4739	UDP	IPFIX	Public
6343	UDP	sFlow	Public
162	UDP	SNMP traps	Public
8000 / 5432 / 6379 / 8123 / 9000	TCP	Backend, database, cache, event store	Loopback only

Open the public rows in your firewall — 443 above all, since port 80 only sends browsers there. The loopback-only rows listen on the host’s loopback address only and need nothing.

Quick install

On the Linux host:

Paste the whole installer block from the email into a terminal and press Enter. It saves the installer as netends-install.sh and checks that it arrived intact; the last line must say netends-install.sh: OK.
Run it:
```
bash netends-install.sh
```

It checks the server first — Linux x86_64, Docker Engine 24 or newer with the Compose plugin, the tools it needs, administrator rights and free disk space — and stops with the fix named if anything is missing. Then it downloads both files, checks each one against the SHA-256 checksum it carries from the email, writes out the release public key it carries and checks that key’s fingerprint, unpacks the files and runs the installer shipped inside the release, which verifies the release signature before it loads anything into Docker.

One progress bar covers the whole run. If it stops, it names the step, the reason and its log. Fix what it names and run the same command again: finished downloads are kept and checked again, not fetched twice.

To install the platform without Gia, use the installer’s platform-only option, which bash netends-install.sh --help lists. You can add Gia later by running the installer again without that option.

When it finishes, it prints the address to open, the certificate fingerprint to check, and how to sign in. The download directory is no longer needed after that, and the installer prints the command that removes it.

Step by step

This is the same install by hand, for a host that cannot reach the download server.

Download both files from the links in the email, on any machine that can reach them. The links support resuming an interrupted download:
```
curl -C - -O <link-from-the-email>
```
Move the files to the host by any means — USB media, an internal mirror — and check each one. The value printed must match the checksum in the email:
```
sha256sum <file>
```
Unpack both files side by side in one directory:
```
tar -xf <file>
```
Save the release public key from the end of the email as netends-release.pub in that same directory — beside the unpacked directories, not inside them. The installer refuses to continue without it rather than install unverified files.
Change into the unpacked platform directory, netends-airgap-core-<version>, and run the installer:
```
sudo ./install_offline.sh
```
It verifies both unpacked files with the key — the checksums first, then the signature — loads the images, and installs Gia along with the platform because its files sit beside the platform’s. See Verifying your download to run the same checks yourself first.

To install the platform alone, do not unpack the Gia file in step 3. To add Gia later, unpack it beside the platform directory of the release you are running and run sudo ./install_offline.sh again from that directory.

What the installer does

Both routes run the same installer. It:

Lays out /opt/netends: the Compose files, the web-server and ingest configuration, the certificate directory and the certificate tool netends-tls.
Writes /opt/netends/.env (permissions 600) with freshly generated secrets — the database password, the JWT secret, the event-store password, and the ENCRYPTION_KEY that protects your device credentials at rest.
Generates a self-signed HTTPS certificate for the host when /opt/netends/certs/ holds none, and prints its SHA-256 fingerprint at the end.
Checks whether Docker can hand a GPU to a container and, when it can, runs Gia on the GPU. The decision is recorded in .env, so it survives restarts and upgrades.
Records the installation’s identity in /var/lib/netends/install-state/install-identity, outside Docker, so a reinstall on the same host keeps the same Installation ID.
Starts the stack and waits for it to answer, over HTTP on the host and then over HTTPS. Database migrations apply themselves on the first start, so it can take a few minutes.

On a fresh install the offline installer asks for an initial admin password — press Enter to use the documented day-one password — while the quick installer always uses the day-one password. If you pass --admin-password, avoid a $ in the value — Compose’s environment handling would corrupt it, so the installer refuses it up front rather than create the account with a password other than the one you typed.

Confirm Gia is using the GPU

The installer prints its GPU decision, with the reason, as GPU capability: yes, no or unknown. To confirm on a running install, ask Gia one question first — the model loads on the first question — then:

cd /opt/netends
docker compose exec ollama ollama ps

The PROCESSOR column must read 100% GPU. A split between CPU and GPU means the card is too small to hold the whole model.

To stand a GPU host down deliberately, set NETENDS_GPU_MODE=off in /opt/netends/.env and run the installer again; on forces the GPU, and auto (the default) follows the check.

Upgrades by reinstalling

Running the installer from a newer release upgrades the install in place. Updating NetEnds describes the updater, which adds a health check and automatic rollback. When you upgrade by reinstalling, this is precisely what changes:

Your /opt/netends/.env is preserved — secrets are never rotated. Only the image coordinates and the measured GPU facts are rewritten, and a timestamped .env.bak.<time> copy is taken first. That copy holds ENCRYPTION_KEY, so treat it like the key.
The Compose files are replaced — they are the release.
Files you are expected to edit — nginx.release.conf and the syslog and flow collector configuration — are not overwritten once you have changed them. The version the release ships is parked beside each as a .dist file and named in the output. Reconcile with diff -u <file> <file>.dist.
A certificate already in /opt/netends/certs/ is never replaced.

Migrations apply automatically when the new backend starts.

Verify the install

Open https://<host>/. Plain http://<host>/ redirects there.

Your browser warns about the certificate until you install one it trusts, because the installer generated a self-signed one for this host. Before you accept the warning, compare the fingerprint the browser shows with the one the installer printed. Running sudo /opt/netends/netends-tls show prints it again at any time.
Sign in as admin with the password netends — the documented day-one password — or with the password you set during the install.

The first login requires setting a new password. The server enforces it: until the password is changed, that account is refused everything except reading its own profile and changing its password, so the day-one password cannot be left in place and quietly used.

Change it at the first login, and do not expose the host to an untrusted network before then. The day-one password is published on this page. Using it does not consume it, and the password change is necessarily reachable, so whoever signs in first sets the new password. Anyone who reaches your install before you do can take the account and lock you out, and the only sign is that the documented password stops working. The window runs from the first container start until the password is actually changed — signing in does not close it.
The Devices page renders — empty on a fresh install.
Run a first discovery from Set Up Network → Discovery, with credentials and subnets, and confirm nodes appear.

Your license

A fresh install starts a 14-day evaluation: 5 devices, every tier on, with no key to enter and nothing to activate. To license it, send the Installation ID shown on the License page to sales@netends.com and upload the .nelic file you receive on the same page. See Licenses & entitlements.

HTTPS and certificates

NetEnds is served over HTTPS on port 443. Port 80 redirects every request there, with two exceptions: /health, which the installers and the updater check on the host, and a request carrying X-Forwarded-Proto: https, which is how a TLS-terminating proxy in front of NetEnds says the browser is already on HTTPS. HSTS is off by default.

The certificate is two files in /opt/netends/certs/: fullchain.pem (the server certificate, then each issuer in turn) and privkey.pem (its private key, mode 0600, owned by root). The one generated at install is ECDSA P-256, valid 825 days, and covers the host’s name, its fully qualified name and every address it has other than loopback and link-local ones.

Everything else goes through one tool installed with the platform:

sudo /opt/netends/netends-tls show

It prints the certificate’s subject, issuer, names, expiry and fingerprint, whether the key matches, whether the chain is in order, and what nginx is actually serving on 443.

Install your own certificate

sudo /opt/netends/netends-tls install --cert server.pem --key server.key --chain intermediates.pem

The --chain option adds the intermediates when --cert does not already hold them. Before anything changes, the tool checks that the key belongs to the certificate, that the key has no passphrase, that the certificate has not expired and that the chain is in order. It then swaps the files in, tests the web-server configuration, reloads without dropping connections, and checks that 443 presents the new certificate. If any step fails, the previous certificate is put back.

Then set the base URL that emails and notifications link to: Settings → Platform Identity. It takes precedence over FRONTEND_URL in /opt/netends/.env.

After an address or host-name change

sudo /opt/netends/netends-tls regenerate --san extra.name.example --san 192.0.2.10

The --san options are optional. The tool refuses to replace a certificate that is not self-signed — it is probably yours — unless you pass --force.

HSTS

HSTS tells a browser never to let anyone past a certificate warning for this host, for a year after each visit. With a self-signed certificate that would lock every user out, so the tool refuses to turn it on until a certificate your browsers trust is installed. Then:

sudo /opt/netends/netends-tls hsts on

Running hsts off stops sending the header, but browsers that already received it keep insisting on HTTPS until it expires.

Behind a reverse proxy or load balancer

A proxy that terminates TLS and forwards to port 80 works as long as it sends X-Forwarded-Proto: https, which most do by default. Without that header every request is redirected to HTTPS, which through the proxy is a loop: add the header, or point the proxy at port 443. A proxy pointed at port 443 must accept the self-signed certificate until you install one it trusts.

An install that stayed on HTTP

An upgrade never overwrites an nginx.release.conf you edited, so such an install keeps its own configuration and the installer says HTTPS was not applied. The HTTPS version is beside yours as nginx.release.conf.dist, with a certificate already generated for it. Carry any change you still need into the .dist file, then:

sudo cp /opt/netends/nginx.release.conf.dist /opt/netends/nginx.release.conf
cd /opt/netends && sudo docker compose up -d --force-recreate nginx

Day-2 operations

From /opt/netends:

docker compose ps                # service state (health checks and auto-restart built in)
docker compose logs -f backend   # any service: backend, workers, ingest
docker compose up -d             # apply .env edits
docker compose down              # stop (your data persists in named volumes)