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 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
f831fd6846
commit
bdc03c5658
5 changed files with 682 additions and 1 deletions
|
|
@ -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,
|
||||
|
||||
|
|
|
|||
208
docs/deploy/docker.md
Normal file
208
docs/deploy/docker.md
Normal file
|
|
@ -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
|
||||
67
docs/deploy/index.md
Normal file
67
docs/deploy/index.md
Normal file
|
|
@ -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.
|
||||
168
docs/deploy/linuxkit.md
Normal file
168
docs/deploy/linuxkit.md
Normal file
|
|
@ -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
|
||||
220
docs/deploy/templates.md
Normal file
220
docs/deploy/templates.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Reference in a new issue