Adds docs.
This commit is contained in:
103
README.md
Normal file
103
README.md
Normal file
@@ -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
|
||||
171
docs/DEVELOPER.md
Normal file
171
docs/DEVELOPER.md
Normal file
@@ -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
|
||||
356
docs/MAINTAINER.md
Normal file
356
docs/MAINTAINER.md
Normal file
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user