Getting started

This guide brings up the full Yagra stack on one machine from the published container images: core, a poller, the WebUI, and the stores behind them. By the end you are signed in and monitoring your first node.

This is the production-shaped deployment, not a throwaway evaluation setup. The same composition runs on real installations, and it is the one that can upgrade itself from the WebUI. There is no repository to clone and nothing to compile.

Prerequisites

• Docker and the Docker Compose plugin.
• On Linux you need the NET_RAW capability, because the poller sends ICMP over a raw socket. The Compose file grants it (cap_add: [NET_RAW]).
• 2 vCPU / 4 GB RAM / 20 GB disk is enough to work through this guide. See System requirements for full-stack sizing.

Bring up the stack

1. Make a directory for the deployment and fetch the composition:

   mkdir yagra && cd yagra
   curl -fsSL -o docker-compose.deploy.yml \
     https://github.com/horryworks/Yagra/releases/latest/download/docker-compose.deploy.yml

2. Choose a database password. Do this before the first start. PostgreSQL writes it into the data volume when it initialises, so changing it afterwards takes an ALTER ROLE as well as an edit:

   printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 16)" > .env

   Everything else has a working default. .env.example documents every key if you want to set more.

3. Start everything:

   docker compose -f docker-compose.deploy.yml up -d

   This pulls the images and starts them — there is no separate pull step and no build.

4. Retrieve the one-time admin password, printed to the core logs on first start:

   docker compose -f docker-compose.deploy.yml logs core

5. Open the WebUI at https://localhost and sign in as admin with that password.

   Your browser will warn on this first visit. The certificate is self-signed until you import one, and Yagra cannot know the hostname you will use, so the name usually will not match either. Accept it for now. Settings ▸ TLS takes a real certificate, or regenerates the self-signed one with the right names.

Keep the file where you started it

In-place upgrades read the deployment’s directory back from a label on their own container. They refuse to run if it no longer holds a file named docker-compose.deploy.yml.

Leave both in place, under that name. (The Compose project name is safe either way — the file pins name: yagra itself.)

Tip

The northbound REST API is served at http://localhost:8080, plaintext, unlike the WebUI. The WebUI talks to it for you, so you only need it directly for automation.

Ports

The stack exposes two HTTP ports, plus UDP intake listeners for passive data:

Port	Protocol	Service
443	TCP (HTTPS)	WebUI
8080	TCP (HTTP)	REST API (+ Prometheus /metrics)
514	UDP	syslog intake
162	UDP	SNMP trap intake (v1/v2c + informs)
2055	UDP	NetFlow v5/v9 / IPFIX intake
6343	UDP	sFlow intake

Each is movable. YAGRA_WEB_PORT relocates the WebUI off 443, and the intake listeners have YAGRA_SYSLOG_PORT, YAGRA_TRAP_PORT, YAGRA_FLOW_PORT and YAGRA_SFLOW_PORT.

The stores (PostgreSQL, Redis, NATS, VictoriaMetrics, VictoriaLogs, ClickHouse) stay on the internal Docker network. The full matrix, including what to firewall, is in the port reference.

Add your first node

1. Go to Nodes in the sidebar and choose Add node.

2. Enter a name and the device’s IP address. With no more than that, Yagra starts ICMP liveness monitoring right away.

3. To collect interface and system metrics too, assign an SNMP credential (a v2c community or SNMPv3 user) and pick a device profile. The built-in profiles cover common device families, and a generic SNMP profile works for anything else.

4. Within a poll cycle the node’s detail page fills in: state, response time, and — with SNMP — per-interface traffic.

Adding devices one by one is not the only way. Discovery sweeps an IP range, finds what answers, classifies it, and lets you import the results in bulk. Both paths, plus URL, DNS, and Meraki monitors, are covered in the monitoring guide.

Next steps

• Upgrading later takes no shell. Settings ▸ Upgrade lists the releases this deployment can move to and runs the whole thing: back up, pull, install, recreate, verify. It runs in a sidecar that holds the Docker socket, so core never has to. That works because of the composition you just started — see upgrades & backups.
• Going further? The installation guide covers pinning a release tag, what to back up, distributed pollers at remote sites, native installs without Docker, and building from source.
• Tune the stack — every environment variable, default, and clamp is in the configuration reference.
• Explore the features — alerting, passive events, traffic flow, and dashboards & reports.
• Understand the design — the architecture overview explains how core, pollers, the bus, and the stores fit together.