Installation

Quick Install (Recommended)

One command handles everything: system packages, service user, venv, config, systemd service, network capabilities, and optionally ZeroTier + Tailscale.

bash <(curl -fsSL https://raw.githubusercontent.com/jmobastos/projectmind_314lan/main/scripts/install.sh)

Takes ~2 minutes on a fresh host. After install, open:

http://<HOST_IP>:8080

Default login: admin / m1nd

Change Default Password

Change the default password immediately in Settings > General.

Manual Installation

1. System Packages

sudo apt-get update
sudo apt-get install -y \
    git python3 python3-pip python3-venv python3-dev \
    iputils-ping traceroute curl iproute2 net-tools \
    libssl-dev libffi-dev build-essential ca-certificates

2. Clone Repository

sudo git clone https://github.com/jmobastos/projectmind_314lan.git /opt/m1nd

3. Service User & Permissions

sudo useradd --system --no-create-home --shell /usr/sbin/nologin m1nd
sudo chown -R m1nd:m1nd /opt/m1nd
sudo chmod 750 /opt/m1nd

4. Python Virtual Environment

sudo -u m1nd python3 -m venv /opt/m1nd/.venv
sudo -u m1nd /opt/m1nd/.venv/bin/pip install --upgrade pip
sudo -u m1nd /opt/m1nd/.venv/bin/pip install -r /opt/m1nd/requirements.txt

5. Configuration

sudo -u m1nd cp /opt/m1nd/config.yaml.example /opt/m1nd/config.yaml

See the Configuration page for details on customising config.yaml.

6. Data Directories

sudo mkdir -p /opt/m1nd/data/ssl /opt/m1nd/data/.backups
sudo chown -R m1nd:m1nd /opt/m1nd/data

7. systemd Service

The service runs as the unprivileged m1nd user. AmbientCapabilities grants ICMP/raw-socket access for ping and CAP_NET_BIND_SERVICE for ports 80/443 — no root needed.

sudo tee /etc/systemd/system/m1nd.service > /dev/null <<'EOF'
[Unit]
Description=m1nd Network Synthetic Monitor
Documentation=https://github.com/jmobastos/projectmind_314lan
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=m1nd
Group=m1nd
WorkingDirectory=/opt/m1nd
ExecStart=/opt/m1nd/.venv/bin/python3 /opt/m1nd/main.py
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

# Raw sockets (ping/traceroute) + privileged ports (80/443)
AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN CAP_NET_BIND_SERVICE

# Hardening
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full
ReadWritePaths=/opt/m1nd/data /opt/m1nd/config.yaml

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now m1nd
sudo systemctl status m1nd

Verify Installation

sudo systemctl status m1nd
curl -s http://localhost:8080 | head -5

Troubleshooting

Another service is using port 8080. Either stop it or change m1nd's port:

# Find what's using port 8080
sudo lsof -i :8080

# Change m1nd's port in config.yaml
sudo -u m1nd nano /opt/m1nd/config.yaml
# Set: port: 9090

# Restart
sudo systemctl restart m1nd

You're likely missing build dependencies:

sudo apt-get install -y python3-dev libffi-dev libssl-dev build-essential
sudo -u m1nd /opt/m1nd/.venv/bin/pip install -r /opt/m1nd/requirements.txt

On Raspberry Pi, some packages take longer to compile. Be patient or use --prefer-binary.

The m1nd user needs raw socket capabilities:

# Check capabilities
sudo systemctl show m1nd | grep Capabilities

# If missing, re-apply the service file from step 7 above
sudo systemctl daemon-reload
sudo systemctl restart m1nd

The virtual environment is incomplete or corrupted:

# Recreate the venv
sudo -u m1nd rm -rf /opt/m1nd/.venv
sudo -u m1nd python3 -m venv /opt/m1nd/.venv
sudo -u m1nd /opt/m1nd/.venv/bin/pip install -r /opt/m1nd/requirements.txt
sudo systemctl restart m1nd

Check your firewall:

# UFW
sudo ufw allow 8080/tcp

# firewalld
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT

Also ensure m1nd is binding to 0.0.0.0 (not 127.0.0.1) in config.yaml.

This usually means multiple processes are accessing the database. Ensure only one m1nd instance is running:

# Check for duplicate processes
ps aux | grep m1nd

# Kill any stale processes
sudo systemctl stop m1nd
sudo pkill -f "python3.*main.py"
sudo systemctl start m1nd

Next Steps

• Quick Start — get monitoring in 5 minutes
• Configure your monitoring targets and SNMP settings
• Deploy with ZeroTier or Tailscale for OOB access