From 09e64acad9e38220ce2de5e76db1b6bdf9bd7afc Mon Sep 17 00:00:00 2001 From: Paul Payne Date: Sat, 11 Oct 2025 18:13:37 +0000 Subject: [PATCH] Adds docs. --- README.md | 103 +++++++++++++ docs/DEVELOPER.md | 171 ++++++++++++++++++++++ docs/MAINTAINER.md | 356 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 630 insertions(+) create mode 100644 README.md create mode 100644 docs/DEVELOPER.md create mode 100644 docs/MAINTAINER.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..fa4e6a3 --- /dev/null +++ b/README.md @@ -0,0 +1,103 @@ +# Wild Central + +## Installation + +### APT Repository (Recommended) + +```bash +# Download and install GPG key +curl -fsSL https://mywildcloud.org/apt/wild-cloud-central.gpg | sudo tee /usr/share/keyrings/wild-cloud-central-archive-keyring.gpg > /dev/null + +# Add repository (modern .sources format) +sudo tee /etc/apt/sources.list.d/wild-cloud-central.sources << 'EOF' +Types: deb +URIs: https://mywildcloud.org/apt +Suites: stable +Components: main +Signed-By: /usr/share/keyrings/wild-cloud-central-archive-keyring.gpg +EOF + +# Update and install +sudo apt update +sudo apt install wild-cloud-central +``` + +### Manual Installation + +Download the latest `.deb` package from the [releases page](https://github.com/wildcloud/wild-central/releases) and install: + +```bash +sudo dpkg -i wild-cloud-central_*.deb +sudo apt-get install -f # Fix any dependency issues +``` + +## Quick Start + +1. **Configure the service** (optional): + + ```bash + sudo cp /etc/wild-cloud-central/config.yaml.example /etc/wild-cloud-central/config.yaml + sudo nano /etc/wild-cloud-central/config.yaml + ``` + +2. **Start the service**: + + ```bash + sudo systemctl enable wild-cloud-central + sudo systemctl start wild-cloud-central + ``` + +3. **Access the web interface**: + Open http://your-server-ip in your browser + +## Features + +- **Web Management Interface** - Browser-based configuration and monitoring +- **REST API** - JSON API for programmatic management +- **DNS/DHCP Services** - Integrated dnsmasq configuration management +- **PXE Boot Support** - Automatic Talos Linux asset downloading and serving + +## Basic Configuration + +The service uses `/etc/wild-cloud-central/config.yaml` for configuration: + +```yaml +cloud: + domain: "wildcloud.local" + dns: + ip: "192.168.8.50" # Your server's IP + dhcpRange: "192.168.8.100,192.168.8.200" + +cluster: + endpointIp: "192.168.8.60" # Talos cluster endpoint + nodes: + talos: + version: "v1.8.0" # Talos version to use +``` + +## Service Management + +```bash +# Check status +sudo systemctl status wild-cloud-central + +# View logs +sudo journalctl -u wild-cloud-central -f + +# Restart service +sudo systemctl restart wild-cloud-central + +# Stop service +sudo systemctl stop wild-cloud-central +``` + +## Support + +- **Documentation**: See `docs/` directory for detailed guides +- **Issues**: Report problems on the project issue tracker +- **API Reference**: Available at `/api/v1/` endpoints when service is running + +## Documentation + +- [Developer Guide](docs/DEVELOPER.md) - Development setup, testing, and API reference +- [Maintainer Guide](docs/MAINTAINER.md) - Package management and repository deployment diff --git a/docs/DEVELOPER.md b/docs/DEVELOPER.md new file mode 100644 index 0000000..8cc35ad --- /dev/null +++ b/docs/DEVELOPER.md @@ -0,0 +1,171 @@ +# Developer Guide + +This guide covers development, testing, and local building of Wild Cloud Central. + +## Development Setup + +### Prerequisites + +- Go 1.21+ +- Docker (for testing) +- make + +```bash +sudo apt update +sudo apt install make direnv +echo 'eval "$(direnv hook bash)"' >> $HOME/.bashrc +source $HOME/.bashrc + +# Node.js and pnpm setup +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash +source $HOME/.bashrc +nvm install --lts + +curl -fsSL https://get.pnpm.io/install.sh | sh - +source $HOME/.bashrc +pnpm install -g @anthropic-ai/claude-code + +# Golang setup +wget https://go.dev/dl/go1.24.5.linux-arm64.tar.gz +sudo tar -C /usr/local -xzf ./go1.24.5.linux-arm64.tar.gz +echo 'export PATH="$PATH:$HOME/go/bin:/usr/local/go/bin"' >> $HOME/.bashrc +source $HOME/.bashrc +rm ./go1.24.5.linux-arm64.tar.gz +go install -v github.com/go-delve/delve/cmd/dlv@latest + +# Python setup +curl -LsSf https://astral.sh/uv/install.sh | sh +source $HOME/.local/bin/env +uv sync + +# Runtime dependencies +./scripts/install-wild-cloud-dependencies.sh + +# App +cd app && pnpm install && cd .. +# Daemon +cd daemon && go mod tidy && cd .. +# CLI +cd cli && go mod tidy && cd .. +``` + +### Building Locally + +1. **Build the application:** + ```bash + make build + ``` + +2. **Run locally:** + ```bash + make run + ``` + +3. **Development with auto-reload:** + ```bash + make dev + ``` + +### Dependencies +- **gorilla/mux** - HTTP routing +- **gopkg.in/yaml.v3** - YAML configuration parsing + +## API Reference + +### Endpoints + +- `GET /api/v1/health` - Service health check +- `GET /api/v1/config` - Get current configuration +- `PUT /api/v1/config` - Update configuration +- `GET /api/v1/dnsmasq/config` - Generate dnsmasq configuration +- `POST /api/v1/dnsmasq/restart` - Restart dnsmasq service +- `POST /api/v1/pxe/assets` - Download/update PXE boot assets + +### Configuration + +Edit `config.yaml` to customize your deployment: + +```yaml +server: + port: 5055 + host: "0.0.0.0" + +cloud: + domain: "wildcloud.local" + dns: + ip: "192.168.8.50" + dhcpRange: "192.168.8.100,192.168.8.200" + +cluster: + endpointIp: "192.168.8.60" + nodes: + talos: + version: "v1.8.0" +``` + +## Testing + +> ⚠️ **Note**: These Docker scripts test the installation process only. In production, use `sudo apt install wild-cloud-central` and manage via systemd. + +Choose the testing approach that fits your needs: + +### 1. Automated Verification - `./tests/integration/test-docker.sh` +- **When to use**: Verify the installation works correctly +- **What it does**: Builds .deb package, installs it, tests all endpoints automatically +- **Best for**: CI/CD, quick verification that everything works + +### 2. Background Testing - `./tests/integration/start-background.sh` / `./tests/integration/stop-background.sh` +- **When to use**: You want to test APIs while doing other work +- **What it does**: Starts services silently in background, gives you your terminal back +- **Example workflow**: Start services, test in another terminal, stop when done +```bash +./tests/integration/start-background.sh # Services start, terminal returns immediately +curl http://localhost:9081/api/v1/health # Test in same or different terminal +# Continue working while services run... +./tests/integration/stop-background.sh # Clean shutdown when finished +``` + +### 3. Interactive Development - `./tests/integration/start-interactive.sh` +- **When to use**: You want to see what's happening as you test +- **What it does**: Starts services with live logs, takes over your terminal +- **Example workflow**: Start services, watch logs in real-time, Ctrl+C to stop +```bash +./tests/integration/start-interactive.sh # Services start, shows live logs +# You see all HTTP requests, errors, debug info in real-time +# Press Ctrl+C when done - terminal is "busy" until then +``` + +### 4. Shell Access - `./tests/integration/debug-container.sh` +- **When to use**: Deep debugging, manual service control, file inspection +- **What it does**: Drops you into the container shell +- **Best for**: Investigating issues, manually starting/stopping services + +### Test Access Points +All services bind to localhost (127.0.0.1) on non-standard ports, so they won't interfere with your local services: + +- Management UI: http://localhost:9080 +- API: http://localhost:9081 +- DNS: localhost:9053 (UDP) - test with `dig @localhost -p 9053 wildcloud.local` +- DHCP: localhost:9067 (UDP) +- TFTP: localhost:9069 (UDP) +- Container logs: `docker logs wild-central-bg` + +## Architecture + +This service replaces the original bash script implementation with: +- Unified configuration management +- Real-time dnsmasq configuration generation +- Integrated Talos factory asset downloading +- Web-based management interface +- Proper systemd service integration + +## Make Targets + +- `make build` - Build the Go binary +- `make run` - Run the application locally +- `make dev` - Start development server +- `make test` - Run Go tests +- `make clean` - Clean build artifacts +- `make deb` - Create Debian package +- `make repo` - Build APT repository +- `make deploy-repo` - Deploy repository to server \ No newline at end of file diff --git a/docs/MAINTAINER.md b/docs/MAINTAINER.md new file mode 100644 index 0000000..e31d118 --- /dev/null +++ b/docs/MAINTAINER.md @@ -0,0 +1,356 @@ +# Maintainer Guide + +This guide covers the complete build pipeline, package creation, repository management, and deployment for Wild Cloud Central. + +## Build System Overview + +Wild Cloud Central uses a modern, multi-stage build system with clear separation of concerns: + +1. **Build** - Compile binaries with version information +2. **Package** - Create .deb packages for distribution +3. **Repository** - Build APT repository with GPG signing +4. **Deploy** - Upload to production server + +### Quick Reference + +```bash +make help # Show all available targets +make version # Show build information +make check # Run quality checks (fmt + vet + test) +make clean # Remove all build artifacts +``` + +## Development Workflow + +### Code Quality Pipeline + +Before building, always run quality checks: + +```bash +make check +``` + +This runs: +- `go fmt` - Code formatting +- `go vet` - Static analysis +- `go test` - Unit tests + +### Building Binaries + +```bash +# Build for current architecture +make build + +# Build for specific architecture +make build-amd64 +make build-arm64 + +# Build all architectures +make build-all +``` + +Binaries include version information from Git and build metadata. + +## Package Management + +### Creating Debian Packages + +```bash +# Create package for current architecture +make package + +# Create packages for specific architectures +make package-amd64 +make package-arm64 + +# Create all packages +make package-all + +# Legacy alias (deprecated) +make deb +``` + +This creates `build/wild-cloud-central_0.1.0_amd64.deb` with: + +- Binary installed to `/usr/bin/wild-cloud-central` +- Systemd service file +- Configuration template +- Web interface files +- Nginx configuration + +### Package Structure + +The .deb package includes: + +- `/usr/bin/wild-cloud-central` - Main binary +- `/etc/systemd/system/wild-cloud-central.service` - Systemd service +- `/etc/wild-cloud-central/config.yaml.example` - Configuration template +- `/var/www/html/wild-central/` - Web interface files +- `/etc/nginx/sites-available/wild-central` - Nginx configuration + +### Post-installation Setup + +The package automatically: + +- Creates `wildcloud` system user +- Creates required directories with proper permissions +- Configures nginx +- Enables systemd service +- Sets up file ownership + +## APT Repository Management + +### Building Repository + +```bash +make repo +``` + +This uses `./scripts/build-apt-repository.sh` with **aptly** to create a professional APT repository in `dist/repositories/apt/`: + +- Complete repository metadata with all hash types (MD5, SHA1, SHA256, SHA512) +- Contents files for enhanced package discovery +- Multiple compression formats (.gz, .bz2) for compatibility +- Proper GPG signing with modern InRelease format +- Industry-standard repository structure following Debian conventions + +The repository includes: +- `pool/main/w/wild-cloud-central/` - Package files +- `dists/stable/main/binary-amd64/` - Metadata and package lists +- `dists/stable/main/binary-arm64/` - ARM64 package metadata +- `dists/stable/InRelease` - Modern GPG signature (preferred) +- `dists/stable/Release.asc` - Traditional GPG signature compatibility +- `wild-cloud-central.gpg` - GPG public key for users + +### Aptly Configuration + +The build system automatically configures aptly to: +- Use strong RSA 4096-bit GPG keys +- Generate complete security metadata to prevent "weak security information" warnings +- Create Contents files for better package discovery +- Support multiple architectures (amd64, arm64) + +### GPG Key Management + +#### First-time Setup + +```bash +./scripts/setup-gpg.sh +``` + +This creates: + +- 4096-bit RSA GPG key pair +- Public key exported as `dist/wild-cloud-central.gpg` (binary format for APT) +- Key configured for 2-year expiration +- Automatic aptly configuration for repository signing + +#### Key Renewal + +When the key expires, regenerate with: + +```bash +gpg --delete-secret-keys "Wild Cloud Central" +gpg --delete-keys "Wild Cloud Central" +make clean # Remove old GPG key and aptly state +./scripts/setup-gpg.sh +``` + +### Repository Deployment + +1. **Configure server details** in `scripts/deploy-apt-repository.sh`: + + ```bash + SERVER="user@mywildcloud.org" + REMOTE_PATH="/var/www/html/apt" + ``` + +2. **Deploy repository**: + + ```bash + make deploy-repo + ``` + +This uploads the aptly-generated repository with complete security metadata, eliminating "weak security information" warnings and ensuring compatibility with modern APT security standards. + +This uploads: + +- Complete repository structure to server +- GPG public key for user verification +- Proper file permissions and structure + +### Server Requirements + +The target server needs: + +- Web server (nginx/apache) serving `/var/www/html/apt` +- HTTPS support for `https://mywildcloud.org/apt` +- SSH access for deployment + +### Repository Structure + +``` +/var/www/html/apt/ +├── dists/ +│ └── stable/ +│ ├── InRelease (modern GPG signature) +│ ├── Release +│ ├── Release.asc +│ └── main/ +│ ├── binary-amd64/ +│ │ ├── Packages +│ │ ├── Packages.gz +│ │ └── Release +│ └── binary-arm64/ +│ ├── Packages +│ ├── Packages.gz +│ └── Release +├── pool/ +│ └── main/ +│ └── w/ +│ └── wild-cloud-central/ +│ ├── wild-cloud-central_0.1.0_amd64.deb +│ └── wild-cloud-central_0.1.0_arm64.deb +├── Contents-amd64 (enhanced package discovery) +├── Contents-amd64.gz +└── wild-cloud-central.gpg (binary format for APT) +``` + +## Release Process + +### Standard Release + +1. **Update version** in `Makefile`: + + ```makefile + VERSION := 0.2.0 + ``` + +2. **Quality assurance and build**: + + ```bash + make clean # Clean previous builds + make check # Run quality checks + make build-all # Build all architectures + ./tests/integration/test-docker.sh # Integration tests + ``` + +3. **Create packages and repository**: + + ```bash + make package-all # Create .deb packages + make repo # Build APT repository + ``` + +4. **Deploy**: + + ```bash + make deploy-repo # Upload to server + ``` + +### Quick Development Release + +For amd64-only development releases: + +```bash +make clean && make check && make repo && make deploy-repo +``` + +### Multi-architecture Release + +For production releases with full architecture support: + +```bash +make clean && make check && make package-all && make repo && make deploy-repo +``` + +5. **Verify deployment**: + + ```bash + curl -I https://mywildcloud.org/apt/dists/stable/Release + curl -I https://mywildcloud.org/apt/wild-cloud-central.gpg + ``` + +## User Installation + +Users install packages using the modern APT `.sources` format: + +```bash +# Download and install GPG key (binary format) +curl -fsSL https://mywildcloud.org/apt/wild-cloud-central.gpg | \ + sudo tee /usr/share/keyrings/wild-cloud-central-archive-keyring.gpg > /dev/null + +# Add repository using modern .sources format +sudo tee /etc/apt/sources.list.d/wild-cloud-central.sources << 'EOF' +Types: deb +URIs: https://mywildcloud.org/apt +Suites: stable +Components: main +Signed-By: /usr/share/keyrings/wild-cloud-central-archive-keyring.gpg +EOF + +# Update and install +sudo apt update +sudo apt install wild-cloud-central +``` + +### Legacy Installation (Deprecated) + +The old `.list` format still works but generates warnings: + +```bash +# Download GPG key (requires conversion) +curl -fsSL https://mywildcloud.org/apt/wild-cloud-central.gpg | \ + sudo gpg --dearmor -o /usr/share/keyrings/wild-cloud-central.gpg + +# Add repository using legacy format (deprecated) +echo 'deb [signed-by=/usr/share/keyrings/wild-cloud-central.gpg] https://mywildcloud.org/apt stable main' | \ + sudo tee /etc/apt/sources.list.d/wild-cloud-central.list +``` + +## Troubleshooting + +### GPG Issues + +- **"no default secret key"**: Run `./scripts/setup-gpg.sh` +- **Key conflicts**: Delete existing keys before recreating +- **Permission errors**: Ensure `~/.gnupg` has correct permissions (700) + +### Repository Issues + +- **Package not found**: Verify `dpkg-scanpackages` output +- **Signature verification failed**: Regenerate GPG key and re-sign +- **404 errors**: Check web server configuration and file permissions +- **Legacy format warnings**: Use modern `.sources` format instead of `.list` +- **GPG key mismatch**: Ensure deployed key matches signing key + +### Deployment Issues + +- **SSH failures**: Verify server credentials in `deploy-repo.sh` +- **Permission denied**: Ensure target directory is writable +- **rsync errors**: Check network connectivity and paths + +## Monitoring + +### Service Health + +```bash +curl https://mywildcloud.org/apt/dists/stable/Release +curl https://mywildcloud.org/apt/wild-cloud-central.gpg +``` + +### Package Statistics + +Monitor download statistics through web server logs: + +```bash +grep "wild-cloud-central.*\.deb" /var/log/nginx/access.log | wc -l +``` + +### Repository Integrity + +Verify signatures regularly: + +```bash +gpg --verify Release.asc Release +```