Saltar al contenido principal

🚀 SigNoz Installation Guide

SigNoz Installation Flow

This guide walks you through installing SigNoz step by step — including port conflict handling, firewall setup, and verification. Follow every step in order.

📋 Before You Start​

Make sure you completed the Prerequisites checklist. Specifically:

  • Docker is installed and running
  • Docker Compose is available
  • You know which ports are free on your system

Step 0 — Check Your Existing Ports (Critical)​

Run this before anything else. It tells you which ports are already taken on your server:

Linux / Ubuntu:

sudo ss -ltnp | egrep ':(80|8080|3301|4317|4318|9000|9001)\b' || echo "None of these in use"

Windows PowerShell:

@(80, 8080, 3301, 4317, 4318, 9000, 9001) | ForEach-Object {
    $result = netstat -ano | findstr ":$_"
    if ($result) { Write-Host "Port $_ IN USE: $result" }
    else { Write-Host "Port $_ is FREE" }
}

macOS:

for port in 80 8080 3301 4317 4318 9000 9001; do
  lsof -i :$port > /dev/null 2>&1 && echo "Port $port IN USE" || echo "Port $port FREE"
done

Write down which ports are taken. You will need this in Step 4.

Step 1 — Clone the SigNoz Repository​

Linux / macOS:

git clone -b main https://github.com/SigNoz/signoz.git
cd ~/signoz/deploy/docker

Windows (PowerShell or Git Bash):

git clone -b main https://github.com/SigNoz/signoz.git
cd signoz\deploy\docker

Confirm the files are there:

ls -la          # Linux/macOS
dir             # Windows

You should see docker-compose.yaml in the listing.

Step 2 — Back Up the Compose File​

Always back up before editing. If something goes wrong, you can restore it.

Linux / macOS:

cp docker-compose.yaml docker-compose.yaml.bak

Windows:

Copy-Item docker-compose.yaml docker-compose.yaml.bak

Step 3 — Check What Port SigNoz Is Using by Default​

Open the compose file and find the UI port mapping:

Linux / macOS:

grep -n "8080" docker-compose.yaml

You will likely see something like:

- "8080:8080"

This means: host port 8080 → container port 8080

Step 4 — Change the Port If There Is a Conflict​

Only do this step if port 8080 was already in use on your server.

In our case, Jenkins was using 8080, so we changed SigNoz's host port to 3301.

Open the file:

Linux / macOS:

nano docker-compose.yaml

Windows (Notepad):

notepad docker-compose.yaml

Find this line:

- "8080:8080"

Change it to:

- "3301:8080"

📌 Format is always HOST_PORT:CONTAINER_PORT The left number (3301) is what your browser or firewall needs to reach. The right number (8080) stays the same — it's inside the container.

Save and close the file.

💡 Ports 4317 and 4318 (OTLP ingestion) are usually free. Only change those if ss / netstat showed them in use.

Step 5 — Validate the Compose File​

Before starting, verify the YAML is valid (catches typos):

docker compose config > /tmp/signoz-rendered.yaml && echo "✅ Config OK"

If you see ✅ Config OK, proceed. If you see an error, re-check your edits.

Step 6 — Start SigNoz​

Linux / macOS / Windows (all the same Docker command):

docker compose -p signoz up -d --remove-orphans

What each flag means:

  • -p signoz → names this project "signoz" so it's easy to manage
  • up -d → starts containers in the background (detached mode)
  • --remove-orphans → cleans up leftover containers from old runs

This will take 2–5 minutes the first time as Docker downloads all the images.

Step 7 — Verify the Containers Are Running​

docker compose -p signoz ps

Expected output (all should show healthy or running):

NAME                    STATUS          PORTS
signoz                  healthy         0.0.0.0:3301->8080/tcp
clickhouse              healthy         ...
zookeeper               healthy         ...
otel-collector          Up              0.0.0.0:4317->4317/tcp, 0.0.0.0:4318->4318/tcp

Also run this for a cleaner view:

docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

Step 8 — Verify the Ports Are Listening​

# Linux
sudo ss -ltnp | egrep ':(3301|4317|4318)\b'

You should see lines with LISTEN for all three ports.

Step 9 — Test the Dashboard Locally​

From inside the VM / server:

curl -I http://localhost:3301

Expected: HTTP/1.1 200 OK

curl http://localhost:3301/api/v1/health

Expected: {"status":"ok"}

If both return correctly, SigNoz is running perfectly on your server. The next step is making it reachable from your browser.

Step 10 — Open the Dashboard in Your Browser​

If Running Locally (your own laptop/PC):​

Open: http://localhost:3301

If Running on a Remote Server (GCP, AWS, any cloud VM):​

You have two options:

Option A — SSH Tunnel (safest, for testing):

# Run this on YOUR laptop, not the server
ssh -L 3301:localhost:3301 your_username@YOUR_VM_PUBLIC_IP

Then open: http://localhost:3301 in your browser.

Option B — Open firewall port (for team access): See the Firewall & Access section below.

🔒 Production recommendation: Do not keep 0.0.0.0/0 open long-term. Start with your office/VPN CIDR only, then put SigNoz behind HTTPS + authentication before wider exposure.

🔥 Firewall & Access Setup​

Google Cloud Platform (GCP)​

  1. Go to GCP Console → VPC Network → Firewall
  2. Click Create Firewall Rule
  3. Fill in:
    • Name: allow-signoz-ui
    • Direction: Ingress
    • Action: Allow
    • Targets: All instances (or specific tag)
    • Source IP ranges: 0.0.0.0/0 (all) or your office IP range
    • Protocols and ports: TCP 3301
  4. Click Create

AWS (EC2 Security Group)​

  1. Go to EC2 → Security Groups
  2. Select your instance's security group
  3. Edit Inbound Rules → Add Rule:
    • Type: Custom TCP
    • Port: 3301
    • Source: Your IP or 0.0.0.0/0

Minimum Hardening Checklist (Production)​

Before sharing SigNoz broadly, verify:

  1. Only trusted CIDRs can reach port 3301
  2. HTTPS reverse proxy is enabled (Nginx/Cloudflare)
  3. First admin account is created and strong password policy is enforced
  4. VM OS firewall (UFW/Security Group) allows only required ports

Ubuntu UFW (local firewall on the server itself)​

Check if UFW is active:

sudo ufw status

If active, allow SigNoz:

sudo ufw allow 3301/tcp
sudo ufw allow 4317/tcp
sudo ufw allow 4318/tcp
sudo ufw status

Windows Firewall (if running locally on Windows)​

# Run PowerShell as Administrator
New-NetFirewallRule -DisplayName "SigNoz UI" -Direction Inbound -Protocol TCP -LocalPort 3301 -Action Allow
New-NetFirewallRule -DisplayName "SigNoz OTLP gRPC" -Direction Inbound -Protocol TCP -LocalPort 4317 -Action Allow
New-NetFirewallRule -DisplayName "SigNoz OTLP HTTP" -Direction Inbound -Protocol TCP -LocalPort 4318 -Action Allow

Step 11 — Create Your First Admin Account​

When you open SigNoz for the first time, it shows a sign-up form. Fill it in.

🔑 The first registered user automatically becomes the admin. Create this account right away — do not leave it open for anyone to claim.

📊 Resource Usage After Install​

Check how much RAM SigNoz is using:

docker stats --no-stream
free -h

SigNoz typically uses 2–3 GB RAM with ClickHouse. On a shared server, keep at least 1–2 GB free for other services.

⏹️ Managing SigNoz​

# Stop SigNoz (containers pause, data is kept)
docker compose -p signoz stop

# Start SigNoz again
docker compose -p signoz start

# Restart SigNoz
docker compose -p signoz restart

# View logs live
docker compose -p signoz logs -f

# View logs for one container
docker compose -p signoz logs -f signoz

# See status
docker compose -p signoz ps

🔄 Auto-Start on Server Reboot​

Add Docker to start on boot (Linux):

sudo systemctl enable docker

SigNoz containers will auto-restart because they have restart: unless-stopped in the compose file (default in SigNoz's official compose).

Verify the restart policy:

docker inspect signoz | grep -i restart

✅ Install Complete​

At this point:

  • ✅ SigNoz containers are running
  • ✅ Ports 3301, 4317, 4318 are listening
  • ✅ Health check returns {"status":"ok"}
  • ✅ You created your admin account

Next: Set up the OTEL Collector →

Read in Sequence​