PHPackages                             asamoahboateng/frankenphp-deploy - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [DevOps & Deployment](/categories/devops)
4. /
5. asamoahboateng/frankenphp-deploy

ActiveLibrary[DevOps & Deployment](/categories/devops)

asamoahboateng/frankenphp-deploy
================================

FrankenPHP + Traefik Docker deployment scaffolding for Laravel Octane projects.

1.3.3(3d ago)095MITPHPPHP ^8.2

Since Feb 4Pushed 1mo agoCompare

[ Source](https://github.com/asamoahboateng/frankenphp-deploy)[ Packagist](https://packagist.org/packages/asamoahboateng/frankenphp-deploy)[ RSS](/packages/asamoahboateng-frankenphp-deploy/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (16)Versions (17)Used By (0)

FrankenPHP Deploy
=================

[](#frankenphp-deploy)

FrankenPHP + Traefik Docker deployment scaffolding for Laravel Octane projects.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11.x or 12.x
- Laravel Octane
- Docker & Docker Compose

Installation
------------

[](#installation)

```
composer require asamoahboateng/frankenphp-deploy --dev
```

Quick Start
-----------

[](#quick-start)

```
# Install the scaffolding (interactive prompts for domain and project name)
php artisan frankenphp:install

# Or with options
php artisan frankenphp:install --domain=myapp.test --project=myapp

# With pgvector support (vector similarity search)
php artisan frankenphp:install --domain=myapp.test --project=myapp --pgvector
```

This will create:

- `frankenphp_server/` directory with Docker configuration files
- `pha` CLI script in your project root

SSL Certificates
----------------

[](#ssl-certificates)

### Local Development

[](#local-development)

```
cd frankenphp_server
./setup-ssl.sh
```

This uses `mkcert` to generate trusted local SSL certificates into `certs/local/`.

### Production / Multi-Domain

[](#production--multi-domain)

When using Traefik, each project manages its own SSL certificate. Place your cert files in the project's `frankenphp_server/certs/` directory:

```
frankenphp_server/certs/
├── local/          ← local dev certs (generated by setup-ssl.sh)
│   ├── cert.pem
│   └── key.pem
└── prod/           ← production certs (you provide these)
    ├── cert.pem
    └── key.pem

```

Set `APP_ENV=local` or `APP_ENV=production` in your `.env` to control which certs are loaded.

When `./pha start` runs, a `cert_loader` service copies each project's certs into shared Docker volumes (`traefik_certs`, `traefik_dynamic`). Traefik watches these volumes and automatically picks up certificates for all projects — so each domain gets its own SSL without any Traefik restart.

Starting Your Application
-------------------------

[](#starting-your-application)

```
# Start with Traefik reverse proxy (recommended for multiple projects)
./pha start

# Or start standalone (FrankenPHP handles SSL directly)
./pha standalone
```

Pha CLI Commands
----------------

[](#pha-cli-commands)

### Lifecycle

[](#lifecycle)

CommandDescription`./pha start`Start with Traefik reverse proxy`./pha standalone`Start without Traefik (FrankenPHP handles SSL)`./pha stop`Stop all containers`./pha reboot`Restart all services`./pha reload`Reload Octane workers (zero downtime)`./pha fresh`Wipe and rebuild (local only)`./pha delete`Remove all containers, images, volumes### Scaling

[](#scaling)

CommandDescription`./pha scale [n]`Scale to n replicas (e.g., `./pha scale 4`)### Development

[](#development)

CommandDescription`./pha art [cmd]`Run artisan command`./pha composer`Run composer command`./pha npm`Run npm command`./pha tinker`Open Laravel tinker`./pha ssh`Shell into container### Monitoring

[](#monitoring)

CommandDescription`./pha ls`List running containers`./pha logs`Tail FrankenPHP logs`./pha status`Show detailed statusConfiguration
-------------

[](#configuration)

After installation, edit `frankenphp_server/.env` to customize:

```
APP_URL=https://myapp.test/
APP_DOMAIN=myapp.test
APP_PORT=8000
APP_ENV=local
COMPOSE_PROJECT_NAME=myapp
TRAEFIK_HOST=traefik.myapp.test
ADMINER_DOMAIN=adminer.myapp.test
```

Architecture
------------

[](#architecture)

### Standalone vs Traefik

[](#standalone-vs-traefik)

Standalone (`./pha standalone`)Traefik (`./pha start`)**SSL**FrankenPHP/Caddy handles SSL directlyTraefik terminates SSL, proxies to FrankenPHP**Ports**Exposes 80, 443, 443/udp (HTTP/3)No ports exposed — Traefik routes traffic**Multi-project**One app per serverMultiple apps on the same server**Scaling**Single containerHorizontal scaling via `replicas`**Cert management**Caddy auto-manages or uses local certs`cert_loader` copies certs to shared Traefik volumes**Adminer**Exposed on port 8080Routed via `adminer.yourdomain.com`Use **standalone** for a single app on a server (simpler, fewer moving parts). Use **Traefik** when you need multiple apps sharing ports 80/443 or horizontal scaling.

### With Traefik (Multi-Project Setup)

[](#with-traefik-multi-project-setup)

```
┌─────────────┐
│   Traefik   │ ← SSL termination, routing
│ (port 443)  │
└──────┬──────┘
       │
┌──────┴──────┐
│ FrankenPHP  │ ← Laravel Octane
└──────┬──────┘
       │
┌──────┴──────┐
│    Init     │ ← composer install, migrations
└──────┬──────┘
       │
┌──────┴──────┐
│  Services   │ ← PostgreSQL, Redis, Queue Worker, DB Backup
└─────────────┘

```

### Standalone (Single Project)

[](#standalone-single-project)

```
┌─────────────┐
│ FrankenPHP  │ ← SSL via Caddy + Laravel Octane
│ (port 443)  │
└──────┬──────┘
       │
┌──────┴──────┐
│    Init     │ ← composer install, migrations
└──────┬──────┘
       │
┌──────┴──────┐
│  Services   │ ← PostgreSQL, Redis, Queue Worker, DB Backup
└─────────────┘

```

Services Included
-----------------

[](#services-included)

- **Init** - Runs before the app starts to install Composer dependencies and execute database migrations
- **FrankenPHP** - High-performance PHP application server with Caddy
- **PostgreSQL 16** - Database (optionally with pgvector for vector similarity search)
- **Redis** - Cache and session storage
- **Queue Worker** - Laravel queue processing
- **DB Backup** - Weekly PostgreSQL backup with automatic old backup cleanup
- **Adminer** - Database management UI
- **Typesense** - Search engine (optional)

Init Service
------------

[](#init-service)

The `init` service is a one-shot container that runs **before** the main FrankenPHP application starts. It ensures your environment is ready by performing:

1. **Composer install** - installs/updates PHP dependencies (`composer install --optimize-autoloader`)
2. **Database migrations** - runs `php artisan migrate --force`
3. **Storage link** - creates the public storage symlink

The startup order is: `db/redis → init → frankenphp → worker`

The init container uses the same Docker image as the app, exits after completing its tasks, and will not restart. If it fails (e.g., a migration error), the main app will not start — allowing you to fix the issue before the app serves traffic.

To customize what the init service runs, edit `frankenphp_server/init.sh`.

Database Backups
----------------

[](#database-backups)

The `db_backup` service runs alongside your app and performs a weekly `pg_dump` of the PostgreSQL database. Each time it runs, it deletes the previous backup and creates a fresh compressed dump.

Backups are stored in `frankenphp_server/db-backups/` on the host:

```
frankenphp_server/db-backups/
└── backup_20260222_030000.sql.gz

```

To restore from a backup:

```
gunzip -c frankenphp_server/db-backups/backup_*.sql.gz | docker exec -i  psql -U laravelUser -d laravel
```

pgvector (Vector Search)
------------------------

[](#pgvector-vector-search)

To enable vector similarity search, use the `--pgvector` flag during installation:

```
php artisan frankenphp:install --pgvector
```

This switches the database image from `postgres:16-alpine` to `pgvector/pgvector:pg16`. After starting the containers, enable the extension in your database:

```
CREATE EXTENSION vector;
```

This is useful for AI/ML applications that need to store and query vector embeddings (e.g., with Laravel Scout or custom similarity search).

Optional Services
-----------------

[](#optional-services)

### Typesense (Search Engine)

[](#typesense-search-engine)

Typesense is included by default but is optional. It's useful for Laravel Scout integration.

#### To use Typesense:

[](#to-use-typesense)

1. Set your API key in `frankenphp_server/.env`:

    ```
    TYPESENSE_API_KEY=your-secure-api-key
    ```
2. Add to your Laravel `.env`:

    ```
    SCOUT_DRIVER=typesense
    TYPESENSE_HOST=typesense
    TYPESENSE_PORT=8108
    TYPESENSE_PROTOCOL=http
    TYPESENSE_API_KEY=your-secure-api-key
    ```
3. Install Laravel Scout with Typesense:

    ```
    composer require laravel/scout typesense/typesense-php
    ```

#### To remove Typesense:

[](#to-remove-typesense)

If you don't need search functionality, comment out or delete the Typesense service in your docker-compose files:

**In `frankenphp_server/docker-compose-traefik.yml` and `docker-compose-standalone.yml`:**

```
# Comment out or delete this entire block:
# typesense:
#   image: typesense/typesense:27.1
#   container_name: myapp_typesense_franken
#   ...
```

Also remove the Typesense environment variables from the `frankenphp` service:

```
# Remove these lines:
# - TYPESENSE_HOST=typesense
# - TYPESENSE_PORT=8108
# - TYPESENSE_PROTOCOL=http
# - TYPESENSE_API_KEY=${TYPESENSE_API_KEY:-xyz123}
```

Publishing Config
-----------------

[](#publishing-config)

To customize the package configuration:

```
php artisan vendor:publish --tag=frankenphp-config
```

This publishes `config/frankenphp.php` where you can set default values for Traefik network names and other settings.

Force Overwrite
---------------

[](#force-overwrite)

To reinstall and overwrite existing files:

```
php artisan frankenphp:install --force
```

License
-------

[](#license)

MIT

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance94

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~10 days

Recently: every ~29 days

Total

16

Last Release

3d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7695191?v=4)[Kwame Asamoah Boateng](/maintainers/asamoahboateng)[@asamoahboateng](https://github.com/asamoahboateng)

---

Tags

laraveldockeroctanefrankenphpdeploymenttraefik

### Embed Badge

![Health badge](/badges/asamoahboateng-frankenphp-deploy/health.svg)

```
[![Health](https://phpackages.com/badges/asamoahboateng-frankenphp-deploy/health.svg)](https://phpackages.com/packages/asamoahboateng-frankenphp-deploy)
```

###  Alternatives

[laravel/sail

Docker files for running a basic Laravel application.

1.9k205.7M1.3k](/packages/laravel-sail)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M194](/packages/laravel-ai)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77022.3M151](/packages/laravel-mcp)[propaganistas/laravel-disposable-email

Disposable email validator

6023.0M7](/packages/propaganistas-laravel-disposable-email)[tallstackui/tallstackui

TallStackUI is a powerful suite of Blade components that elevate your workflow of Livewire applications.

725173.2k14](/packages/tallstackui-tallstackui)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)