Up and running in minutes

A single curl command handles everything: Docker setup, image pull from Docker Hub, environment generation, and stack launch. No git clone, no source code on your server.

Requirements

What you need before installing

Operating System

Ubuntu 22.04 / 24.04 / 25.10
Debian 12 / 13

Docker

Docker Engine 24+
Docker Compose v2
(The installer can install Docker for you)

RAM

2 GB minimum
4 GB+ recommended

Storage

25 GB minimum
40 GB+ recommended
SSD strongly preferred

Network Ports

Port 80 — HTTP (redirect + ACME)
Port 443 — HTTPS proxy traffic
Port 8443 — Admin panel

Root / sudo

Installer must run as root
or with sudo

One-Line Installation

The install script auto-detects the latest published image from Docker Hub, pulls it, creates the stack in /opt/nyxguardmanager, and enables reboot persistence via systemd.

BASH · FRESH INSTALL

curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/install.sh | sudo bash

✓ Installs to /opt/nyxguardmanager/ by default. Admin panel accessible at https://<your-ip>:8443/ after install.

What the Installer Does

Here's exactly what happens when you run the install script, step by step.

Install base packages & Docker

If Docker Engine and Docker Compose v2 are not installed, the script adds the official Docker apt repository and installs them automatically. Then it enables the Docker daemon.

Requires apt-get — Ubuntu and Debian are fully supported. Other distros: install Docker manually first.

Detect the latest image tag from Docker Hub

The installer queries Docker Hub (nyxmael/nyxguardmanager) for all published semantic version tags and selects the highest one automatically. No manual version tracking needed.

OVERRIDE: PIN A SPECIFIC VERSION

APP_TAG=4.0.0 curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/install.sh | sudo bash

Generate `.env` with random secrets

If no .env exists in the install directory, the script generates one with strong random passwords for the database. The file is set to chmod 600. If a .env already exists (upgrade), it is never overwritten.

⚠ Keep your .env file secure. Never commit it to version control — it contains your database credentials.

Write `docker-compose.yml` and pull the image

The script writes a ready-to-run Compose file referencing the detected image tag, then pulls the image from Docker Hub.

IMAGE PULLED

docker pull nyxmael/nyxguardmanager:<latest-tag>

Start the stack & enable systemd service

The stack starts with Docker Compose. A systemd unit is installed and enabled so the stack auto-starts on every reboot.

AUTO-START SERVICE

# Installed automatically:
/etc/systemd/system/nyxguardmanager.service
# Enabled with:
systemctl enable --now nyxguardmanager.service

Open the admin panel

Navigate to the admin panel URL. First boot runs the setup wizard — create your admin account and configure your first proxy host.

URL

https://<your-server-ip>:8443/

The admin panel uses a self-signed certificate on first launch. Your browser will show a security warning — this is expected. Accept it to proceed. You can replace the cert via Settings → SSL after setup.

✓ Setup wizard runs on first boot. No hardcoded default passwords.

Manual Install via Docker Compose

Prefer to set it up yourself without running a script? Use the compose file below. No source code is needed — everything runs from the prebuilt Docker image.

Create install directory

BASH

sudo mkdir -p /opt/nyxguardmanager
cd /opt/nyxguardmanager

Create `docker-compose.yml`

docker-compose.yml

services:
  nyxguard-manager:
    container_name: nyxguard-manager
    image: nyxmael/nyxguardmanager:4.0.0
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "8443:8443"
    environment:
      TZ: "${TZ:-UTC}"
      PUID: "${PUID:-1000}"
      PGID: "${PGID:-1000}"
      DB_MYSQL_HOST: "db"
      DB_MYSQL_PORT: "3306"
      DB_MYSQL_USER: "${DB_MYSQL_USER:-nyxguard}"
      DB_MYSQL_PASSWORD: "${DB_MYSQL_PASSWORD}"
      DB_MYSQL_NAME: "${DB_MYSQL_NAME:-nyxguard}"
      SKIP_CERTBOT_OWNERSHIP: "true"
    healthcheck:
      test: ["CMD", "curl", "-fs", "http://localhost:3000/"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s
    volumes:
      - nyxguard_data:/data
      - nyxguard_letsencrypt:/etc/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /etc/localtime:/etc/localtime:ro
      - /proc/1/net/arp:/host/proc/net/arp:ro
    depends_on:
      - db

  db:
    container_name: nyxguard-db
    image: jc21/mariadb-aria:latest
    restart: unless-stopped
    environment:
      TZ: "${TZ:-UTC}"
      MYSQL_ROOT_PASSWORD: "${MYSQL_ROOT_PASSWORD}"
      MYSQL_DATABASE: "${DB_MYSQL_NAME:-nyxguard}"
      MYSQL_USER: "${DB_MYSQL_USER:-nyxguard}"
      MYSQL_PASSWORD: "${DB_MYSQL_PASSWORD}"
    volumes:
      - nyxguard_db:/var/lib/mysql
      - /etc/localtime:/etc/localtime:ro

volumes:
  nyxguard_data:
    name: nyxguard_data
  nyxguard_letsencrypt:
    name: nyxguard_letsencrypt
  nyxguard_db:
    name: nyxguard_db

Create `.env` with strong passwords

.env

TZ=UTC
PUID=1000
PGID=1000
DB_MYSQL_USER=nyxguard
DB_MYSQL_NAME=nyxguard
DB_MYSQL_PASSWORD=CHANGE_ME_STRONG_PASSWORD
MYSQL_ROOT_PASSWORD=CHANGE_ME_STRONG_ROOT_PASSWORD

⚠ Replace both passwords with strong random values before starting. Never commit .env to version control.

Start the stack

BASH

docker compose --env-file .env up -d
docker compose logs -f  # watch startup

Updating NyxGuard Manager

The update script checks Docker Hub for the latest published tag, compares it to your running version, and if a newer release exists, prompts you and applies the update in-place. Your data and configuration live in Docker volumes and are never touched.

Run the update script

BASH · STANDARD UPDATE

curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/update.sh | sudo bash

What the updater does

UPDATE FLOW

# 1. Read current image tag from docker-compose.yml
# 2. Query Docker Hub for latest published semver tag
# 3. If no newer release → print "No newer release found." and exit
# 4. If newer → display current vs target, prompt y/N
# 5. docker pull nyxmael/nyxguardmanager:<new-tag>
# 6. Update image reference in docker-compose.yml
# 7. docker compose up -d --remove-orphans  (rolling restart)
# 8. Print "Update complete."

✓ Docker volumes (DB / config / certs) are never removed or touched during an update.

Optional overrides

BASH · FORCE A SPECIFIC VERSION

FORCE_TAG=4.0.0 curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/update.sh | sudo bash

BASH · NON-INTERACTIVE (CI/CD)

NYXGUARD_AUTO_YES=1 curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/update.sh | sudo bash

Manual update via Docker Compose

If you installed manually (without install.sh), update by pulling the new image and restarting:

BASH · MANUAL UPDATE

cd /opt/nyxguardmanager
docker pull nyxmael/nyxguardmanager:4.0.0
# Update the image: tag in docker-compose.yml, then:
docker compose --env-file .env up -d

Quick Health Checks

Verify your installation is running correctly.

BASH · HEALTH CHECKS

docker ps                                    # confirm containers are Up
curl -kI https://127.0.0.1:8443/             # HTTP 308 or 200
curl -ksS https://127.0.0.1:8443/api/ | jq   # API response
docker logs --tail=100 nyxguard-manager      # recent logs

Environment Variables

All installer and runtime behaviour can be controlled via environment variables.

Installer Variables (install.sh)

Variable	Default	Description
INSTALL_DIR	/opt/nyxguardmanager	Where to create the stack and store compose/env files
IMAGE_REPO	nyxmael/nyxguardmanager	Docker image repository to pull from
APP_TAG	(auto-detect latest)	Pin a specific image version tag, e.g. `4.0.0`

Updater Variables (update.sh)

Variable	Default	Description
INSTALL_DIR	/opt/nyxguardmanager	Location of the existing compose stack
IMAGE_REPO	nyxmael/nyxguardmanager	Docker image repository to check and pull from
FORCE_TAG	(auto-detect latest)	Force update to a specific version tag
NYXGUARD_AUTO_YES	0	Set to `1` to skip the confirmation prompt (non-interactive / CI use)

Runtime .env Variables (docker-compose)

Variable	Default	Description
TZ	UTC	Timezone for the container
PUID / PGID	1000	User and group ID for file ownership
DB_MYSQL_PASSWORD	(generated)	Database password — set by installer, keep it secret
MYSQL_ROOT_PASSWORD	(generated)	MariaDB root password — set by installer, keep it secret
NYXGUARD_POLL_INTERVAL_MS	15000	Attack monitor poll interval in milliseconds (1000–60000)
SKIP_CERTBOT_OWNERSHIP	false	Set to `true` to skip slow certbot chown on startup. Recommended for production.
DISABLE_IPV6	false	Set to `true` to disable IPv6 in nginx.

Sensitive values (database passwords) are generated automatically by the installer. Never commit your .env file to version control.

Post-Install Checklist

After your first successful login, go through these steps to harden your installation.

Enable 2FA

Go to your profile → Enable Two-Factor Authentication. Scan the QR code with your authenticator app and save the recovery codes.

Create your first proxy host

Proxy Hosts → Add Host. Point it to your backend, request a Let's Encrypt certificate, and enable Force HTTPS.

Configure GlobalGate

NyxGuard → GlobalGate. Add your trusted IP ranges, configure country rules, and enable WAF on your proxy hosts.

Set up LAN Access Control (optional)

Settings → LAN Access. Add your LAN CIDR and trusted MAC addresses to restrict admin panel access to local devices only.

Configure GeoIP (optional)

NyxGuard → IPs & Locations → GeoIP DB. Upload a MaxMind GeoLite2 or IP2Location .mmdb file, or enter your MaxMind credentials for auto-updates.

Connect Prometheus (optional)

Settings → Integrations → Create token. Configure Prometheus scrape job. Import the Grafana dashboard from Settings → Grafana.