Create initial documentation structure

2025-11-06 09:04:27 +00:00 · 2025-08-31 14:27:00 +02:00
parent 7675271370
commit bd31c03f4a
16 changed files with 3514 additions and 0 deletions
--- a/docs/development/building.md
+++ b/docs/development/building.md
@@ -0,0 +1,464 @@
+# Building from Source
+
+This guide covers building LlamaCtl from source code for development and production deployment.
+
+## Prerequisites
+
+### Required Tools
+
+- **Go 1.24+**: Download from [golang.org](https://golang.org/dl/)
+- **Node.js 22+**: Download from [nodejs.org](https://nodejs.org/)
+- **Git**: For cloning the repository
+- **Make**: For build automation (optional)
+
+### System Requirements
+
+- **Memory**: 4GB+ RAM for building
+- **Disk**: 2GB+ free space
+- **OS**: Linux, macOS, or Windows
+
+## Quick Build
+
+### Clone and Build
+
+```bash
+# Clone the repository
+git clone https://github.com/lordmathis/llamactl.git
+cd llamactl
+
+# Build the application
+go build -o llamactl cmd/server/main.go
+```
+
+### Run
+
+```bash
+./llamactl
+```
+
+## Development Build
+
+### Setup Development Environment
+
+```bash
+# Clone repository
+git clone https://github.com/lordmathis/llamactl.git
+cd llamactl
+
+# Install Go dependencies
+go mod download
+
+# Install frontend dependencies
+cd webui
+npm ci
+cd ..
+```
+
+### Build Components
+
+```bash
+# Build backend only
+go build -o llamactl cmd/server/main.go
+
+# Build frontend only
+cd webui
+npm run build
+cd ..
+
+# Build everything
+make build
+```
+
+### Development Server
+
+```bash
+# Run backend in development mode
+go run cmd/server/main.go --dev
+
+# Run frontend dev server (separate terminal)
+cd webui
+npm run dev
+```
+
+## Production Build
+
+### Optimized Build
+
+```bash
+# Build with optimizations
+go build -ldflags="-s -w" -o llamactl cmd/server/main.go
+
+# Or use the Makefile
+make build-prod
+```
+
+### Build Flags
+
+Common build flags for production:
+
+```bash
+go build \
+  -ldflags="-s -w -X main.version=1.0.0 -X main.buildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  -trimpath \
+  -o llamactl \
+  cmd/server/main.go
+```
+
+**Flag explanations:**
+- `-s`: Strip symbol table
+- `-w`: Strip debug information
+- `-X`: Set variable values at build time
+- `-trimpath`: Remove absolute paths from binary
+
+## Cross-Platform Building
+
+### Build for Multiple Platforms
+
+```bash
+# Linux AMD64
+GOOS=linux GOARCH=amd64 go build -o llamactl-linux-amd64 cmd/server/main.go
+
+# Linux ARM64
+GOOS=linux GOARCH=arm64 go build -o llamactl-linux-arm64 cmd/server/main.go
+
+# macOS AMD64
+GOOS=darwin GOARCH=amd64 go build -o llamactl-darwin-amd64 cmd/server/main.go
+
+# macOS ARM64 (Apple Silicon)
+GOOS=darwin GOARCH=arm64 go build -o llamactl-darwin-arm64 cmd/server/main.go
+
+# Windows AMD64
+GOOS=windows GOARCH=amd64 go build -o llamactl-windows-amd64.exe cmd/server/main.go
+```
+
+### Automated Cross-Building
+
+Use the provided Makefile:
+
+```bash
+# Build all platforms
+make build-all
+
+# Build specific platform
+make build-linux
+make build-darwin
+make build-windows
+```
+
+## Build with Docker
+
+### Development Container
+
+```dockerfile
+# Dockerfile.dev
+FROM golang:1.24-alpine AS builder
+
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+RUN go build -o llamactl cmd/server/main.go
+
+FROM alpine:latest
+RUN apk --no-cache add ca-certificates
+WORKDIR /root/
+COPY --from=builder /app/llamactl .
+
+EXPOSE 8080
+CMD ["./llamactl"]
+```
+
+```bash
+# Build development image
+docker build -f Dockerfile.dev -t llamactl:dev .
+
+# Run container
+docker run -p 8080:8080 llamactl:dev
+```
+
+### Production Container
+
+```dockerfile
+# Dockerfile
+FROM node:22-alpine AS frontend-builder
+
+WORKDIR /app/webui
+COPY webui/package*.json ./
+RUN npm ci
+
+COPY webui/ ./
+RUN npm run build
+
+FROM golang:1.24-alpine AS backend-builder
+
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+COPY --from=frontend-builder /app/webui/dist ./webui/dist
+
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -ldflags="-s -w" \
+    -o llamactl \
+    cmd/server/main.go
+
+FROM alpine:latest
+
+RUN apk --no-cache add ca-certificates tzdata
+RUN adduser -D -s /bin/sh llamactl
+
+WORKDIR /home/llamactl
+COPY --from=backend-builder /app/llamactl .
+RUN chown llamactl:llamactl llamactl
+
+USER llamactl
+EXPOSE 8080
+
+CMD ["./llamactl"]
+```
+
+## Advanced Build Options
+
+### Static Linking
+
+For deployments without external dependencies:
+
+```bash
+CGO_ENABLED=0 go build \
+  -ldflags="-s -w -extldflags '-static'" \
+  -o llamactl-static \
+  cmd/server/main.go
+```
+
+### Debug Build
+
+Build with debug information:
+
+```bash
+go build -gcflags="all=-N -l" -o llamactl-debug cmd/server/main.go
+```
+
+### Race Detection Build
+
+Build with race detection (development only):
+
+```bash
+go build -race -o llamactl-race cmd/server/main.go
+```
+
+## Build Automation
+
+### Makefile
+
+```makefile
+# Makefile
+VERSION := $(shell git describe --tags --always --dirty)
+BUILD_TIME := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
+LDFLAGS := -s -w -X main.version=$(VERSION) -X main.buildTime=$(BUILD_TIME)
+
+.PHONY: build clean test install
+
+build:
+	@echo "Building LlamaCtl..."
+	@cd webui && npm run build
+	@go build -ldflags="$(LDFLAGS)" -o llamactl cmd/server/main.go
+
+build-prod:
+	@echo "Building production binary..."
+	@cd webui && npm run build
+	@CGO_ENABLED=0 go build -ldflags="$(LDFLAGS)" -trimpath -o llamactl cmd/server/main.go
+
+build-all: build-linux build-darwin build-windows
+
+build-linux:
+	@GOOS=linux GOARCH=amd64 go build -ldflags="$(LDFLAGS)" -o dist/llamactl-linux-amd64 cmd/server/main.go
+	@GOOS=linux GOARCH=arm64 go build -ldflags="$(LDFLAGS)" -o dist/llamactl-linux-arm64 cmd/server/main.go
+
+build-darwin:
+	@GOOS=darwin GOARCH=amd64 go build -ldflags="$(LDFLAGS)" -o dist/llamactl-darwin-amd64 cmd/server/main.go
+	@GOOS=darwin GOARCH=arm64 go build -ldflags="$(LDFLAGS)" -o dist/llamactl-darwin-arm64 cmd/server/main.go
+
+build-windows:
+	@GOOS=windows GOARCH=amd64 go build -ldflags="$(LDFLAGS)" -o dist/llamactl-windows-amd64.exe cmd/server/main.go
+
+test:
+	@go test ./...
+
+clean:
+	@rm -f llamactl llamactl-*
+	@rm -rf dist/
+
+install: build
+	@cp llamactl $(GOPATH)/bin/llamactl
+```
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/build.yml
+name: Build
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.24'
+    
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+    
+    - name: Install dependencies
+      run: |
+        go mod download
+        cd webui && npm ci
+    
+    - name: Run tests
+      run: |
+        go test ./...
+        cd webui && npm test
+    
+    - name: Build
+      run: make build
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.24'
+    
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+    
+    - name: Build all platforms
+      run: make build-all
+    
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: binaries
+        path: dist/
+```
+
+## Build Troubleshooting
+
+### Common Issues
+
+**Go version mismatch:**
+```bash
+# Check Go version
+go version
+
+# Update Go
+# Download from https://golang.org/dl/
+```
+
+**Node.js issues:**
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Remove node_modules and reinstall
+rm -rf webui/node_modules
+cd webui && npm ci
+```
+
+**Build failures:**
+```bash
+# Clean and rebuild
+make clean
+go mod tidy
+make build
+```
+
+### Performance Issues
+
+**Slow builds:**
+```bash
+# Use build cache
+export GOCACHE=$(go env GOCACHE)
+
+# Parallel builds
+export GOMAXPROCS=$(nproc)
+```
+
+**Large binary size:**
+```bash
+# Use UPX compression
+upx --best llamactl
+
+# Analyze binary size
+go tool nm -size llamactl | head -20
+```
+
+## Deployment
+
+### System Service
+
+Create a systemd service:
+
+```ini
+# /etc/systemd/system/llamactl.service
+[Unit]
+Description=LlamaCtl Server
+After=network.target
+
+[Service]
+Type=simple
+User=llamactl
+Group=llamactl
+ExecStart=/usr/local/bin/llamactl
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+# Enable and start service
+sudo systemctl enable llamactl
+sudo systemctl start llamactl
+```
+
+### Configuration
+
+```bash
+# Create configuration directory
+sudo mkdir -p /etc/llamactl
+
+# Copy configuration
+sudo cp config.yaml /etc/llamactl/
+
+# Set permissions
+sudo chown -R llamactl:llamactl /etc/llamactl
+```
+
+## Next Steps
+
+- Configure [Installation](../getting-started/installation.md)
+- Set up [Configuration](../getting-started/configuration.md)
+- Learn about [Contributing](contributing.md)
--- a/docs/development/contributing.md
+++ b/docs/development/contributing.md
@@ -0,0 +1,373 @@
+# Contributing
+
+Thank you for your interest in contributing to LlamaCtl! This guide will help you get started with development and contribution.
+
+## Development Setup
+
+### Prerequisites
+
+- Go 1.24 or later
+- Node.js 22 or later
+- `llama-server` executable (from [llama.cpp](https://github.com/ggml-org/llama.cpp))
+- Git
+
+### Getting Started
+
+1. **Fork and Clone**
+   ```bash
+   # Fork the repository on GitHub, then clone your fork
+   git clone https://github.com/yourusername/llamactl.git
+   cd llamactl
+   
+   # Add upstream remote
+   git remote add upstream https://github.com/lordmathis/llamactl.git
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   # Go dependencies
+   go mod download
+   
+   # Frontend dependencies
+   cd webui && npm ci && cd ..
+   ```
+
+3. **Run Development Environment**
+   ```bash
+   # Start backend server
+   go run ./cmd/server
+   ```
+   
+   In a separate terminal:
+   ```bash
+   # Start frontend dev server
+   cd webui && npm run dev
+   ```
+
+## Development Workflow
+
+### Setting Up Your Environment
+
+1. **Configuration**
+   Create a development configuration file:
+   ```yaml
+   # dev-config.yaml
+   server:
+     host: "localhost"
+     port: 8080
+   logging:
+     level: "debug"
+   ```
+
+2. **Test Data**
+   Set up test models and instances for development.
+
+### Making Changes
+
+1. **Create a Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Development Commands**
+   ```bash
+   # Backend
+   go test ./... -v                    # Run tests
+   go test -race ./... -v              # Run with race detector
+   go fmt ./... && go vet ./...        # Format and vet code
+   go build ./cmd/server               # Build binary
+   
+   # Frontend (from webui/ directory)
+   npm run test                        # Run tests
+   npm run lint                        # Lint code
+   npm run type-check                  # TypeScript check
+   npm run build                       # Build for production
+   ```
+
+3. **Code Quality**
+   ```bash
+   # Run all checks before committing
+   make lint
+   make test
+   make build
+   ```
+
+## Project Structure
+
+### Backend (Go)
+
+```
+cmd/
+├── server/              # Main application entry point
+pkg/
+├── backends/           # Model backend implementations
+├── config/            # Configuration management
+├── instance/          # Instance lifecycle management
+├── manager/           # Instance manager
+├── server/            # HTTP server and routes
+├── testutil/          # Test utilities
+└── validation/        # Input validation
+```
+
+### Frontend (React/TypeScript)
+
+```
+webui/src/
+├── components/        # React components
+├── contexts/         # React contexts
+├── hooks/           # Custom hooks
+├── lib/             # Utility libraries
+├── schemas/         # Zod schemas
+└── types/           # TypeScript types
+```
+
+## Coding Standards
+
+### Go Code
+
+- Follow standard Go formatting (`gofmt`)
+- Use `go vet` and address all warnings
+- Write comprehensive tests for new functionality
+- Include documentation comments for exported functions
+- Use meaningful variable and function names
+
+Example:
+```go
+// CreateInstance creates a new model instance with the given configuration.
+// It validates the configuration and ensures the instance name is unique.
+func (m *Manager) CreateInstance(ctx context.Context, config InstanceConfig) (*Instance, error) {
+    if err := config.Validate(); err != nil {
+        return nil, fmt.Errorf("invalid configuration: %w", err)
+    }
+    
+    // Implementation...
+}
+```
+
+### TypeScript/React Code
+
+- Use TypeScript strict mode
+- Follow React best practices
+- Use functional components with hooks
+- Implement proper error boundaries
+- Write unit tests for components
+
+Example:
+```typescript
+interface InstanceCardProps {
+  instance: Instance;
+  onStart: (name: string) => Promise<void>;
+  onStop: (name: string) => Promise<void>;
+}
+
+export const InstanceCard: React.FC<InstanceCardProps> = ({
+  instance,
+  onStart,
+  onStop,
+}) => {
+  // Implementation...
+};
+```
+
+## Testing
+
+### Backend Tests
+
+```bash
+# Run all tests
+go test ./...
+
+# Run tests with coverage
+go test ./... -coverprofile=coverage.out
+go tool cover -html=coverage.out
+
+# Run specific package tests
+go test ./pkg/manager -v
+
+# Run with race detection
+go test -race ./...
+```
+
+### Frontend Tests
+
+```bash
+cd webui
+
+# Run unit tests
+npm run test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run E2E tests
+npm run test:e2e
+```
+
+### Integration Tests
+
+```bash
+# Run integration tests (requires llama-server)
+go test ./... -tags=integration
+```
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Update your branch**
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+2. **Run all tests**
+   ```bash
+   make test-all
+   ```
+
+3. **Update documentation** if needed
+
+4. **Write clear commit messages**
+   ```
+   feat: add instance health monitoring
+   
+   - Implement health check endpoint
+   - Add periodic health monitoring
+   - Update API documentation
+   
+   Fixes #123
+   ```
+
+### Submitting a PR
+
+1. **Push your branch**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+2. **Create Pull Request**
+   - Use the PR template
+   - Provide clear description
+   - Link related issues
+   - Add screenshots for UI changes
+
+3. **PR Review Process**
+   - Automated checks must pass
+   - Code review by maintainers
+   - Address feedback promptly
+   - Keep PR scope focused
+
+## Issue Guidelines
+
+### Reporting Bugs
+
+Use the bug report template and include:
+
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details (OS, Go version, etc.)
+- Relevant logs or error messages
+- Minimal reproduction case
+
+### Feature Requests
+
+Use the feature request template and include:
+
+- Clear description of the problem
+- Proposed solution
+- Alternative solutions considered
+- Implementation complexity estimate
+
+### Security Issues
+
+For security vulnerabilities:
+- Do NOT create public issues
+- Email security@llamactl.dev
+- Provide detailed description
+- Allow time for fix before disclosure
+
+## Development Best Practices
+
+### API Design
+
+- Follow REST principles
+- Use consistent naming conventions
+- Provide comprehensive error messages
+- Include proper HTTP status codes
+- Document all endpoints
+
+### Error Handling
+
+```go
+// Wrap errors with context
+if err := instance.Start(); err != nil {
+    return fmt.Errorf("failed to start instance %s: %w", instance.Name, err)
+}
+
+// Use structured logging
+log.WithFields(log.Fields{
+    "instance": instance.Name,
+    "error": err,
+}).Error("Failed to start instance")
+```
+
+### Configuration
+
+- Use environment variables for deployment
+- Provide sensible defaults
+- Validate configuration on startup
+- Support configuration file reloading
+
+### Performance
+
+- Profile code for bottlenecks
+- Use efficient data structures
+- Implement proper caching
+- Monitor resource usage
+
+## Release Process
+
+### Version Management
+
+- Use semantic versioning (SemVer)
+- Tag releases properly
+- Maintain CHANGELOG.md
+- Create release notes
+
+### Building Releases
+
+```bash
+# Build all platforms
+make build-all
+
+# Create release package
+make package
+```
+
+## Getting Help
+
+### Communication Channels
+
+- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: General questions and ideas
+- **Code Review**: PR comments and feedback
+
+### Development Questions
+
+When asking for help:
+
+1. Check existing documentation
+2. Search previous issues
+3. Provide minimal reproduction case
+4. Include relevant environment details
+
+## Recognition
+
+Contributors are recognized in:
+
+- CONTRIBUTORS.md file
+- Release notes
+- Documentation credits
+- Annual contributor highlights
+
+Thank you for contributing to LlamaCtl!