From: Giorgio Ravera Date: Mon, 31 Aug 2026 20:46:08 +0000 (+0200) Subject: Added new workflow for wiki and initial wiki X-Git-Url: http://git.giorgioravera.it/?a=commitdiff_plain;h=f25ff3b9828fe70b32b8509062c9a03ec7b1d5f7;p=network-manager.git Added new workflow for wiki and initial wiki --- diff --git a/.github/workflows/wiki-sync.yaml b/.github/workflows/wiki-sync.yaml new file mode 100644 index 0000000..5934e20 --- /dev/null +++ b/.github/workflows/wiki-sync.yaml @@ -0,0 +1,90 @@ +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 diff --git a/backend/docs/wiki/Home.md b/backend/docs/wiki/Home.md new file mode 100644 index 0000000..083e10b --- /dev/null +++ b/backend/docs/wiki/Home.md @@ -0,0 +1,182 @@ +# 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]] diff --git a/backend/docs/wiki/Quick-Start.md b/backend/docs/wiki/Quick-Start.md new file mode 100644 index 0000000..2386252 --- /dev/null +++ b/backend/docs/wiki/Quick-Start.md @@ -0,0 +1,136 @@ +# 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)