How to Deploy SigNoz on a VPS

copysudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw --force enable
sudo ufw status verbose

#Install foundryctl

The installer script puts foundryctl in ~/.local/bin:

copycurl -fsSL https://signoz.io/foundry.sh | bash
export PATH="$HOME/.local/bin:$PATH"
grep -q '.local/bin' ~/.bashrc || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
foundryctl --help | head -5

#Write casting.yaml

The casting file describes the installation. The minimal version from SigNoz's docs targets Docker Compose. The patches block uses Foundry's JSON Patch support to change the UI's port mapping from 8080:8080 to 127.0.0.1:8080:8080, so only the reverse proxy can reach it:

copymkdir -p ~/signoz && cd ~/signoz
cat > casting.yaml <<'YAML'
apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: compose
    mode: docker
  patches:
    - target: "deployment/compose.yaml"
      operations:
        - op: replace
          path: /services/signoz-signoz-0/ports/0
          value: "127.0.0.1:8080:8080"
YAML

Don't edit the generated files under pours/ by hand. Foundry's docs are explicit that forge overwrites them on the next run. Every change goes into casting.yaml: component settings under spec.<component>, anything else under spec.patches.

#Deploy

cast checks your environment, renders the Compose files into pours/deployment/, and starts the containers:

copycd ~/signoz
export PATH="$HOME/.local/bin:$PATH"
foundryctl cast -f casting.yaml

Pulling ClickHouse and the other images takes a few minutes on the first run. Wait for the SigNoz server to report healthy, then check that the port mapping took effect:

copycd ~/signoz
for i in $(seq 1 60); do
  curl -fs http://127.0.0.1:8080/api/v1/health && break
  sleep 5
done
echo
docker ps --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'

You should see ClickHouse, ClickHouse Keeper, Postgres (the metadata store), the ingester and the SigNoz server. The server's port should show 127.0.0.1:8080->8080/tcp. The ingester publishes 4317 and 4318 on all interfaces, because that is where your applications send data.

#Create the admin account first

Until the first account exists, SigNoz is not fully set up. Two things follow from that. The signup page is open to whoever reaches the UI first, and that person becomes the root admin. And the ingester does not accept telemetry yet: in our run, OTLP requests to 4318 were refused until an account and organisation existed. They were accepted within a minute of signup. So create the account before you put a domain in front of it and before you debug "missing data".

The UI is bound to loopback, so reach it over an SSH tunnel from your own machine and open http://localhost:8080:

copyssh -L 8080:127.0.0.1:8080 deploy@SERVER_IP

If you'd rather do it from the server's shell, the signup form posts to /api/v1/register. This creates the admin with a generated password saved to ~/signoz/admin-password:

copycd ~/signoz
[ -f admin-password ] || openssl rand -base64 24 > admin-password
chmod 600 admin-password
curl -s -X POST http://127.0.0.1:8080/api/v1/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Admin","orgName":"example","email":"admin@example.com","password":"'"$(cat admin-password)"'"}' \
  | grep -o '"isRoot":[a-z]*'

"isRoot":true confirms the account is the root admin. Change the email to yours. It is your login.

#Send a test trace

Before wiring up a real application, prove the pipeline works end to end. This posts one span to the OTLP/HTTP endpoint in the standard OpenTelemetry JSON encoding, retrying while the ingester finishes starting:

copyfor i in $(seq 1 30); do
  NOW=$(date +%s%N)
  code=$(curl -s -o /tmp/otlp.out -w '%{http_code}' -X POST http://127.0.0.1:4318/v1/traces \
    -H 'Content-Type: application/json' \
    -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"vps-smoke-test"}}]},"scopeSpans":[{"spans":[{"traceId":"5b8efff798038103d269b633813fc60c","spanId":"eee19b7ec3c1b174","name":"smoke-test","kind":1,"startTimeUnixNano":"'"$NOW"'","endTimeUnixNano":"'"$((NOW+50000000))"'"}]}]}]}')
  [ "$code" = 200 ] && break
  sleep 10
done
echo "HTTP $code"; cat /tmp/otlp.out; echo
[ "$code" = 200 ]

HTTP 200 with an empty {"partialSuccess":{}} body means the collector accepted the span. A service called vps-smoke-test should then appear on the Services page.

#HTTPS + domain

Point an A record for signoz.example.com at the server and put Caddy in front of the loopback port:

signoz.example.com {
    reverse_proxy 127.0.0.1:8080
}

Then open https://signoz.example.com and log in with the admin account.

#Securing the OTLP ports

The UI now requires a login. The OTLP receivers on 4317 and 4318 do not: they accept telemetry from anyone who can reach them. Pick one of these:

• Applications on the same box: patch the ingester's ports to 127.0.0.1 the same way as the UI, with two more replace operations on /services/ingester/ports/0 and /services/ingester/ports/1.
• Applications on other servers: restrict 4317/4318 in your provider's cloud firewall to those servers' IPs, or send over a private network or WireGuard.
• Anything over the public internet: put a local OpenTelemetry Collector next to each application and forward over an authenticated, TLS-terminated path. Don't leave an open ingest port for strangers to fill your disk.

#Retention

SigNoz keeps separate retention periods for logs, traces and metrics. Set them in the UI under Settings → Workspace → Retention Controls, with a Save button per signal. Two rules from the docs are worth knowing before you touch them: a change applies only to newly ingested data, and data past its retention is deleted permanently. Raising the number later does not bring it back. Logs usually decide your disk size, so set log retention first.

#Backups

Everything lives in three Docker volumes whose names start with signoz-. List them:

copydocker volume ls --filter name=signoz

The Postgres metadata store holds users, dashboards, alerts and saved views. It is small and the most painful to lose. Dump it with the stack running:

copycd ~/signoz
docker exec signoz-metastore-postgres-0 pg_dump -U signoz signoz \
  | gzip > signoz-meta-$(date +%F).sql.gz
ls -lh signoz-meta-*.sql.gz

The ClickHouse volume holds the telemetry itself. It is large, and it is often reasonable not to back it up at all: an observability store is usually worth more for its dashboards and alerts than for last month's spans. If you do want it, stop the stack with docker compose -f pours/deployment/compose.yaml stop, archive the signoz-telemetrystore-0-0-data volume with a throwaway alpine container, and start it again. Copy everything off the box.

#Upgrades

The generated Compose file uses latest tags by default. To upgrade, update foundryctl itself, pull new images, and re-run cast:

copycd ~/signoz
export PATH="$HOME/.local/bin:$PATH"
curl -fsSL https://signoz.io/foundry.sh | bash
docker compose -f pours/deployment/compose.yaml pull
foundryctl cast -f casting.yaml

To stay on a known version instead, pin the image in casting.yaml under spec.signoz.spec.image (for example signoz/signoz:<version>), as the SigNoz docs show. Take a metadata dump before any upgrade.

#Troubleshooting

Containers keep restarting. Almost always memory. Check with free -m and docker stats --no-stream. SigNoz's docs put the floor at 4 GB for Docker.

foundryctl fails. Re-run the same command with --debug. foundryctl gauge -f casting.yaml runs only the prerequisite checks (Docker, Compose) without deploying.

The UI doesn't load through Caddy. Run curl -s 127.0.0.1:8080/api/v1/health on the box. If that works, the problem is DNS or the Caddyfile. If it doesn't, read docker compose -f pours/deployment/compose.yaml logs signoz-signoz-0.

No data from an application. Check that the app's OTLP exporter points at the server on 4317 (gRPC) or 4318 (HTTP), and that the provider firewall allows it. Then send the smoke-test span above from the application's host. If that arrives and the app's data doesn't, the problem is in the app's SDK settings.

#Verification + next steps

You're done when https://signoz.example.com loads over a valid certificate, you're logged in as the admin, vps-smoke-test shows up under Services, docker ps shows the UI bound to 127.0.0.1, and a metadata dump sits somewhere off the box.

Next, instrument a real service with an OpenTelemetry SDK and point it at the ingester. Then set log retention to match your disk before the disk decides for you.