Documentation

Netra is an open-source DevOps CLI that installs and manages a complete observability stack (Prometheus, Grafana, Loki, Promtail, Node Exporter) on Linux servers.

Overview

Run netra install and Netra will:

Detect your server environment (interfaces, firewall, Docker)
Ask configuration questions (or use a YAML config file)
Generate configuration files from Jinja2 templates
Install Docker if needed
Deploy monitoring services via Docker Compose
Configure firewall rules (optional)
Start the stack and show service URLs

Prerequisites

Linux – Primary target; other platforms may work for generate / scan only.
Python 3.12+ – Or use a released binary.
Docker – For install; Netra can install it if missing. Optional: curl for the Docker install script.

Installation

With pip (recommended; works everywhere including CI):

git clone https://github.com/imabhinavdev/netra.git
cd netra
pip install -r requirements-dev.txt   # or: pip install -r requirements.txt
python -m cli.main --help

With PDM (optional, for local development):

git clone https://github.com/imabhinavdev/netra.git
cd netra
pdm install
pdm run netra --help

If pdm install fails with a requirement error, use the pip method above or run pdm run pip install -r requirements.txt.

Commands

Command	Description
`netra install [config.yaml]`	Install the stack (interactive or from config file)
`netra install --dry-run`	Show what would be done without making changes
`netra scan`	Show network interfaces, firewall, and Docker status
`netra generate [-o DIR]`	Generate config files only (no Docker/install)
`netra status [--install-dir DIR]`	Show running services
`netra update [--install-dir DIR]`	Pull latest images and restart stack
`netra uninstall [--install-dir] [--remove-configs]`	Remove stack (and optionally config files)
`netra cluster add [IP]`	Add a remote server (Node Exporter + Promtail via SSH)
`netra check`	Quick environment check

Deployment modes

Single server – All services (Prometheus, Grafana, Loki, Promtail, Node Exporter) on one machine.
Distributed – Run components on different hosts; use config files or multiple netra install runs with different options.

Install prompts explained

When you run netra install without a config file, Netra will ask you a bunch of questions. Here’s what each one means—and yes, we’ll keep it short and slightly silly.

Prompt order (and typical defaults): (1) Deployment mode → single; (2) Install directory → ~/netra; (3) Firewall (ufw) → yes/no; (4) Components (Prometheus, Grafana, Loki, Promtail, Node Exporter) → all on for single server; (5) Network / bind IP → choose interface; (6) Grafana (remote?, auth?, port) → same server, auth on, port 3000; (7) Prometheus (targets, scrape interval); (8) Logs (Docker, system, custom dirs, Loki destination); (9) If nginx-proxy detected: use proxy?, domain, email.

Deployment

Single server vs Distributed. One box to rule them all, or spread the love across multiple machines. Pick single unless you’re doing a multi-host setup; we won’t judge either way.

Installation directory

Where Netra will drop the compose file, configs, and state. Default is ~/netra. No, we won’t judge your path—just make sure you have write access.

Configure firewall (ufw)?

If you say yes, Netra will try to open the ports the stack needs. This requires root (run with sudo). If you skip it, we’ll still tell you which ports to open manually. Your server, your rules.

Components

Which parts of the stack to install:

Prometheus – The metrics collector. Numbers, graphs, and the occasional existential crisis about cardinality.
Grafana – Pretty dashboards. The only thing we expose to the world when you’re behind nginx-proxy.
Loki – Log aggregation. Like Prometheus, but for logs. No, we’re not making this up.
Promtail – Ships logs to Loki. The loyal sidekick. Node Exporter comes along for the ride when Prometheus is installed.

Network / Select interface

Which IP to bind services to. Netra lists your interfaces (eth0, docker0, etc.). Pick the one the internet can reach—usually the real NIC, not docker0. If you’re not sure, 1 is often the right answer.

Grafana

Where to run – Same server or a remote one. Authentication – Turn it on unless you like living dangerously. Port – Default 3000; we’ll grab the next free one if it’s taken. When behind nginx-proxy, only Grafana gets a public URL; the rest stay behind the curtain.

Prometheus

Targets – Who do you want to spy on? localhost for this machine, or a comma-separated list of host:port for others. Scrape interval – How often to scrape (e.g. 15s). Don’t go too crazy or Prometheus might start judging your life choices.

Logs

Docker container logs? Yes, please. System logs (/var/log)? Also yes, unless you’re a minimalist. Custom log directories? Add as many as you want—we’re not judging. Where to store logs? Local Loki or a remote Loki server. Choose local unless you’ve already got Loki running somewhere else.

nginx-proxy (if detected)

If Netra spots an nginx-proxy container, it’ll ask whether to put this stack behind it. Say yes and you’ll get a domain and email prompt for Let’s Encrypt (ACME). Only Grafana will be exposed publicly; Prometheus, Loki, and friends stay safely on 127.0.0.1.

Config file install

Use a YAML file to avoid interactive prompts:

netra install config.yaml

Config keys (full list):

deployment.mode – single | distributed
install_dir – e.g. ~/netra (top-level)
components.prometheus, components.grafana, components.loki, components.promtail, components.node_exporter – boolean
grafana.enabled, grafana.port, grafana.admin_user, grafana.admin_password
prometheus.scrape_interval, prometheus.port
logs.docker, logs.system – for Promtail
loki.port
firewall.allow_config – open ports (requires root)
ports.grafana, ports.prometheus, ports.loki, ports.node_exporter
nginx_proxy.enabled, nginx_proxy.domain, nginx_proxy.email, nginx_proxy.network – when using nginx-proxy (only Grafana public)

Example config.yaml:

deployment:
  mode: single

grafana:
  enabled: true
  port: 3000

prometheus:
  scrape_interval: 15s

logs:
  docker: true
  system: true

With nginx-proxy (only Grafana public, domain + ACME):

nginx_proxy:
  enabled: true
  domain: grafana.example.com
  email: you@example.com
  #   network: nginx-proxy   # optional, default

Grafana datasources (Prometheus and Loki)

Netra provisions Prometheus and Loki as Grafana datasources automatically. They use internal Docker URLs so Grafana talks to them over the Docker network—no public exposure:

Prometheus – http://prometheus:9090, UID prometheus (default datasource; used by bundled dashboards)
Loki – http://loki:3100, UID loki

The provisioning file is grafana-provisioning-datasources/datasources.yaml in your install directory. When using nginx-proxy, Prometheus and Loki are bound to 127.0.0.1 on the host; Grafana still reaches them via these internal URLs.

After install

Netra prints the service URLs.

Without nginx-proxy: All services listen on the chosen bind IP. Example: Grafana http://<bind_ip>:3000, Prometheus http://<bind_ip>:9090, Loki http://<bind_ip>:3100.

With nginx-proxy: Only Grafana is public (e.g. https://grafana.example.com). Prometheus, Loki, and Node Exporter are bound to 127.0.0.1 and are only reachable on the server (Grafana reaches them via internal Docker URLs).

Default install directory: ~/netra. State is written to netra_state.yaml in that directory. Use --install-dir with status, update, and uninstall if you chose another path.

Firewall

If you enable firewall configuration, Netra will open the ports used by the stack (Grafana 3000, Prometheus 9090, Loki 3100, Node Exporter 9100). This requires root (e.g. sudo netra install). If you skip firewall setup, Netra will still print which ports to open manually. When using nginx-proxy, only the proxy needs to be reachable; Grafana’s port is not opened on the host.

Install directory layout

After netra install, the install directory (e.g. ~/netra) contains:

docker-compose.yml – generated Compose file
prometheus.yml – Prometheus config (if Prometheus installed)
loki.yml – Loki config (if Loki installed)
promtail.yml – Promtail config (if Promtail installed)
grafana-provisioning/ – dashboard provisioning: dashboards.yaml, netra/*.json
grafana-provisioning-datasources/ – datasource provisioning: datasources.yaml (Prometheus + Loki, internal URLs)
netra_state.yaml – install state (ports, options)

Troubleshooting

Grafana “permission denied” on provisioning: Ensure the install directory and grafana-provisioning / grafana-provisioning-datasources directories and files are readable by the Grafana container. Netra sets 755 on dirs and 644 on files.
Loki errors: Check loki.yml in the install directory and ensure paths and ports match your setup.
Port already in use: Netra will offer the next available port; you can also set ports explicitly in your config file.

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for community standards. To report security issues, see SECURITY.md.