Docker Deployment Guide

This guide covers the deployment of the Bowlerplate ecosystem using Docker. The architecture is designed to be modular, sharing common infrastructure (Database, Redis, Proxy) across multiple applications.

🏗️ Architecture Overview

The system is composed of three main layers:

1. Shared Proxy: A Caddy-based reverse proxy that handles incoming traffic and SSL.
2. Shared Infrastructure: A single MariaDB and Redis instance serving all apps.
3. Application Layer: Your Laravel backend, queue workers, scheduler, and documentation site.

🛠️ Prerequisites

• Docker and Docker Compose installed.
• Git (for cloning and version control).
• Basic knowledge of terminal commands.

🚀 Step-by-Step Setup

1. Initialize Shared Networks

Before starting any services, create the external networks that allow containers to communicate across different Compose projects.

docker network create web
docker network create shared

2. Start Shared Infrastructure

Navigate to the infra directory and start the database and cache services.

cd infra
docker compose up -d

This starts:

• MariaDB (Host: mysql, Port: 3306)
• Redis (Host: redis, Port: 6379)

3. Setup Reverse Proxy

The proxy handles routing for your domains (e.g., api.yourdomain.com).

cd ../proxy
docker compose up -d

4. Provision Your Application

Run the provisioning script to create a dedicated database and user for your app.

cd ../infra
chmod +x provision-app.sh
./provision-app.sh bowlerplate

Save the output! It will provide you with the DB_DATABASE, DB_USERNAME, and DB_PASSWORD for your .env file.

5. Configure the Application

Copy the production environment template and update it with the credentials from the previous step.

cd ../backend/laravel
cp .env.example .env.production

Edit .env.production:

• DB_HOST=mysql
• DB_DATABASE=bowlerplate
• DB_USERNAME=bowlerplate_user
• DB_PASSWORD=your_provisioned_password
• REDIS_HOST=redis
• APP_URL=https://api.yourdomain.com

6. Build and Deploy

Build Documentation Site

The documentation site uses a "pre-built" Docker strategy. You must build it locally first.

cd ../../docs
bun install
bun run build

Launch the Stack

Now, go back to the Laravel directory and start the application services. Note: This single compose file manages both the Backend and the Documentation site.

cd ../backend/laravel
docker compose up -d --build

This will launch:

• backend: The API server running on FrankenPHP (Port 8000).
• docs: The documentation site running on Bun (Port 3000).
• queue: The Laravel queue worker.
• scheduler: The Laravel task scheduler.

🔧 Useful Commands

Viewing Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend

Running Artisan Commands

docker compose exec backend php artisan migrate
docker compose exec backend php artisan tinker

Restarting Services

docker compose restart backend

⚠️ Important Notes

• Volumes: Application data and logs are stored in named volumes (e.g., app_storage). Do not delete these volumes unless you want to wipe application state.
• Permissions: The Dockerfile automatically sets permissions for storage and bootstrap/cache. If you encounter permission issues, ensure your host directory is writable by www-data (UID 33).
• FrankenPHP: The backend uses FrankenPHP with Octane for high performance. It handles the web server and PHP execution in a single process.