--- /dev/null
+name: Wiki Sync
+
+on:
+ push:
+ branches:
+ - main
+ paths:
+ - 'docs/wiki/**'
+ - '.github/workflows/wiki-sync.yaml'
+ workflow_dispatch:
+
+permissions:
+ contents: write
+
+concurrency:
+ group: wiki-sync
+ cancel-in-progress: false
+
+jobs:
+ wiki-sync:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ persist-credentials: false
+
+ - name: Configure repository authentication
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: gh auth setup-git
+
+ - name: Check whether this is still the current main revision
+ id: current-main
+ shell: bash
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ CURRENT_SHA=$(gh api repos/${GITHUB_REPOSITORY}/git/ref/heads/main --jq '.object.sha')
+ if [ "$CURRENT_SHA" != "$GITHUB_SHA" ]; then
+ echo "Skipping obsolete workflow."
+ echo "Current SHA: $CURRENT_SHA"
+ echo "Workflow SHA: $GITHUB_SHA"
+ echo "publish=false" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+ echo "publish=true" >> "$GITHUB_OUTPUT"
+
+ - name: Checkout wiki
+ if: steps.current-main.outputs.publish == 'true'
+ run: |
+ git clone https://github.com/${GITHUB_REPOSITORY}.wiki.git wiki
+
+ - name: Sync wiki
+ if: steps.current-main.outputs.publish == 'true'
+ run: |
+ rsync -av --delete docs/wiki/ wiki/
+
+ - name: Commit and push
+ if: steps.current-main.outputs.publish == 'true'
+ shell: bash
+ run: |
+ CURRENT_SHA=$(gh api repos/${GITHUB_REPOSITORY}/git/ref/heads/main --jq '.object.sha')
+ if [ "$CURRENT_SHA" != "$GITHUB_SHA" ]; then
+ echo "Skipping obsolete workflow."
+ echo "Current SHA: $CURRENT_SHA"
+ echo "Workflow SHA: $GITHUB_SHA"
+ exit 0
+ fi
+
+ git -C "wiki" diff --check
+ git -C "wiki" add --all
+ if git -C "wiki" diff --cached --quiet; then
+ echo "Wiki already up to date"
+ exit 0
+ fi
+
+ git -C "wiki" config user.name "github-actions[bot]"
+ git -C "wiki" config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ git -C "wiki" commit -m "docs: sync wiki from ${GITHUB_SHA:0:12}"
+
+ CURRENT_SHA=$(gh api repos/${GITHUB_REPOSITORY}/git/ref/heads/main --jq '.object.sha')
+ if [ "$CURRENT_SHA" != "$GITHUB_SHA" ]; then
+ echo "Skipping obsolete workflow."
+ echo "Current SHA: $CURRENT_SHA"
+ echo "Workflow SHA: $GITHUB_SHA"
+ exit 0
+ fi
+ git -C "wiki" push origin HEAD
--- /dev/null
+# Network Manager
+
+Welcome to the **Network Manager Wiki**.
+
+Network Manager is a web-based platform designed to simplify the administration of network infrastructure through a centralized management interface. It integrates DNS, DHCP, and certificate management into a single solution, providing administrators with complete visibility and control over their network environment.
+
+---
+
+## 🌐 What is Network Manager?
+
+Network Manager is an integrated frontend for:
+
+- **BIND DNS**
+- **Kea DHCP**
+- **Let's Encrypt** certificate management
+
+The application automatically generates and manages network configurations while maintaining a local configuration history that supports auditing and rollback operations. It is designed to reduce operational complexity, eliminate manual configuration errors, and provide a single source of truth for network services management.
+
+---
+
+## ✨ Key Features
+
+### DNS Management
+
+Manage DNS zones and records through a modern web interface.
+
+### DHCP Management
+
+Configure and administer DHCP services and network hosts.
+
+### Automated Configuration Generation
+
+Generate DNS and DHCP configurations automatically from your defined domain and network settings.
+
+### Configuration Versioning
+
+Track changes, review history, and roll back to previous configurations when required.
+
+### Security & Authentication
+
+- Administrator authentication
+- Configurable login rate limiting
+- Docker Secrets support
+- Secure session management with customizable session keys
+
+### Lightweight & Self-Hosted
+
+- SQLite-based persistence
+- Minimal infrastructure requirements
+- Easy deployment with Docker and Docker Compose
+
+### Centralized Administration
+
+Manage hosts, DNS zones, DHCP leases, and certificates from a single interface.
+
+---
+
+## 🏗 Architecture Overview
+
+```text
+┌─────────────────────────┐
+│ Web Interface │
+└────────────┬────────────┘
+ │
+ ▼
+┌─────────────────────────┐
+│ Network Manager │
+│ Backend/API │
+└───────┬─────────┬───────┘
+ │ │
+ ▼ ▼
+ BIND DNS Kea DHCP
+ │
+ ▼
+ Let's Encrypt
+```
+
+---
+
+## 🚀 Getting Started
+
+Deploying Network Manager is straightforward:
+
+1. Prepare a Docker environment.
+2. Configure application settings through environment variables.
+3. Launch the application using Docker Compose.
+4. Access the web interface and start managing your network services.
+
+For detailed installation instructions, continue with the **Getting Started** section of this wiki.
+
+---
+
+## 📚 Documentation
+
+### Introduction
+
+- Overview
+- Architecture
+- Design Principles
+
+### Installation
+
+- Requirements
+- Docker Deployment
+- Environment Setup
+
+### Configuration
+
+- Environment Variables
+- Authentication
+- Session Management
+- Logging
+
+### Administration
+
+- DNS Management
+- DHCP Management
+- Host Management
+- Certificate Management
+
+### Operations
+
+- Backup & Restore
+- Configuration Rollback
+- Monitoring & Logs
+- Troubleshooting
+
+### Development
+
+- Development Setup
+- Project Structure
+- Roadmap
+- Contributing
+
+---
+
+## 📦 Technology Stack
+
+- Python Backend
+- SQLite Database
+- BIND DNS
+- Kea DHCP
+- Let's Encrypt
+- Docker
+- Docker Compose
+
+---
+
+## 🎯 Project Goals
+
+Network Manager aims to provide:
+
+- A unified interface for network service administration
+- Automated generation of service configurations
+- Secure and auditable infrastructure management
+- Simplified deployment and maintenance
+- Reliable configuration tracking and recovery mechanisms
+
+---
+
+## 🚧 Project Status
+
+Network Manager is an actively developed project. New features and improvements are continuously planned and tracked through the project roadmap and TODO list.
+
+---
+
+## 🤝 Contributing
+
+Contributions, bug reports, feature requests, and feedback are welcome.
+
+If you'd like to help improve Network Manager:
+
+1. Open an issue to discuss proposed changes.
+2. Fork the repository.
+3. Create a feature branch.
+4. Submit a pull request.
+
+Together we can build a powerful, modern, and easy-to-use network management platform.
+
+---
+
+**Next:** → [[Getting Started]]
--- /dev/null
+# Quick Start
+
+This guide deploys a persistent Network Manager instance for homelab or small network environments.
+For production deployments, review the security recommendations before exposing the application to untrusted networks.
+
+## Prerequisites
+
+- Docker Engine with the Compose plugin, or another compatible container runtime.
+- TCP port 8000 available on the host.
+- A writable data volume for the SQLite database, backups, and logs.
+- A modern web browser.
+
+## Option 1: Docker Compose
+
+Download the homelab Compose file and start WebSSH:
+
+```bash
+mkdir network-manager-deployment
+cd network-manager-deployment
+curl -O https://raw.githubusercontent.com/xraver/network-manager/main/docker-compose.yaml
+docker compose up -d
+```
+
+PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Path network-manager-deployment
+Set-Location network-manager-deployment
+Invoke-WebRequest `
+ https://raw.githubusercontent.com/xraver/network-manager/main/docker-compose.yaml `
+ -OutFile docker-compose.yml
+docker compose up -d
+```
+
+Open `http://localhost:8000` or replace `localhost` with the host address.
+
+## Option 2: Docker run
+
+```bash
+docker run -d \
+ --name network-manager \
+ -p 8000:8000 \
+ -e DOMAIN=example.com \
+ -e EXTERNAL_NAME=dyndns.example.com \
+ -e ADMIN_USER=admin \
+ -e ADMIN_PASSWORD=admin \
+ -v network_manager_data:/data \
+ --restart unless-stopped \
+ ghcr.io/xraver/network-manager:latest
+```
+
+The persistent volume is essential. It stores:
+- SQLite database
+- Configuration data
+- Backups
+- Application logs
+
+Removing the volume will permanently remove all stored data.
+
+## Administrator Password
+
+By default, the application creates the administrator account using the configured environment variables:
+```bash
+ADMIN_USER=admin
+ADMIN_PASSWORD=admin
+```
+For production environments, avoid plaintext passwords and use a Docker secret containing a bcrypt password hash.
+
+Generate a password hash:
+```python
+python - <<'PY'
+import bcrypt
+
+password = b"SecurePassword"
+print(bcrypt.hashpw(password, bcrypt.gensalt()).decode())
+PY
+```
+Save the result to:
+```bash
+./secrets/admin_password_hash
+```
+
+and reference it through:
+```bash
+ADMIN_PASSWORD_HASH_FILE: /run/secrets/admin_password_hash
+```
+
+## Verify the instance
+
+Check container state and readiness:
+
+```bash
+docker compose ps
+curl -fsS http://localhost:8000/about
+curl -fsS http://localhost:8000/api/health
+```
+
+You should receive an HTTP response from the application.
+
+```json
+{
+ "app": {
+ "name": "network-manager",
+ "version": "1.0.0"
+ },
+ "domain": "example.org",
+ "server_time": "2026-08-31T05:33:19.344005+00:00"
+}
+```
+
+```json
+{
+ "status": "healthy",
+ "latency_ms": 0.69,
+ "database": {
+ "status": "healthy",
+ "version": "3.53.2",
+ "tables": 6,
+ "size_mb": 0.07
+ }
+}
+```
+
+Review logs:
+```bash
+docker compose logs --tail=200 network-manager
+```
+
+Open the web interface and log in using the configured administrator account.
+
+## Next steps
+
+- [Docker and Docker Compose](Docker-and-Docker-Compose)
+- [Production Deployment](Production-Deployment)
+- [Users and Account Management](Users-and-Account-Management)
+- [Backup, Restore and Secret Rotation](Backup-Restore-and-Secret-Rotation)
projects / network-manager.git / commitdiff