ssiroos/netsmartapp repository overview

⁠NetSmartApp

Manage DNS, DHCP, NTP, directory services, Kerberos, mail, monitoring, and WireGuard or AmneziaWG from one self-hosted web panel.

NetSmartApp is designed for small organizations, MSPs, private networks, development labs, and self-hosted environments. It runs as a Docker Compose stack with MySQL and persistent storage.

⁠Start here

• Product and features: https://pwaapps.com/smartnetwork.php⁠
• First-run and domain setup: https://pwaapps.com/netsmart-guide.php⁠
• Docker image: https://hub.docker.com/r/ssiroos/netsmartapp⁠

Use this overview to understand the deployment. Follow the first-run guide for public DNS, HTTPS, firewall rules, first login, licence registration, AmneziaWG, mail, backups, and updates.

⁠Current release

Pin the release for repeatable deployments:

docker pull ssiroos/netsmartapp:1.0.12

ssiroos/netsmartapp:latest is also available, but it is a floating tag and can change.

⁠Licensing

Purchase commercial licences at https://licence.pwaapps.com/⁠.

If a licence expires, core services such as DNS, DHCP, NTP, directory, Kerberos, mail, VPN, and monitoring continue to operate. The deployment must still be renewed to remain legally licensed. The AI Assistant and PWAApps integrations, including SecurityBox, ChaparKhoneh, and PWA AI Relay, are disabled until renewal.

⁠Production requirements

• Native Linux Docker host or Linux VM
• Docker Engine and Docker Compose v2
• Static server address
• Host networking
• NET_ADMIN
• /dev/net/tun for the AmneziaWG userspace fallback
• IPv4 forwarding and NAT for routed VPN clients
• MySQL and persistent volumes
• Free host ports for enabled services

Docker Desktop on Windows or macOS is suitable for evaluation. It does not provide the same production DHCP, routing, and host-network behavior as native Linux.

⁠Prepare secrets and forwarding

Create .env with unique values:

MYSQL_ROOT_PASSWORD=replace-with-a-long-random-root-password
MYSQL_DATABASE=netsmart_db
MYSQL_USER=netsmart_user
MYSQL_PASSWORD=replace-with-a-long-random-database-password
MYSQL_HOST_PORT=3307

NETSMART_HTTP_BIND=127.0.0.1
NETSMART_HTTP_PORT=8080
WIREGUARD_ENDPOINT_HOST=vpn.example.com

SNMP_COMMUNITY=replace-with-a-private-random-community

Use 127.0.0.1 for the panel backend when Nginx or Apache provides HTTPS on the same host. Use 0.0.0.0 only for direct access from a trusted network protected by a firewall.

Enable and persist IPv4 forwarding before using WireGuard or AmneziaWG:

sudo sysctl -w net.ipv4.ip_forward=1
echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-netsmart-vpn.conf
sudo sysctl --system

⁠Production Compose example

services:
  mysql:
    image: mysql:8.4
    container_name: netsmart-mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE:-netsmart_db}
      MYSQL_USER: ${MYSQL_USER:-netsmart_user}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    ports:
      - "127.0.0.1:${MYSQL_HOST_PORT:-3307}:3306"
    volumes:
      - ./mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -u$$MYSQL_USER -p$$MYSQL_PASSWORD"]
      interval: 10s
      timeout: 5s
      retries: 12

  netsmart:
    image: ssiroos/netsmartapp:1.0.12
    container_name: netsmart-app
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      ASPNETCORE_ENVIRONMENT: Production
      ASPNETCORE_URLS: "http://${NETSMART_HTTP_BIND:-127.0.0.1}:${NETSMART_HTTP_PORT:-8080}"
      ConnectionStrings__DefaultConnection: "Server=127.0.0.1;Port=${MYSQL_HOST_PORT:-3307};Database=${MYSQL_DATABASE:-netsmart_db};User ID=${MYSQL_USER:-netsmart_user};Password=${MYSQL_PASSWORD};AllowUserVariables=true"
      DefaultAdmin__Username: sa
      DefaultAdmin__Password: sa123456
      WG_QUICK_USERSPACE_IMPLEMENTATION: amneziawg-go
      WireGuard__Enabled: "false"
      WireGuard__EndpointHost: ${WIREGUARD_ENDPOINT_HOST:-vpn.example.com}
      WireGuard__EnableNat: "true"
      WireGuard__NatInterface: auto
    volumes:
      - ./certs:/app/certs
      - netsmart_app_logs:/app/logs
      - netsmart_data_protection_keys:/app/data-protection-keys
      - netsmart_wireguard_config:/app/wireguard

volumes:
  netsmart_app_logs:
  netsmart_data_protection_keys:
  netsmart_wireguard_config:

Start and inspect:

mkdir -p certs
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 netsmart

⁠Mandatory first login

A fresh database creates:

Username: sa
Password: sa123456

NetSmartApp immediately requires a new password. Complete this step before enabling services. Never keep sa123456 on a running installation.

Then:

1. Create a named administrator for routine work.
2. Configure email or authenticator-app MFA from Login Config.
3. Put the panel behind HTTPS.
4. Restrict the panel to trusted administrator addresses when possible.
5. For commercial use, register the final HTTPS service domain.

⁠Domain planning

Use separate names because the services use different protocols:

Point the required A records to the server. Do not publish AAAA unless IPv6 is fully configured. Keep VPN and mail names in DNS-only mode if the DNS provider offers an HTTP proxy.

Place the panel behind Nginx or Apache with a valid HTTPS certificate. Open NetSmartApp through its final HTTPS name before commercial registration because that hostname becomes the registered service domain. Follow the domain setup guide⁠ for exact DNS, proxy, certificate, and firewall steps.

⁠Included services

• DNS records, forwarding, cache, query logs, and DNS over HTTPS
• DHCP pools and leases
• NTP with upstream failover
• LDAP-style users, OUs, searches, and password policies
• Kerberos v5 KDC
• Optional Samba Active Directory profile for Windows domain join
• WireGuard and AmneziaWG with obfuscation, peers, client downloads, NAT, and live status
• SMTP, submission, SMTPS, POP3, IMAP, TLS, DKIM, filtering, and quarantine
• Prometheus-compatible metrics and read-only SNMP v2c
• Health dashboard and consolidated logs
• CAPTCHA, email MFA, and authenticator-app MFA
• Optional assistant using Ollama, LM Studio, or an OpenAI-compatible provider

The built-in LDAP-style directory is not an Active Directory domain controller. Use the optional Samba AD profile for Windows domain join and a unified Windows-compatible identity domain.

⁠Network exposure

Open only the services you enable.

⁠AmneziaWG checklist

1. Point vpn.example.com to the server.
2. Allow inbound UDP 51820 in cloud and host firewalls.
3. Confirm IPv4 forwarding is enabled.
4. Select AmneziaWG in WireGuard / AmneziaWG Settings.
5. Configure matching client-supported obfuscation values and enable NAT.
6. Select Apply & Start.
7. Create one peer per device with a unique address such as 10.8.0.2/32.
8. Import the downloaded configuration into the AmneziaWG client.
9. Verify a recent handshake and nonzero RX/TX counters.

Client configurations contain private keys. Store and transfer them securely.

⁠Back up and update

Back up MySQL, data-protection keys, VPN configuration, TLS certificates, DKIM keys, external configuration, and optional Samba AD volumes together. Test restoration on an isolated host.

For an update, review release notes, back up, change the pinned tag when necessary, and run:

docker compose pull netsmart
docker compose up -d --force-recreate netsmart
docker compose ps
docker compose logs --tail=200 netsmart

Verify login, health, enabled services, VPN handshakes, DNS, and mail after updating.

⁠Limitations

• NetSmartApp is a consolidated single-stack deployment. High availability, clustering, and automatic failover are not claimed.
• Production DHCP, host routing, and AmneziaWG require native Linux networking.
• Several critical services on one host create a shared failure domain. Add redundancy or separate services when one-host downtime is unacceptable.
• Host ports can conflict with services already installed on the server.

⁠Help

• Setup guide: https://pwaapps.com/netsmart-guide.php⁠
• Product page and FAQ: https://pwaapps.com/smartnetwork.php⁠
• Support: https://pwaapps.com/contact⁠
• Logs: docker compose logs --tail=200 netsmart