How abdullahalharun/coolify works
1. What this system is
- Coolify is a self-hosted control plane for deploying and operating applications, databases, services, and proxies on remote machines.
- The repository is primarily a Laravel application with Livewire UI, but it also ships companion Docker images and deployment templates that are part of the platform architecture.
2. Core control-plane shape
- The main app stores platform state in its own database: users, teams, servers, projects, environments, applications, databases, services, tags, secrets, backups, subscriptions, and webhooks.
- It does not host customer workloads directly; instead, it orchestrates them on managed servers over SSH/Docker.
3. Primary user-facing layer
- The UI is mostly Livewire + Blade components under app/Livewire and resources/views/livewire.
- Routes are split into web UI, API, console, and webhook endpoints.
- The UI covers onboarding, server management, project/resource configuration, deployments, databases, backups, logs, terminal access, settings, and subscription/admin screens.
4. API boundary
- The API controllers under app/Http/Controllers/Api expose resource management for applications, databases, servers, projects, services, teams, security, and deployment operations.
- openapi.json / openapi.yaml and the Generate/OpenApi command indicate the API is documented and treated as a first-class interface.
5. Domain model and tenancy
- The architecture is organized around Team -> Project -> Environment -> Resource relationships.
- Resources include:
- applications
- services
- standalone databases
- storage volumes
- scheduled tasks
- tags
- Access control is enforced through policies and middleware, with API-specific checks for abilities, allowed IPs, and sensitive data masking.
6. Orchestration and execution layer
- The heart of the system is in app/Actions and app/Jobs.
- Actions encapsulate operations like generate config, start/stop/restart apps and databases, proxy control, server validation, cleanup, and remote command execution.
- Jobs handle asynchronous workflows such as deployments, backups, server checks, Docker cleanup, SSL renewal, pull/push update tasks, notification dispatch, and subscription/billing processing.
7. Remote server boundary
- Coolify talks to managed servers using SSH and Docker-centric commands, with helpers for multiplexing and SSL.
- Remote actions include installing Docker, running commands, pulling logs/files, checking container status, managing proxies, and starting platform agents/sentinels.
- The key architectural boundary is: central Laravel control plane versus remote infrastructure nodes where workloads actually run.
8. Runtime coordination
- Background processing uses Laravel queue infrastructure with Horizon and scheduler commands.
- Console commands support queue cleanup, server/resource checks, update flows, environment seeding, and maintenance tasks.
- This means many visible UI actions are really requests that enqueue work and then reflect state changes later via jobs/events.
9. Realtime and terminal subsystems
- The repo contains a dedicated docker/coolify-realtime service, including a terminal server and Soketi entrypoint.
- Realtime is used for live status updates, logs, and terminal-like interactions rather than being part of the main web request lifecycle.
- This is a separate operational component from the Laravel app and should be shown as an adjacent service in an architecture diagram.
10. Eventing and notifications
- The app raises events for status changes, backups, tunnel changes, cleanup completion, SSL, server reachability, and service checks.
- Listeners and notification classes fan these events out to email, Discord, Slack, Telegram, and Pushover.
- There is also a transactional email path for auth, invitations, resets, and operational messages.
11. Integrations with external systems
- Source control providers: GitHub, GitLab, Bitbucket, Gitea webhooks and OAuth/app integrations.
- Billing: Stripe subscription and invoice handling.
- Cloud/network helpers: Cloudflare tunnels and related server configuration flows.
- Identity and auth extensions appear through Fortify, Sanctum, Socialite, and OAuth settings.
12. Persistence and schema
- The system relies heavily on a relational database with a large migration history, indicating the schema is the source of truth for platform configuration.
- Models mirror infrastructure entities and operational artifacts such as deployment queues, executions, backups, certificates, cleanup runs, and notifications.
- Secrets and keys are handled as first-class persisted resources, with encryption-related migrations and helper traits.
13. Deployment packaging
- The repository includes Dockerfiles and compose files for development, production, Windows, helper, realtime, and testing-host modes.
- There are also scripts for install, upgrade, cloud upgrade, sync, and nightly distribution.
- This means the repo is both the application source and the packaging/source-of-truth for how Coolify itself is deployed.
14. Template-driven app bootstrapping
- templates/compose contains a large catalog of ready-made Docker Compose templates for popular apps and databases.
- These templates are used to accelerate resource creation and encode supported deployment patterns.
- In diagram terms, they are an input catalog feeding the project/resource creation flows, not runtime services themselves.
Main entry points: Actions Actions · web.php Web UI · Jobs Jobs · Server.php Servers
Components 19
Control Plane
Laravel core that stores state, exposes UI/API, and coordinates operations.
- Web UI · User-facing routes and Livewire/Blade screens for onboarding, projects, servers, settings, and terminal.
routes/web.php - API Surface · Resource-management API endpoints plus OpenAPI documentation.
routes/api.php - Domain Models · Persistent platform entities such as teams, projects, environments, resources, secrets, backups, and subscriptions.
app/Models - Access Control · Authorization, allowed-IP checks, sensitive-data masking, and auth/session boundaries.
app/Policies
Execution
Asynchronous jobs, actions, and console processes that do the work.
- Actions · Synchronous orchestration primitives for config generation, server validation, proxy control, and remote command execution.
app/Actions - Jobs · Queued deployments, backups, cleanup, updates, checks, notifications, and billing processing.
app/Jobs - Console · Scheduler, Horizon, maintenance, cleanup, seeding, generation, and update commands.
app/Console/Commands - Services · Configuration generation, repositories, Docker parsing, and proxy dashboard cache.
app/Services - Events · Status, backup, proxy, tunnel, cleanup, SSL, and server reachability events.
app/Events - Notifications · Email and third-party notifications for application, server, database, and task outcomes.
app/Notifications
Remote Infra
Managed servers, Docker, SSH, proxy, and realtime adjunct services.
- Servers · Remote machines that host Docker workloads and platform agents, reached over SSH.
app/Models/Server.php - Docker Ops · Container status, start/stop/restart, cleanup, logs, and proxy/database lifecycle on remote hosts.
app/Actions/Docker - Realtime Service · Separate realtime service for live updates, Soketi, and terminal traffic.
docker/coolify-realtime
Packaging
Docker images, scripts, and deployment/runtime packaging for Coolify itself.
- Compose Templates · Template library used to bootstrap applications and databases from compose patterns.
templates/compose - Coolify Images · Dockerfiles and compose definitions for development, production, helper, testing-host, and realtime images.
docker - Install Scripts · Install, upgrade, cloud-upgrade, sync, and nightly distribution scripts.
scripts
Integrations
External systems and inbound/outbound integration boundaries.
- Git Providers · GitHub, GitLab, Bitbucket, and Gitea integrations via webhooks and OAuth/app settings.
- Stripe Billing · Subscriptions, invoices, trials, and payment webhooks.
app/Http/Controllers/Webhook/Stripe.php - Cloudflare · Cloudflare tunnel and related server configuration flows.
app/Actions/Server/ConfigureCloudflared.php
Connections 20
- Web UI → Domain Models: reads/writes · UI screens manage platform state and resource configuration.
- Web UI → Actions: triggers · User actions enqueue orchestration and remote operations.
- API Surface → Domain Models: CRUD · API controllers expose resource and team management.
- API Surface → Access Control: guards · API requests enforce abilities, allowed IPs, and sensitive data masking.
- Actions → Services: uses · Actions rely on generators, repositories, and parsing services.
- Actions → Servers: operates on · Actions coordinate work on managed servers.
- Actions → Docker Ops: executes · Remote lifecycle work is carried out through Docker-centric commands.
- Jobs → Actions: dispatches · Queued workflows reuse orchestration actions.
- Jobs → Events: emits · Jobs publish lifecycle and outcome events.
- Events → Notifications: fan-out · Listeners convert events into user-facing messages.
- Console → Jobs: schedules · Console commands manage queue, scheduler, maintenance, and update workflows.
- Console → Servers: checks/maintains · Commands perform server checks, cleanup, seeding, and update flows.
- Realtime Service → Web UI: streams to · Realtime updates power live logs, status, and terminal interactions.
- Realtime Service → Servers: bridges · Realtime terminal and status traffic bridges the control plane and nodes.
- Compose Templates → Web UI: bootstraps · Compose templates feed project and resource creation flows.
- Coolify Images → Actions: packages · Docker images define how the control plane and worker roles run.
- Install Scripts → Coolify Images: deploys · Scripts install and upgrade packaged runtime images.
- Git Providers → API Surface: webhooks · Source-control events enter through webhook and OAuth integrations.
- Stripe Billing → Jobs: billing events · Stripe events are processed asynchronously.
- Cloudflare → Servers: configures · Cloudflare tunnel integration configures remote infrastructure.