From bdc03c5658ef67440ce5b8934f890ee2e2be6460 Mon Sep 17 00:00:00 2001 From: Snider Date: Thu, 29 Jan 2026 22:24:54 +0000 Subject: [PATCH] docs: add Deploy section with LinuxKit VMs, templates, and Docker - Add /deploy/ section with overview, navigation, and sidebar - LinuxKit VMs: running images, managing VMs, building images - Templates: pre-configured VM templates (core-dev, server-php, edge-node) - Docker: compose, multi-stage builds, orchestration guides - Update nav dropdown with Deploy items Co-Authored-By: Claude Opus 4.5 --- docs/.vitepress/config.js | 20 +++- docs/deploy/docker.md | 208 +++++++++++++++++++++++++++++++++++ docs/deploy/index.md | 67 ++++++++++++ docs/deploy/linuxkit.md | 168 +++++++++++++++++++++++++++++ docs/deploy/templates.md | 220 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 682 insertions(+), 1 deletion(-) create mode 100644 docs/deploy/docker.md create mode 100644 docs/deploy/index.md create mode 100644 docs/deploy/linuxkit.md create mode 100644 docs/deploy/templates.md diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 56c4941..5a6904f 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -79,7 +79,12 @@ export default defineConfig({ { text: 'Deploy', activeMatch: '/deploy/', - items: [] + items: [ + { text: 'Overview', link: '/deploy/' }, + { text: 'LinuxKit VMs', link: '/deploy/linuxkit' }, + { text: 'Templates', link: '/deploy/templates' }, + { text: 'Docker', link: '/deploy/docker' } + ] }, { text: 'Packages', @@ -114,6 +119,19 @@ export default defineConfig({ } ], + // Deploy section + '/deploy/': [ + { + text: 'Deploy', + items: [ + { text: 'Overview', link: '/deploy/' }, + { text: 'LinuxKit VMs', link: '/deploy/linuxkit' }, + { text: 'Templates', link: '/deploy/templates' }, + { text: 'Docker', link: '/deploy/docker' } + ] + } + ], + // Auto-discovered package sidebars (php, go, admin, api, mcp, etc.) ...packagesSidebar, diff --git a/docs/deploy/docker.md b/docs/deploy/docker.md new file mode 100644 index 0000000..832ebea --- /dev/null +++ b/docs/deploy/docker.md @@ -0,0 +1,208 @@ +# Docker Deployment + +Deploy containerised applications with Docker, Docker Compose, and container orchestrators. + +## Building Images + +Build Docker images with `core build`: + +```bash +# Auto-detect Dockerfile and build +core build --type docker + +# Custom image name +core build --type docker --image ghcr.io/myorg/myapp + +# Build and push to registry +core build --type docker --image ghcr.io/myorg/myapp --push +``` + +## Docker Compose + +### Basic Setup + +`docker-compose.yml`: + +```yaml +version: '3.8' + +services: + app: + image: ghcr.io/myorg/myapp:latest + ports: + - "8080:8080" + environment: + - APP_ENV=production + - DATABASE_URL=postgres://db:5432/myapp + depends_on: + - db + - redis + + db: + image: postgres:15 + volumes: + - postgres_data:/var/lib/postgresql/data + environment: + - POSTGRES_DB=myapp + - POSTGRES_PASSWORD_FILE=/run/secrets/db_password + secrets: + - db_password + + redis: + image: redis:7-alpine + volumes: + - redis_data:/data + +volumes: + postgres_data: + redis_data: + +secrets: + db_password: + file: ./secrets/db_password.txt +``` + +### Deploy + +```bash +# Start services +docker compose up -d + +# View logs +docker compose logs -f app + +# Scale horizontally +docker compose up -d --scale app=3 + +# Update to new version +docker compose pull && docker compose up -d +``` + +## Multi-Stage Builds + +Optimised Dockerfile for PHP applications: + +```dockerfile +# Build stage +FROM composer:2 AS deps +WORKDIR /app +COPY composer.json composer.lock ./ +RUN composer install --no-dev --no-scripts --prefer-dist + +# Production stage +FROM dunglas/frankenphp:latest +WORKDIR /app + +COPY --from=deps /app/vendor ./vendor +COPY . . + +RUN composer dump-autoload --optimize + +EXPOSE 8080 +CMD ["frankenphp", "run", "--config", "/etc/caddy/Caddyfile"] +``` + +## Health Checks + +Add health checks for orchestrator integration: + +```dockerfile +HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ + CMD curl -f http://localhost:8080/health || exit 1 +``` + +Or in docker-compose: + +```yaml +services: + app: + image: myapp:latest + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080/health"] + interval: 30s + timeout: 3s + retries: 3 + start_period: 5s +``` + +## Environment Configuration + +### Using .env Files + +```yaml +services: + app: + image: myapp:latest + env_file: + - .env + - .env.local +``` + +### Environment Variables + +| Variable | Description | +|----------|-------------| +| `APP_ENV` | Environment (production, staging) | +| `APP_DEBUG` | Enable debug mode | +| `DATABASE_URL` | Database connection string | +| `REDIS_URL` | Redis connection string | +| `LOG_LEVEL` | Logging verbosity | + +## Registry Authentication + +### GitHub Container Registry + +```bash +# Login +echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin + +# Push +docker push ghcr.io/myorg/myapp:latest +``` + +### AWS ECR + +```bash +# Login +aws ecr get-login-password --region eu-west-1 | \ + docker login --username AWS --password-stdin 123456789.dkr.ecr.eu-west-1.amazonaws.com + +# Push +docker push 123456789.dkr.ecr.eu-west-1.amazonaws.com/myapp:latest +``` + +## Orchestration + +### Docker Swarm + +```bash +# Initialise swarm +docker swarm init + +# Deploy stack +docker stack deploy -c docker-compose.yml myapp + +# Scale service +docker service scale myapp_app=5 + +# Rolling update +docker service update --image myapp:v2 myapp_app +``` + +### Kubernetes + +Generate Kubernetes manifests from Compose: + +```bash +# Using kompose +kompose convert -f docker-compose.yml + +# Apply to cluster +kubectl apply -f . +``` + +## See Also + +- [Docker Publisher](/publish/docker) - Push images to registries +- [Build Command](/build/cli/build/) - Build Docker images +- [LinuxKit](linuxkit) - VM-based deployment diff --git a/docs/deploy/index.md b/docs/deploy/index.md new file mode 100644 index 0000000..0d316fd --- /dev/null +++ b/docs/deploy/index.md @@ -0,0 +1,67 @@ +# Deploy + +Deploy applications to VMs, containers, and cloud infrastructure. + +## Deployment Options + +| Target | Description | Use Case | +|--------|-------------|----------| +| [LinuxKit](linuxkit) | Lightweight immutable VMs | Production servers, edge nodes | +| [Templates](templates) | Pre-configured VM images | Quick deployment, dev environments | +| [Docker](docker) | Container orchestration | Kubernetes, Swarm, ECS | + +## Quick Start + +### Run a Production Server + +```bash +# Build and run from template +core vm run --template server-php --var SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" + +# Or run a pre-built image +core vm run -d --memory 4096 --cpus 4 server.iso +``` + +### Deploy to Docker + +```bash +# Build and push image +core build --type docker --image ghcr.io/myorg/myapp --push + +# Deploy with docker-compose +docker compose up -d +``` + +## Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ Build Phase │ +│ core build → Docker images, LinuxKit ISOs, binaries │ +└─────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ Publish Phase │ +│ core ci → GitHub, Docker Hub, GHCR, Homebrew, etc. │ +└─────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ Deploy Phase │ +│ core vm → LinuxKit VMs, templates, orchestration │ +└─────────────────────────────────────────────────────────┘ +``` + +## CLI Commands + +| Command | Description | +|---------|-------------| +| `core vm run` | Run a LinuxKit image or template | +| `core vm ps` | List running VMs | +| `core vm stop` | Stop a VM | +| `core vm logs` | View VM logs | +| `core vm exec` | Execute command in VM | +| `core vm templates` | Manage LinuxKit templates | + +See the [CLI Reference](/build/cli/vm/) for full command documentation. diff --git a/docs/deploy/linuxkit.md b/docs/deploy/linuxkit.md new file mode 100644 index 0000000..cbd4cbd --- /dev/null +++ b/docs/deploy/linuxkit.md @@ -0,0 +1,168 @@ +# LinuxKit VMs + +Deploy applications using lightweight, immutable LinuxKit VMs. VMs run using QEMU or HyperKit depending on your system. + +## Running VMs + +### From Image File + +Run pre-built images in `.iso`, `.qcow2`, `.vmdk`, or `.raw` format: + +```bash +# Run ISO image +core vm run server.iso + +# Run with more resources +core vm run -d --memory 4096 --cpus 4 server.qcow2 + +# Custom SSH port +core vm run --ssh-port 2223 server.iso +``` + +### From Template + +Build and run from a LinuxKit template in one command: + +```bash +# Run template with SSH key +core vm run --template server-php --var SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" + +# Multiple variables +core vm run --template server-php \ + --var SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" \ + --var DOMAIN=example.com +``` + +## Options + +| Flag | Description | Default | +|------|-------------|---------| +| `--template` | Run from a LinuxKit template | - | +| `--var` | Template variable (KEY=VALUE) | - | +| `--name` | VM name | auto | +| `--memory` | Memory in MB | 1024 | +| `--cpus` | CPU count | 1 | +| `--ssh-port` | SSH port for exec | 2222 | +| `-d` | Detached mode (background) | false | + +## Managing VMs + +### List Running VMs + +```bash +# Show running VMs +core vm ps + +# Include stopped VMs +core vm ps -a +``` + +Output: +``` +ID NAME IMAGE STATUS STARTED PID +abc12345 myvm server-php.qcow2 running 5m 12345 +def67890 devbox core-dev.iso stopped 2h - +``` + +### Stop a VM + +```bash +# Full ID +core vm stop abc12345678 + +# Partial ID match +core vm stop abc1 +``` + +### View Logs + +```bash +# View logs +core vm logs abc12345 + +# Follow logs (like tail -f) +core vm logs -f abc12345 +``` + +### Execute Commands + +Run commands in a VM via SSH: + +```bash +# List files +core vm exec abc12345 ls -la + +# Check services +core vm exec abc12345 systemctl status php-fpm + +# Open interactive shell +core vm exec abc12345 /bin/sh +``` + +## Building Images + +Build LinuxKit images with `core build`: + +```bash +# Build ISO from config +core build --type linuxkit --config .core/linuxkit/server.yml + +# Build QCOW2 for QEMU/KVM +core build --type linuxkit --config .core/linuxkit/server.yml --format qcow2-bios + +# Build for multiple platforms +core build --type linuxkit --targets linux/amd64,linux/arm64 +``` + +### Output Formats + +| Format | Description | Use Case | +|--------|-------------|----------| +| `iso-bios` | Bootable ISO | Physical servers, legacy VMs | +| `qcow2-bios` | QEMU/KVM image | Linux hypervisors | +| `raw` | Raw disk image | Cloud providers | +| `vmdk` | VMware image | VMware ESXi | +| `vhd` | Hyper-V image | Windows Server | + +## LinuxKit Configuration + +Example `.core/linuxkit/server.yml`: + +```yaml +kernel: + image: linuxkit/kernel:5.15 + cmdline: "console=tty0" + +init: + - linuxkit/init:v0.8 + - linuxkit/runc:v0.8 + +onboot: + - name: sysctl + image: linuxkit/sysctl:v0.8 + - name: dhcpcd + image: linuxkit/dhcpcd:v0.8 + command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf"] + +services: + - name: sshd + image: linuxkit/sshd:v0.8 + - name: php + image: dunglas/frankenphp:latest + +files: + - path: /etc/ssh/authorized_keys + contents: | + {{ .SSH_KEY }} + - path: /etc/myapp/config.yaml + contents: | + server: + port: 8080 + domain: {{ .DOMAIN }} +``` + +## See Also + +- [Templates](templates) - Pre-configured VM templates +- [LinuxKit Publisher](/publish/linuxkit) - Publish LinuxKit images +- [CLI Reference](/build/cli/vm/) - Full VM command documentation diff --git a/docs/deploy/templates.md b/docs/deploy/templates.md new file mode 100644 index 0000000..14e7e58 --- /dev/null +++ b/docs/deploy/templates.md @@ -0,0 +1,220 @@ +# Templates + +Pre-configured LinuxKit templates for common deployment scenarios. + +## Available Templates + +| Template | Description | Platforms | +|----------|-------------|-----------| +| `core-dev` | Full development environment with 100+ tools | linux/amd64, linux/arm64 | +| `server-php` | FrankenPHP production server | linux/amd64, linux/arm64 | +| `edge-node` | Minimal edge deployment | linux/amd64, linux/arm64 | + +## Using Templates + +### List Templates + +```bash +core vm templates list +``` + +Output: +``` +Available Templates: + + core-dev + Full development environment with 100+ tools + Platforms: linux/amd64, linux/arm64 + + server-php + FrankenPHP production server + Platforms: linux/amd64, linux/arm64 + + edge-node + Minimal edge deployment + Platforms: linux/amd64, linux/arm64 +``` + +### Show Template Details + +```bash +core vm templates show server-php +``` + +Output: +``` +Template: server-php + +Description: FrankenPHP production server + +Platforms: + - linux/amd64 + - linux/arm64 + +Formats: + - iso + - qcow2 + +Services: + - sshd + - frankenphp + - php-fpm + +Size: ~800MB +``` + +### Show Template Variables + +```bash +core vm templates vars server-php +``` + +Output: +``` +Variables for server-php: + SSH_KEY (required) SSH public key + DOMAIN (optional) Server domain name + MEMORY (optional) Memory in MB (default: 2048) + CPUS (optional) CPU count (default: 2) +``` + +### Run Template + +```bash +# With required variables +core vm run --template server-php --var SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" + +# With all variables +core vm run --template server-php \ + --var SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" \ + --var DOMAIN=example.com \ + --var MEMORY=4096 +``` + +## Template Locations + +Templates are searched in order: + +1. `.core/linuxkit/` - Project-specific templates +2. `~/.core/templates/` - User templates +3. Built-in templates + +## Creating Templates + +Create a LinuxKit YAML file in `.core/linuxkit/`: + +### Development Template + +`.core/linuxkit/dev.yml`: + +```yaml +kernel: + image: linuxkit/kernel:5.15 + cmdline: "console=tty0" + +init: + - linuxkit/init:v0.8 + - linuxkit/runc:v0.8 + - linuxkit/containerd:v0.8 + +onboot: + - name: sysctl + image: linuxkit/sysctl:v0.8 + - name: dhcpcd + image: linuxkit/dhcpcd:v0.8 + command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf"] + +services: + - name: sshd + image: linuxkit/sshd:v0.8 + - name: docker + image: docker:dind + capabilities: + - all + binds: + - /var/run:/var/run + +files: + - path: /etc/ssh/authorized_keys + contents: | + {{ .SSH_KEY }} +``` + +### Production Template + +`.core/linuxkit/prod.yml`: + +```yaml +kernel: + image: linuxkit/kernel:5.15 + cmdline: "console=tty0 quiet" + +init: + - linuxkit/init:v0.8 + - linuxkit/runc:v0.8 + +onboot: + - name: sysctl + image: linuxkit/sysctl:v0.8 + binds: + - /etc/sysctl.d:/etc/sysctl.d + - name: dhcpcd + image: linuxkit/dhcpcd:v0.8 + command: ["/sbin/dhcpcd", "--nobackground", "-f", "/dhcpcd.conf"] + +services: + - name: sshd + image: linuxkit/sshd:v0.8 + - name: app + image: myapp:{{ .VERSION }} + capabilities: + - CAP_NET_BIND_SERVICE + binds: + - /var/data:/data + +files: + - path: /etc/ssh/authorized_keys + contents: | + {{ .SSH_KEY }} + - path: /etc/myapp/config.yaml + contents: | + server: + port: 443 + domain: {{ .DOMAIN }} + database: + path: /data/app.db +``` + +Run with: + +```bash +core vm run --template prod \ + --var SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" \ + --var VERSION=1.2.3 \ + --var DOMAIN=example.com +``` + +## Template Variables + +Variables use Go template syntax with double braces: + +```yaml +# Required variable +contents: | + {{ .SSH_KEY }} + +# With default value +contents: | + port: {{ .PORT | default "8080" }} + +# Conditional +{{ if .DEBUG }} + debug: true +{{ end }} +``` + +## See Also + +- [LinuxKit VMs](linuxkit) - Running and managing VMs +- [Build Command](/build/cli/build/) - Building LinuxKit images +- [VM Command](/build/cli/vm/) - Full VM CLI reference