mirror of
https://github.com/lordmathis/llamactl.git
synced 2025-11-06 09:04:27 +00:00
Create initial documentation structure
This commit is contained in:
464
docs/development/building.md
Normal file
464
docs/development/building.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user