Infracheck operating guide.

Overview

Infracheck is a local-first network diagnostics stack for home users, small offices, IT support teams and MSPs. It starts with Android and Windows apps for the user's own device, then adds a Docker-based local appliance when a site needs continuous evidence.

For product positioning and use-case pages, see What is Infracheck, self-hosted MSP monitoring, Docker appliance monitoring, Android Wi-Fi diagnostics, and network evidence reports. For practical troubleshooting intent, use Wi-Fi quality and stability test and local network diagnostics.

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 diagnostics

Use App Only when you want to check the network from the phone or PC itself, whether you are troubleshooting your own home Wi-Fi or collecting evidence during a support visit.

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 tools

• Manual start/stop sampling for location-dependent or intermittent problems.
• Live RSSI/BSSID charting and saved analysis history.
• Nearby network checks for channels, security, congestion and strong neighbors.
• Roaming-style evidence with BSSID changes, RSSI range, sample count, and recommendations.

Windows App diagnostics

Use the Windows app when the complaint needs evidence from a laptop, desktop, wired adapter, VPN path, Windows Wi-Fi environment, DNS resolver, or local subnet. It works standalone and does not require an appliance.

Primary workflow

1. Open the app and run Check this PC now from Overview.
2. Review gateway, DNS, HTTP, public IP, adapter state, and recommendations.
3. Open Wi-Fi Live for nearby network and channel analysis.
4. Open Ethernet & LAN for wired adapters and safe subnet discovery.
5. Use Tools for speed, trace route, DNS lookup, HTTP, TCP, MTU, VPN/routes, DNS comparison, DHCP, TLS, and quality tests.
6. Export a PDF report when you need customer or ticket evidence.

Public screenshots intentionally hash Wi-Fi names and BSSIDs and mask private addresses, appliance URLs, public IP examples, and tokens. The product itself stores diagnostic history locally under the Windows user profile unless the user exports a report.

Open the Windows app repository.

App + Appliance workflow

Use this mode when a Linux Docker appliance is deployed in a home, office or customer network. It is useful when history must remain available after the first check or support visit.

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.
8. Use Field tools for Site AutoTest, local throughput, VoIP readiness, progressive path checks, DNS/DHCP integrity, SNMP/LLDP topology and floor-plan Wi-Fi survey.

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 GitHub

The free appliance repository is available at github.com/gatgserv/infracheck-appliance.

git clone https://github.com/gatgserv/infracheck-appliance.git
cd infracheck-appliance
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

Upgrade and rollback

Before upgrading, keep a copy of .env, config/config.yaml, and the persistent data/ folder. The appliance stores local history in SQLite and generated reports under the mounted data path.

cd infracheck-appliance
cp .env .env.backup
cp config/config.yaml config/config.yaml.backup
docker compose pull
docker compose up -d --build

If an upgrade fails, restore the previous repository version and the saved config files, then run docker compose up -d --build again. Do not delete data/ unless you intentionally want to clear local history and reports.

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"

Schedules, retention, and storage

Use the Configuration page to set how often each check runs: ping, DNS, HTTP/TLS, LAN discovery, WAN speed, and advanced checks can be scheduled independently. TLS expiry checks normally do not need minute-level frequency; daily cadence is usually enough unless the target list changes often.

The mounted data path keeps SQLite history and generated reports. Configure retention to match customer policy, ticket evidence requirements, and disk size. For small sites, keeping recent operational history plus selected customer reports is usually more useful than keeping every raw check forever.

• SQLite: check history, alert lifecycle, device inventory, labels, comments, settings, and report records.
• Reports: generated PDF/HTML evidence files stored under the reports path.
• Backups: copy .env, config/config.yaml, and data/ before upgrades or host migration.

Dashboard and operational UI

The appliance UI is designed as a local network health dashboard for owners, administrators and support teams.

• 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 is the appliance download?

The free appliance is published at github.com/gatgserv/infracheck-appliance. The Download page links to the repository and version 1.0.0.

What should I 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.