on:\n\n-
Virtualization (KVM/QEMU, libvirt, Cockpit)\n- Storage (CephFS-first, optional
ZFS, mixed
mode)\n-
Containers (Docker + Compose) and Kubernetes (kubeadm + containerd)\n-
Low-friction
ncurses
installer with minimal choices\n- Automated first-boot provisioning
(Ceph/ZFS/K8s/Docker/libvirt/bridge networking)\n\n## Project Layout\n\n-
README.md —
Overview\n-
context.md — Session history and progress tracking\n- improvements.md —
Enhancement
roadmap and
completed work\n- docs/ — Architecture, operations, profiles, install guides,
TUI docs\n-
etc/ —
System configuration, blocklists, service defaults, systemd units\n- opt/ —
Build
automation,
addons, observability, services, installer assets\n- usr/ — Operational tools,
service
units,
helpers\n- build/ — ISO build scripts and hooks\n- tests/ — Unit, integration,
and
validation\n-
.github/workflows/ — CI/CD pipelines\n\n## Enterprise Features\n\n-
Multi-cluster
management with
failover and federation\n- Advanced network configuration via netcfg-tuiwith
rollback
support\n-
Plugin architecture for custom storage, network, or monitoring providers\n-
End-to-end
testing
framework for deployments and upgrades\n- ADRs and operational playbooks for
production
readiness\n\n## Quick Start (Build ISO)\n\nbash\nsudo apt update\nsudo apt install -y live-build debootstrap xorriso squashfs-tools git\n./build/build-debvisor.sh\n\ntext\n\n## Result:
live-image-amd64.hybrid.iso\n\nThe build script
runsbuild/sync-addons-playbook.shbefore
creating
the ISO so\nbootstrap-addons.ymlinconfig/includes.chrootstays in sync with
the
source\nAnsible
playbook.\n\n## Developer Tasks (Docs/Lint)\n\n- Activate the virtual
environment, then
run linters
and fixers locally.\n- Keep markdown formatting consistent to avoid CI
failures.\n- See
improvements.md for more context and metrics.\n\npowershell\n# Activate venv (PowerShell)\n./.venv/Scripts/Activate.ps1\n\n# Fix a single Markdown file\n& ./.venv/Scripts/python.exe ./fix_markdown_lint.py ./docs/CONTRIBUTING.md\n\n# Run full markdown lint scan\n& ./.venv/Scripts/python.exe -m pymarkdown scan .\n\n# Run fixer unit tests\n& ./.venv/Scripts/python.exe ./scripts/test_fix_markdown_lint.py\n\ntext\n\n##
Profiles\n\n- ceph
(default): All non-OS disks become Ceph OSDs; CephFS at /srv/cephfs; RBD\n\n
pool for VM
disks\n\n-
zfs: Non-OS disks aggregated into ZFS pooltank; datasets for VM, Docker,
and\n\n
K8s\n\n- mixed:
CephFS for shared (RWX) plus ZFS for local performance datasets\n\n## First
Boot\n\nThe
first-boot
unit reads/etc/debvisor-profile(written by the installer)
and\nprovisions:\n\n-
Bridgebr0, KVM
modules, libvirt default pool\n- Ceph (MON/MGR/OSD/MDS, RBD and CephFS pools) if
ceph or
mixed\n-
ZFS pool and datasets if zfs or mixed\n- Docker daemon defaults\n- Kubernetes
single-node
(Calico
CNI, control-plane taint removal)\n- Firewall: SSH (22), Cockpit (9090), K8s API
(6443)\n\n##
Maintenance and Operations\n\n### Ceph Health Checking\n\n- Service:
ceph-health.service(oneshot)
andceph-health.timer(hourly)\n- Logs:journalctl -u ceph-health.service\n-
Management:
see
etc/README.md\n\n### ZFS Pool Scrubbing\n\n- Service:
zfs-scrub-weekly.service(oneshot)
andzfs-scrub-weekly.timer\n\n (weekly, Sunday 2 AM)\n\n- Config:
/etc/default/debvisor-zfs-scrub\n- Logs: journalctl -u zfs-scrub-weekly.service\n\n##
Supply
Chain Security\n\n### Security Features\n\n- GPG-signed release artifacts and
container
images\n-
Dual SBOM formats (CycloneDX and SPDX) with policy enforcement\n- Cosign
attestations
(keyless) with
Rekor transparency log\n- SLSA provenance with source and tag matching\n- VEX
documents
for
vulnerability context\n- Continuous verification with nightly
re-validation\n\n### Quick
Verification\n\nbash\n# Download release\ngh release download v1.0.0\n\n# Verify GPG signature\ngpg --verify debvisor-1.0.0.tar.gz.asc debvisor-1.0.0.tar.gz\n\n# Check SHA256 checksums\nsha256sum -c debvisor-1.0.0.tar.gz.sha256\n\n# Verify container provenance\nslsa-verifier verify-image ghcr.io/undefind/debvisor:1.0.0 --source-uri \\n github.com/UndiFineD/DebVisor\n\n# Verify SBOM attestations\ncosign verify-attestation --type cyclonedx ghcr.io/undefind/debvisor:1.0.0\n\ntext\n\n## Network Configuration\n\n-
Management:
see
etc/README.md for customization and monitoring.\n\n### Blocklist Management\n\n-
Validation:
etc/debvisor/validate-blocklists.sh(CIDR syntax and overlap\n\n
detection)\n\n-
Integrity:etc/debvisor/verify-blocklist-integrity.sh(checksums and format\n\n
verification)\n\n-
Examples:blocklist-example.txt, blocklist-whitelist-example.txt\n- Testing:
GitHub
Actions
validates all blocklists on commit\n\n### Production Deployment Checklist\n\n-
[] Enable
maintenance
timers: systemctl enable ceph-health.timer\n\n zfs-scrub-weekly.timer\n\n- []
Configure
ZFS
timeout for your pool size in /etc/default/debvisor-zfs-scrub\n- [] Align
timer
schedules with
maintenance windows\n- [] Set up log aggregation or alerts for service
failures\n- []
Stagger scrub
schedules across nodes\n- [] Test manual run: systemctl start zfs-scrub-weekly.service\n- [ ]
Monitor logs during the first automated run\n\n## Modes\n\n- lab(default):
ensuresroot, node,
and monitorusers exist (non-root\n\n locked), convenience defaults\n\n-prod:
only
ensures
root; create other accounts via your workflow\n\n## Addons\n\n- Global config:
/etc/debvisor-addons.confwith flagsADDON_RPC_SERVICE,\n\n ADDON_WEB_PANEL,
ADDON_VNC_CONSOLE, ADDON_MONITORING_STACK\n\n- Profile defaults:
/etc/debvisor-addons.d/*.conf\n- First boot runs bootstrap-addons.ymllocally
to apply
addon
roles\n\n## Dry Run\n\nRundebvisor-firstboot.sh --dry-runto log intended
actions without
modifying\nusers, disks, or services.\n\n## Improvements and Operational
Excellence\n\n-
Phase 1
(Complete): Documentation and configuration hardening; systemd units,\n\n
directory
READMEs,
deployment checklists, ZFS sizing guidance\n\n- Phase 2 (Complete): Shared bash
library,
validation
scripts, CI workflow\n\n.github/workflows/validate-syntax.yml, component
validator\n
opt/validate-components.sh\n\n- Phase 3 (Planned): gRPC service, web panel
with
hardening,
integration tests,\n\n advanced monitoring\n\n## Contributing\n\n- Propose doc
changes in
docs/\n-
Use the shared library debvisor-lib.shin new scripts\n- Support--dry-run,
--check,
--verbose, and --log-fileflags\n- Include robust error handling and audit
logging\n-
Keep
scripts idempotent and non-destructive\n- Run validation before
submitting:opt/validate-components.sh\n\n## Roadmap (High Level)\n\n- Cluster
expansion
scripts
(Ceph and Kubernetes)\n- Ceph CSI and ZFS LocalPV Helm charts under
docker/addons/\n-
Metrics stack
(Prometheus and Grafana)\n- Upgrade orchestration (Ansible playbooks)\n\n## Rate
Limiting\n\n- Web
Panel (Flask): set RATELIMIT_DEFAULTand use@limiter.limitper route\n- RPC
Server
(gRPC):
configure rate limits in/etc/debvisor/rpc/config.json;\n\n implemented by
RateLimitingInterceptorinopt/services/rpc/server.py\n\n## License\n\nApache
License
Version 2.0,
January 2004 — see license.md.\n\n## Monitoring\n\n- Dashboards: see
docs/monitoring-health-detail.md for Prometheus and Grafana\n\n setup using
/health/detail\n\n-
Metrics: expose Prometheus metrics at /metrics\n