docs(deploy): add PHP deployment guide
- Add PHP deployment with FrankenPHP containers - Document core php build, serve, and deploy commands - Include Coolify deployment integration - Add CI/CD examples for GitHub Actions and GitLab - Update nav and sidebar with PHP option Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
bdc03c5658
commit
7696d8cd41
3 changed files with 314 additions and 0 deletions
|
|
@ -81,6 +81,7 @@ export default defineConfig({
|
|||
activeMatch: '/deploy/',
|
||||
items: [
|
||||
{ text: 'Overview', link: '/deploy/' },
|
||||
{ text: 'PHP', link: '/deploy/php' },
|
||||
{ text: 'LinuxKit VMs', link: '/deploy/linuxkit' },
|
||||
{ text: 'Templates', link: '/deploy/templates' },
|
||||
{ text: 'Docker', link: '/deploy/docker' }
|
||||
|
|
@ -125,6 +126,7 @@ export default defineConfig({
|
|||
text: 'Deploy',
|
||||
items: [
|
||||
{ text: 'Overview', link: '/deploy/' },
|
||||
{ text: 'PHP', link: '/deploy/php' },
|
||||
{ text: 'LinuxKit VMs', link: '/deploy/linuxkit' },
|
||||
{ text: 'Templates', link: '/deploy/templates' },
|
||||
{ text: 'Docker', link: '/deploy/docker' }
|
||||
|
|
|
|||
|
|
@ -6,6 +6,7 @@ Deploy applications to VMs, containers, and cloud infrastructure.
|
|||
|
||||
| Target | Description | Use Case |
|
||||
|--------|-------------|----------|
|
||||
| [PHP](php) | Laravel/PHP with FrankenPHP | Web applications, APIs |
|
||||
| [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 |
|
||||
|
|
|
|||
311
docs/deploy/php.md
Normal file
311
docs/deploy/php.md
Normal file
|
|
@ -0,0 +1,311 @@
|
|||
# PHP Deployment
|
||||
|
||||
Deploy Laravel/PHP applications using FrankenPHP containers, LinuxKit VMs, or Coolify.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Build production image
|
||||
core php build --name myapp --tag v1.0
|
||||
|
||||
# Run locally
|
||||
core php serve --name myapp -d
|
||||
|
||||
# Deploy to Coolify
|
||||
core php deploy --wait
|
||||
```
|
||||
|
||||
## Building Images
|
||||
|
||||
### Docker Image
|
||||
|
||||
Build a production-ready Docker image with FrankenPHP:
|
||||
|
||||
```bash
|
||||
# Basic build
|
||||
core php build
|
||||
|
||||
# With custom name and tag
|
||||
core php build --name myapp --tag v1.0
|
||||
|
||||
# For specific platform
|
||||
core php build --name myapp --platform linux/amd64
|
||||
|
||||
# Without cache
|
||||
core php build --name myapp --no-cache
|
||||
```
|
||||
|
||||
### LinuxKit Image
|
||||
|
||||
Build a bootable VM image:
|
||||
|
||||
```bash
|
||||
# Build with default template (server-php)
|
||||
core php build --type linuxkit
|
||||
|
||||
# Build QCOW2 for QEMU/KVM
|
||||
core php build --type linuxkit --format qcow2
|
||||
|
||||
# Build ISO for bare metal
|
||||
core php build --type linuxkit --format iso
|
||||
|
||||
# Custom output path
|
||||
core php build --type linuxkit --output ./dist/server.qcow2
|
||||
```
|
||||
|
||||
### Build Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--type` | Build type: `docker` or `linuxkit` | docker |
|
||||
| `--name` | Image name | project directory |
|
||||
| `--tag` | Image tag | latest |
|
||||
| `--platform` | Target platform | linux/amd64 |
|
||||
| `--dockerfile` | Custom Dockerfile path | Dockerfile |
|
||||
| `--format` | LinuxKit format: qcow2, iso, raw, vmdk | qcow2 |
|
||||
| `--template` | LinuxKit template | server-php |
|
||||
| `--no-cache` | Build without cache | false |
|
||||
|
||||
## Running Production Containers
|
||||
|
||||
### Local Testing
|
||||
|
||||
Run a production container locally before deploying:
|
||||
|
||||
```bash
|
||||
# Run in foreground
|
||||
core php serve --name myapp
|
||||
|
||||
# Run detached (background)
|
||||
core php serve --name myapp -d
|
||||
|
||||
# Custom ports
|
||||
core php serve --name myapp --port 8080 --https-port 8443
|
||||
|
||||
# With environment file
|
||||
core php serve --name myapp --env-file .env.production
|
||||
```
|
||||
|
||||
### Shell Access
|
||||
|
||||
Debug running containers:
|
||||
|
||||
```bash
|
||||
# Open shell in container
|
||||
core php shell <container-id>
|
||||
|
||||
# Run artisan commands
|
||||
docker exec -it <container-id> php artisan migrate:status
|
||||
```
|
||||
|
||||
## Deploying to Coolify
|
||||
|
||||
[Coolify](https://coolify.io) is a self-hosted PaaS for deploying applications.
|
||||
|
||||
### Configuration
|
||||
|
||||
Add Coolify credentials to `.env`:
|
||||
|
||||
```env
|
||||
COOLIFY_URL=https://coolify.example.com
|
||||
COOLIFY_TOKEN=your-api-token
|
||||
COOLIFY_APP_ID=production-app-id
|
||||
COOLIFY_STAGING_APP_ID=staging-app-id
|
||||
```
|
||||
|
||||
Or configure in `.core/php.yaml`:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
deploy:
|
||||
coolify:
|
||||
server: https://coolify.example.com
|
||||
project: my-project
|
||||
```
|
||||
|
||||
### Deploy Commands
|
||||
|
||||
```bash
|
||||
# Deploy to production
|
||||
core php deploy
|
||||
|
||||
# Deploy to staging
|
||||
core php deploy --staging
|
||||
|
||||
# Force deploy (even if no changes)
|
||||
core php deploy --force
|
||||
|
||||
# Wait for deployment to complete
|
||||
core php deploy --wait
|
||||
```
|
||||
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
# Current deployment status
|
||||
core php deploy:status
|
||||
|
||||
# Staging status
|
||||
core php deploy:status --staging
|
||||
|
||||
# Specific deployment
|
||||
core php deploy:status --id abc123
|
||||
```
|
||||
|
||||
### Rollback
|
||||
|
||||
```bash
|
||||
# Rollback to previous deployment
|
||||
core php deploy:rollback
|
||||
|
||||
# Rollback staging
|
||||
core php deploy:rollback --staging
|
||||
|
||||
# Rollback to specific deployment
|
||||
core php deploy:rollback --id abc123
|
||||
|
||||
# Wait for rollback to complete
|
||||
core php deploy:rollback --wait
|
||||
```
|
||||
|
||||
### Deployment History
|
||||
|
||||
```bash
|
||||
# List recent deployments
|
||||
core php deploy:list
|
||||
|
||||
# Staging deployments
|
||||
core php deploy:list --staging
|
||||
|
||||
# Show more
|
||||
core php deploy:list --limit 20
|
||||
```
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Deploy
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Core CLI
|
||||
run: |
|
||||
curl -fsSL https://get.host.uk.com | bash
|
||||
echo "$HOME/.core/bin" >> $GITHUB_PATH
|
||||
|
||||
- name: Build image
|
||||
run: core php build --name ${{ vars.IMAGE_NAME }} --tag ${{ github.sha }}
|
||||
|
||||
- name: Push to registry
|
||||
run: |
|
||||
echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
|
||||
docker push ${{ vars.IMAGE_NAME }}:${{ github.sha }}
|
||||
|
||||
- name: Deploy
|
||||
env:
|
||||
COOLIFY_URL: ${{ secrets.COOLIFY_URL }}
|
||||
COOLIFY_TOKEN: ${{ secrets.COOLIFY_TOKEN }}
|
||||
COOLIFY_APP_ID: ${{ secrets.COOLIFY_APP_ID }}
|
||||
run: core php deploy --wait
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
stage: deploy
|
||||
image: hostuk/core:latest
|
||||
script:
|
||||
- core php build --name $CI_REGISTRY_IMAGE --tag $CI_COMMIT_SHA
|
||||
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
|
||||
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
|
||||
- core php deploy --wait
|
||||
only:
|
||||
- main
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Production .env
|
||||
|
||||
```env
|
||||
APP_ENV=production
|
||||
APP_DEBUG=false
|
||||
APP_URL=https://myapp.com
|
||||
|
||||
# Database
|
||||
DB_CONNECTION=pgsql
|
||||
DB_HOST=db.internal
|
||||
DB_DATABASE=myapp
|
||||
DB_USERNAME=myapp
|
||||
DB_PASSWORD=${DB_PASSWORD}
|
||||
|
||||
# Cache & Queue
|
||||
CACHE_DRIVER=redis
|
||||
QUEUE_CONNECTION=redis
|
||||
SESSION_DRIVER=redis
|
||||
REDIS_HOST=redis.internal
|
||||
|
||||
# FrankenPHP
|
||||
OCTANE_SERVER=frankenphp
|
||||
OCTANE_WORKERS=auto
|
||||
OCTANE_MAX_REQUESTS=1000
|
||||
```
|
||||
|
||||
### Health Checks
|
||||
|
||||
Ensure your app has a health endpoint:
|
||||
|
||||
```php
|
||||
// routes/web.php
|
||||
Route::get('/health', fn () => response()->json([
|
||||
'status' => 'ok',
|
||||
'timestamp' => now()->toIso8601String(),
|
||||
]));
|
||||
```
|
||||
|
||||
## Deployment Strategies
|
||||
|
||||
### Blue-Green
|
||||
|
||||
```bash
|
||||
# Build new version
|
||||
core php build --name myapp --tag v2.0
|
||||
|
||||
# Deploy to staging
|
||||
core php deploy --staging --wait
|
||||
|
||||
# Test staging
|
||||
curl https://staging.myapp.com/health
|
||||
|
||||
# Switch production
|
||||
core php deploy --wait
|
||||
```
|
||||
|
||||
### Canary
|
||||
|
||||
```bash
|
||||
# Deploy to canary (10% traffic)
|
||||
COOLIFY_APP_ID=$CANARY_APP_ID core php deploy --wait
|
||||
|
||||
# Monitor metrics, then full rollout
|
||||
core php deploy --wait
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Docker Deployment](docker) - Container orchestration
|
||||
- [LinuxKit VMs](linuxkit) - VM-based deployment
|
||||
- [Templates](templates) - Pre-configured VM templates
|
||||
- [PHP CLI Reference](/build/cli/php/) - Full command documentation
|
||||
Loading…
Add table
Reference in a new issue