Infracheck operating guide.

Overview

Infracheck is a local-first infrastructure telemetry stack for small IT support teams and MSPs. It combines a native Android field app with a Docker-based local appliance so technicians can compare what the phone sees with what the customer network sees continuously.

Architecture

The stack is intentionally simple: the phone captures client experience, the appliance captures site-wide telemetry, and Premium centralization remains self-hosted.

App Only field diagnostics

Use App Only when the technician is on site without a deployed appliance. This mode sees the network from the phone perspective.

Quick Scan checks

• SSID, BSSID, IP/DHCP details, RSSI, link speed, channel, and Android internet validation.
• DNS latency, HTTP latency, public IP, captive portal behavior, neighboring networks, and channel congestion.
• Recommendations for weak signal, low link rate, channel interference, slow DNS, slow HTTP, and captive portal issues.

Wi-Fi Live and roaming

• Manual start/stop sampling for location-dependent or intermittent problems.
• Live RSSI/BSSID charting and saved analysis history.
• Roaming result with BSSID changes, RSSI range, sample count, and recommendations.

App + Appliance workflow

Use this mode when a Linux Docker appliance is deployed in the customer network. It is the recommended support workflow because history remains available after the technician leaves.

1. Discover the appliance through mDNS _infracheck._tcp, or pair manually by URL and admin token.
2. Review health, problem radar, latest values, charts, active alerts, WAN speed, and LAN inventory.
3. Acknowledge, hide for 24 hours, or close alerts directly from the app.
4. Edit LAN device hostname overrides and technician comments.
5. Configure discovery ranges, targets, thresholds, WAN speed limits, retention, and admin token.
6. Generate and share appliance PDF reports when the customer needs evidence.
7. Use Phone vs Appliance when the phone sees a problem that the appliance does not, or the opposite.

Appliance installation

Infracheck v1 targets Linux Docker hosts on the target LAN.

Requirements

• Linux host inside the customer network.
• Docker Engine and Docker Compose plugin.
• Internet access during first install so images can be downloaded.

Install from appliance kit

unzip infracheck-appliance-kit.zip
cd infracheck-appliance-kit
sh scripts/install-linux.sh

Installer actions

• Creates .env with generated admin/read/Grafana tokens if missing.
• Creates config/config.yaml from the example if missing.
• Creates the persistent data/ folder.
• Opens common firewalld ports when firewalld is active.
• Runs docker compose up -d --build.

Open services

• Appliance UI: http://<host-ip>:8080/ui
• Grafana: http://<host-ip>:3000
• Prometheus: http://<host-ip>:9090
• Alertmanager: http://<host-ip>:9093

Configuration

The default appliance config is mounted at /etc/infracheck/config.yaml. In local deployments, edit container/config/config.yaml.

Important environment overrides

Discovery ranges

When discovery CIDRs are empty, the agent auto-detects directly connected IPv4 networks and caps broad masks to /24. For routed networks or multiple VLANs, configure every range explicitly.

targets:
  discovery:
    cidrs:
      - "192.168.10.0/24"
      - "192.168.20.0/24"
      - "10.20.0.0/23"

Dashboard and operational UI

The appliance UI is designed as the technician command center for a customer site.

• Dashboard: overall health, problem radar, findings, network quality, WAN speed, LAN devices, latest checks, and report actions.
• Alerts: active and historical alerts with severity, trigger time, acknowledge time, clear time, details, acknowledge, close, and temporary hide/suppress actions.
• Inventory: discovered devices, first/last seen timestamps, hostname override, and technician comments.
• Configuration: discovery ranges, ping/DNS/HTTP/TLS targets, advanced checks, WAN speed limits, alert thresholds, retention, and admin token changes.

Reports and customer evidence

Reports convert support work into customer-visible evidence. Use them after installs, after incident triage, before/after remediation, or for recurring account reviews.

• Executive summary and health score.
• Problem localization and triage details.
• Health impact, findings, recommendations, and graphs.
• Min/avg/max statistics for the selected reporting period.
• Alert lifecycle, latest checks, and LAN inventory snapshot.

Security model

Infracheck is local-first. The free appliance runs inside the customer network, and Premium centralization is planned as self-hosted.

• Read endpoints can remain public on the LAN by default.
• Mutating endpoints require the admin token.
• Mutating actions include manual test runs, iperf3 server start/stop, manual LAN discovery, and report generation.
• Metrics are public by default for Prometheus. Set security.protect_metrics: true or INFRACHECK_PROTECT_METRICS=true to protect /metrics.
• Set security.allow_public_reads: false or INFRACHECK_ALLOW_PUBLIC_READS=false to protect read-only API endpoints.
• The agent accepts Authorization: Bearer <token> and X-Infracheck-Token: <token>.
• The stack uses host networking on Linux and limited network capabilities. It does not require --privileged by default.
• Keep .env, generated tokens, Grafana credentials, and data/ private.

API and diagnostics commands

Use these commands during installation validation, troubleshooting, or automation.

curl http://localhost:8080/healthz
curl http://localhost:8080/readyz
curl http://localhost:8080/api/v1/info
curl http://localhost:8080/api/v1/health
curl http://localhost:8080/api/v1/verdicts/latest
curl http://localhost:8080/api/v1/recommendations
curl http://localhost:8080/api/v1/tests/ping/latest
curl http://localhost:8080/api/v1/tests/dns/latest
curl http://localhost:8080/api/v1/tests/http/latest
curl http://localhost:8080/api/v1/tests/speed/latest
curl http://localhost:8080/api/v1/devices
curl http://localhost:8080/api/v1/reports

Protected actions

curl -X POST http://localhost:8080/api/v1/tests/ping/run \
  -H "Authorization: Bearer $INFRACHECK_ADMIN_TOKEN"

curl -X POST http://localhost:8080/api/v1/discovery/run \
  -H "Authorization: Bearer $INFRACHECK_ADMIN_TOKEN"

curl -X POST http://localhost:8080/api/v1/reports/generate \
  -H "Authorization: Bearer $INFRACHECK_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"daily","hours":24}'

Troubleshooting

Check logs

cd container
docker compose logs -f

Check health and metrics

curl http://localhost:8080/healthz
curl http://localhost:8080/readyz
curl http://localhost:8080/metrics

Start a local throughput test server

curl -X POST http://localhost:8080/api/v1/iperf/server/start \
  -H "Authorization: Bearer $INFRACHECK_ADMIN_TOKEN"
iperf3 -c <agent-ip>
curl -X POST http://localhost:8080/api/v1/iperf/server/stop \
  -H "Authorization: Bearer $INFRACHECK_ADMIN_TOKEN"

Run LAN discovery

curl -X POST http://localhost:8080/api/v1/discovery/run \
  -H "Authorization: Bearer $INFRACHECK_ADMIN_TOKEN"
curl http://localhost:8080/api/v1/devices

If gateway auto-detection fails, set targets.gateway.address explicitly in the config.

Self-hosted Premium License roadmap

Premium is positioned as a paid license for organizations that need central operations without forcing customer data into a vendor-hosted SaaS.

• Self-hosted central portal for multiple appliances.
• Customer/location grouping for MSPs.
• Email, webhook, Slack, or Teams alert routing.
• White label branding and branded reports.
• Roles, permissions, API access, and audit-oriented workflows.

FAQ

Is the app free?

Yes. The field app is positioned as free.

Is the appliance free?

Yes. The local appliance/container is positioned as free.

Is Premium a SaaS subscription?

No. The current positioning is a paid Premium License with a self-hosted central portal.

Where will download links go?

The Start Free page is ready for the Android app link and the appliance container link when they are available.

What should a technician check after deploy?

1. Confirm the Appliance UI opens on http://<appliance-ip>:8080/ui.
2. Set a strong admin token and store it in the app pairing screen.
3. Configure real customer discovery ranges, targets, and thresholds.
4. Run manual ping, DNS, HTTP, discovery, and WAN speed tests.
5. Generate a current status report and confirm charts and tables look correct.