Nezha Server and Website Monitoring on AWS User Guide

Overview

Nezha is an open source, lightweight tool for monitoring your servers and websites: a real time status dashboard, HTTP, TCP and Ping service checks, push notifications and alerting, scheduled tasks and a browser based web terminal. It ships as a single self contained Go binary that keeps all of its state in an embedded SQLite database, so a single instance runs the full dashboard, agent gRPC channel and alerting with no external database or object store. The cloudimg image installs the pinned Nezha 2.2.10 dashboard binary and runs it as the nezha-dashboard systemd service. Since version 1, Nezha serves both the browser dashboard and the agent gRPC channel on one port, 8008. Nezha uses native username and password admin accounts, so no external OAuth provider is required. Upstream Nezha seeds a well known default admin login (admin / admin); this image never ships that - on the first boot of every instance the admin password is rotated to a unique, randomly generated value, and the per instance agent and JWT secrets are generated freshly too, so nothing is shared between deployments. Backed by 24/7 cloudimg support.

What is included:

• Nezha 2.2.10 installed as a single Go binary and running as the nezha-dashboard systemd service
• Real time server and website monitoring with a built in web dashboard on :8008
• The browser dashboard and the agent gRPC channel multiplexed on one port, 8008
• Native username and password admin login - no external OAuth provider required
• The weak upstream default admin / admin password rotated to a unique per instance value on first boot
• Per instance agent secret and JWT secret generated freshly on first boot, never shared between instances
• Embedded SQLite store - no external database to run or maintain
• The admin password stored bcrypt hashed, never in plaintext, with the credentials file 0600 root:root
• nezha-dashboard.service as a systemd unit, enabled and active
• 24/7 cloudimg support

Prerequisites

An active AWS account, an EC2 key pair in the target region, and a VPC + subnet with a public IP. m5.large (2 vCPU / 8 GiB RAM) is a comfortable starting point for evaluation and for monitoring dozens of servers; scale the instance up as your fleet grows. Security group inbound: allow 22/tcp from your management network and 8008/tcp for the dashboard and the agents. Port 8008 carries both the browser dashboard and the agent gRPC channel, so your monitored servers connect to the same host and port you browse to. Nezha serves plain HTTP on 8008; for production, front it with TLS on your own domain and restrict access to trusted IP ranges (see Maintenance).

Step 1 - Launch from AWS Marketplace

Sign in to the AWS Marketplace, search for Nezha by cloudimg, and select Continue to Subscribe then Continue to Configuration and Continue to Launch. Choose the region, the m5.large instance type, your VPC and subnet, and your EC2 key pair. For the security group, allow SSH (22) from your management network and add a rule for 8008/tcp so you and your agents can reach the dashboard. Then Launch.

Step 2 - Launch from the AWS CLI

aws ec2 run-instances \
  --image-id <nezha-ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <your-sg-id> \
  --subnet-id <your-subnet-id> \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=nezha}]'

Make sure the security group referenced by --security-group-ids allows inbound 22/tcp from your management network and 8008/tcp for the dashboard and the agents.

Step 3 - Connect to your instance

Connect over SSH as the default login user for your operating system variant:

Step 4 - Confirm the service is running

systemctl is-active nezha-dashboard.service

It reports active. Nezha serves the browser dashboard and the agent gRPC channel on port 8008, and keeps its state in the embedded SQLite database under /opt/nezha/dashboard/data.

Step 5 - Retrieve your admin login

Nezha uses native admin accounts. On the first boot of your instance the weak upstream default password is rotated to a unique value, written to a root-only file:

sudo cat /root/nezha-credentials.txt

This file contains NEZHA_USERNAME (admin), the rotated NEZHA_PASSWORD, the NEZHA_URL to open in a browser, and NEZHA_AGENT_CONNECT (the host and port your monitoring agents connect to). The per instance agent and JWT secrets are generated on first boot and stored in the dashboard config, never shipped in the image. Store the password somewhere safe.

Step 6 - Confirm the default login is disabled

Upstream Nezha ships a well known admin / admin login. This image rotates it on first boot, so the default no longer works and only your per instance password authenticates. The following reads the per instance password from the credentials file and proves the round-trip against the login API - the correct password authenticates and issues a token, while both the old default and a wrong password are rejected:

PW=$(sudo grep '^NEZHA_PASSWORD=' /root/nezha-credentials.txt | cut -d= -f2-)
L(){ curl -s -m 10 -X POST http://127.0.0.1:8008/api/v1/login -H 'Content-Type: application/json' -d "{\"username\":\"admin\",\"password\":\"$1\"}"; }
echo "per-instance password : $(L "$PW"  | jq -r 'if .success==true then "authenticated (token issued)" else "rejected" end')"
echo "default admin         : $(L admin  | jq -r 'if .success==true then "authenticated" else "rejected (default disabled)" end')"
echo "wrong password        : $(L nope   | jq -r 'if .success==true then "authenticated" else "rejected" end')"

It prints per-instance password : authenticated (token issued), default admin : rejected (default disabled), and wrong password : rejected. The dashboard is only reachable with your unique per instance credentials.

Step 7 - Sign in to the web dashboard

Browse to http://<instance-public-ip>:8008/dashboard/. Nezha shows its login page: enter the username admin and the password from Step 5, then select Log in.

Step 8 - Explore the server dashboard

After signing in you land on the admin dashboard. The Server view lists every monitored machine with its group, owner, IP, agent version and status, and the top navigation gives you Service (HTTP, TCP and Ping checks), Task, Notification, Dynamic DNS, NAT Traversal, Group and Server Transfers. A fresh instance starts with no servers - you add them in the next step.

Step 9 - Add a server to monitor

Select Installation command on the Server page and pick the target operating system (Linux, macOS or Windows). Nezha generates a one line installer that downloads the agent, registers it with this dashboard at the agent connect address, and starts reporting metrics. Run that command on each server you want to watch; it appears in the Server list within seconds and begins streaming CPU, memory, disk, network and uptime.

Step 10 - Review the settings

Open the Settings page from the profile menu. Under System settings you can set the site name, language and theme, and the tabs across the top give you User management, Online User sessions, a Web Application Firewall and API Tokens for automation. The cloudimg image ships with the site name preset and English selected.

Step 11 - Confirm the embedded SQLite store

Nezha keeps everything - the admin user, your monitored servers, service checks and history - in a single embedded SQLite database, so there is no separate database server to run:

ls -l /opt/nezha/dashboard/data/sqlite.db
sudo sqlite3 /opt/nezha/dashboard/data/sqlite.db "SELECT 'users: '||count(*) FROM users;"

The database file lives under /opt/nezha/dashboard/data, and the admin password inside it is stored bcrypt hashed, never in plaintext.

Maintenance

• Password and users: the admin password is rotated to a unique value on first boot and written to /root/nezha-credentials.txt. Change it any time from the avatar -> Profile menu in the web UI, and manage additional users under Settings -> User.
• Add servers: use Installation command on the Server page to enrol agents; they connect to this host on port 8008 using the per instance agent secret.
• Restrict access: Nezha serves plain HTTP on port 8008. For production, restrict the port to trusted IP ranges in your security group and front the dashboard with TLS (for example a reverse proxy with your own domain) terminating on :443.
• One port: since version 1 the browser dashboard and the agent gRPC channel share port 8008 (listen_port in /opt/nezha/dashboard/data/config.yaml); your agents use the same host and port you browse to.
• Secrets: the agent secret and JWT secret are generated per instance on first boot and kept in config.yaml; they are never shipped in the image, so no two deployments share a secret.
• Storage and backup: all Nezha state lives in the embedded SQLite database under /opt/nezha/dashboard/data; back up that directory to protect your monitoring configuration and history.
• Licensing (Apache-2.0): Nezha is licensed under the Apache License 2.0. The image ships the unmodified upstream 2.2.10 binary.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.