The Docker plugin for Castor.

Describe your stack in PHP. Get a Compose file, a router, HTTPS and the tasks to drive them.

🚀 TL;DR

Installation

castor composer require castor-php/docker

Usage

1. Create a castor.php file in your project root:

<?php

namespace project;

use Castor\Attribute\AsContext;
use Castor\Attribute\AsListener;
use Castor\Context;
use Castor\Docker\Event\RegisterServiceEvent;
use Castor\Docker\Service\PostgresService;
use Castor\Docker\Service\SymfonyService;

#[AsContext(default: true)]
function default_context(): Context
{
    return new Context([
        'root_domain' => 'myproject.test',
        'registry' => 'ghcr.io/mycompany/myproject'
    ]);
}

#[AsListener(RegisterServiceEvent::class)]
function register_service(RegisterServiceEvent $event)
{
    $postgresService = new PostgresService();
    $event->addService($postgresService);

    $event->addService(
        (new SymfonyService(name: 'app', directory: __DIR__))
            ->withDatabaseService($postgresService)
            ->addDomain('myproject.test')
            ->allowHttpAccess()
    );
}

1. Start your project infrastructure:

castor docker:build
castor docker:up

The global Caddy router serving your domains is started along with it, and stopped again when no project needs it anymore.

1. See what it serves:

castor docker:about

It lists every URL the project answers on, with the service serving each of them.

Global router

The Caddy router is global: one instance, living outside of any project, serves every Castor Docker project on the machine. Ports 80 and 443 are bound once, projects run side by side, and the router survives their restarts.

docker:up starts it when the project routes a domain, docker:stop stops it once no routed container is left running anywhere. It lives in ~/.castor/docker/router/, and these tasks are for the times you want to decide yourself:

castor docker:router:enable     # create, start and trust it
castor docker:router:status     # is it running, which projects it serves
castor docker:router:logs       # add --follow to tail them
castor docker:router:restart
castor docker:router:disable

Set the router_autostart context variable to false, or CASTOR_DOCKER_ROUTER_AUTOSTART=0 for a single command, to leave the router entirely to those tasks.

Each project keeps its own compose network, and the router joins it on docker:up rather than every project joining a shared one — so two projects can both have a service named app without colliding in the Docker DNS. See the router documentation for the details.

Registering those two services also gave you tasks: castor app:bash, castor app:install, castor app:symfony, castor postgres:client, castor docker:logs, and more.

Prefer not to write it by hand? Let the plugin do it:

castor docker:service:install symfony

Want more?

• Getting started — install the plugin and boot your first environment
• Services — everything you can add to your stack
• Tasks — the commands the plugin gives you
• Going further — multiple applications, custom images, your own services