coolify: Instructions file for Codex

AGENTS.md

This file provides guidance to agentic coding tools when working with code in this repository.

Project Overview

Coolify is an open-source, self-hostable PaaS (alternative to Heroku/Netlify/Vercel). It manages servers, applications, databases, and services via SSH. Built with Laravel 12 (using Laravel 10 file structure), Livewire 3, and Tailwind CSS v4.

Design Reference

For UI/UX design specifications, principles, and visual standards, consult the local DESIGN.md. It is the source of truth for frontend design work in this repository.

Development Environment

Docker Compose-based dev setup with services: coolify (app, which also runs Reverb WebSockets and the terminal server), postgres, redis, vite, testing-host, mailpit, minio.

# One dev instance per git branch (containers, volumes, VMs named after the branch)
./scripts/dev start [qemu-profile]           # localhost VM: KVM (Linux, /dev/kvm + root/sudo) or Lima (macOS, limactl), else testing-host
./scripts/dev stop                           # stop containers and VMs; data is kept for the next start
./scripts/dev run                            # start + follow logs, stop on exit (Jean run script)
./scripts/dev urls                           # all instances, URLs, ports, and checkouts
./scripts/dev exec php artisan migrate       # run a command in this branch's Coolify container
./scripts/dev destroy <name>                 # delete containers, volumes, VMs, and the port slot
./scripts/dev teardown                       # destroy this worktree's instance (Jean teardown before worktree deletion)
# Compose: docker-compose.dev-multi.yml  Env + slots: <main checkout>/.dev-instances/ (gitignored)

# Legacy fixed-name stack (not used by scripts/dev)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

The main checkout serves its branch at localhost:8000 (Reverb 6001, terminal 6002, db 5432, redis 6379, vite 5173). Worktrees get a port block at 20000 + slot*10 (app +0, Reverb +1, terminal +2, db +3, redis +4, vite +5). Each instance has its own libvirt network coolify-dev-<slot> (10.221.<slot>.0/24) and VMs coolify-dev-<branch>--<profile>; VMs are reused, use php artisan dev:qemu <profile> --fresh to rebuild one. On macOS with Lima >= 2.0 (brew install lima), the localhost VM is the Lima instance coolify-dev-<slot>-<profile> (same profiles, users, and SSH key); Coolify reaches it through Lima's forwarded SSH port on host.docker.internal, and only guest ports 80/443 are forwarded to the Mac. Rebuild it with limactl delete -f <vm>. Force it with COOLIFY_DEV_SERVER_BACKEND=lima. To pass the host NVIDIA GPU through to the KVM localhost VM (ubuntu-root only), start with COOLIFY_DEV_GPU=1 ./scripts/dev start (or php artisan dev:qemu ubuntu-root --as-localhost --gpu). This attaches every PCI function of the GPU, gives the VM 4 GiB, stops nvidia-persistenced on the host, and installs the NVIDIA driver and container toolkit in the VM. The host cannot use the GPU while the VM runs. Remove it with --fresh without --gpu. If APP_URL in .env is a *.ts.net host, the browser ports are published with tailscale serve. Set COOLIFY_DEV_INSTANCE=<name> to run another instance from the same checkout.