An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.
PHP coolifydatabasesdeploymentdockerdocker-composeinertiajslaravelmariadbmysqlnextjsnodejsphppostgresredisself-hostedself-hostingserverstatic-sitesveltesvelte5
feat(dev): run localhost dev server in a Lima VM on macOS
Andras Bacsai5f6fb5dcc209
diff --git a/AGENTS.md b/AGENTS.mdindex e66b6737b1..b1fb6b0f3d 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -15,8 +15,8 @@ For UI/UX design specifications, principles, and visual standards, consult the lDocker Compose-based dev setup with services: coolify (app, which also runs Reverb WebSockets and the terminal server), postgres, redis, vite, testing-host, mailpit, minio.```bash-# One dev instance per git branch (containers, volumes, KVM VMs named after the branch)-./scripts/dev start [qemu-profile] # KVM VM as localhost when /dev/kvm + root/sudo, else testing-host+# 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@@ -29,7 +29,7 @@ Docker Compose-based dev setup with services: coolify (app, which also runs Revedocker 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. 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.+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`. 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.## Testing the Self-Hosted Upgrade Processdiff --git a/app/Actions/Development/SeedDevelopmentQemuServer.php b/app/Actions/Development/SeedDevelopmentQemuServer.phpindex 191d045360..ad385f878e 100644--- a/app/Actions/Development/SeedDevelopmentQemuServer.php+++ b/app/Actions/Development/SeedDevelopmentQemuServer.php@@ -12,7 +12,10 @@ class SeedDevelopmentQemuServer{use AsAction;- public function handle(string $profileName, bool $removeOtherServers = true, bool $asLocalhost = false): Server+ /**+ * $ip and $port override the profile address, for example for a Lima VM whose SSH port is forwarded to the host.+ */+ public function handle(string $profileName, bool $removeOtherServers = true, bool $asLocalhost = false, ?string $ip = null, int $port = 22): Server{$this->ensureDevelopmentEnvironment();$profile = config("development-qemu.profiles.{$profileName}");@@ -41,8 +44,8 @@ class SeedDevelopmentQemuServer$server->fill(['name' => $asLocalhost ? 'localhost' : $profile['name'],'description' => 'Development QEMU virtual machine',- 'ip' => $profile['ip'],- 'port' => 22,+ 'ip' => $ip ?? $profile['ip'],+ 'port' => $port,'user' => $profile['user'],'team_id' => 0,'private_key_id' => $privateKey->id,diff --git a/app/Console/Commands/SeedDevelopmentQemuServerCommand.php b/app/Console/Commands/SeedDevelopmentQemuServerCommand.phpindex ce68b904f9..082ad83ae2 100644--- a/app/Console/Commands/SeedDevelopmentQemuServerCommand.php+++ b/app/Console/Commands/SeedDevelopmentQemuServerCommand.php@@ -7,7 +7,7 @@ use Illuminate\Console\Command;class SeedDevelopmentQemuServerCommand extends Command{- protected $signature = 'dev:qemu:seed {profile : Profile key from config/development-qemu.php} {--keep-others} {--as-localhost : Use the VM for the localhost server (id 0)}';+ protected $signature = 'dev:qemu:seed {profile : Profile key from config/development-qemu.php} {--keep-others} {--as-localhost : Use the VM for the localhost server (id 0)} {--ip= : SSH host instead of the profile IP} {--port=22 : SSH port}';protected $description = 'Seed one development QEMU server in the Coolify database';@@ -19,7 +19,7 @@ class SeedDevelopmentQemuServerCommand extends Commandreturn self::FAILURE;}- $server = SeedDevelopmentQemuServer::run($this->argument('profile'), ! $this->option('keep-others'), (bool) $this->option('as-localhost'));+ $server = SeedDevelopmentQemuServer::run($this->argument('profile'), ! $this->option('keep-others'), (bool) $this->option('as-localhost'), $this->option('ip') ?: null, (int) $this->option('port'));$this->info("Seeded {$server->name} at {$server->ip}.");return self::SUCCESS;diff --git a/scripts/dev b/scripts/devindex 1f47900b54..24063dbf8d 100755--- a/scripts/dev+++ b/scripts/dev@@ -2,7 +2,7 @@# Manage the development instance of the current git branch.## Usage:-# ./scripts/dev start [qemu-profile] # start this branch's instance (KVM VM or testing-host)+# ./scripts/dev start [qemu-profile] # start this branch's instance (KVM VM, Lima VM, or testing-host)# ./scripts/dev stop [qemu-profile] # stop containers and VMs; data is kept# ./scripts/dev run [qemu-profile] # start, follow logs, stop on exit (Jean)# ./scripts/dev urls # all instances, ports, and state@@ -10,15 +10,19 @@# ./scripts/dev destroy <name> # delete containers, volumes, VMs, and the port slot# ./scripts/dev teardown # destroy this worktree's instance if it exists (Jean)#-# Each branch is one instance: Compose project, container, volumes, and KVM VMs are+# Each branch is one instance: Compose project, container, volumes, and VMs are# named after it, so stop + start keeps the same data. Detached HEAD uses the# checkout directory name. Set COOLIFY_DEV_INSTANCE=<name> to override.#+# Server backend (auto): KVM on Linux with /dev/kvm and root/sudo, Lima on macOS when+# limactl (Lima >= 2.0) is installed, else the testing-host container. Lima VMs are+# named coolify-dev-<slot>-<profile>; rebuild one with: limactl delete -f <vm>+## Ports: the main checkout uses 8000 (Reverb 6001, terminal 6002, db 5432, redis 6379,# vite 5173). Worktrees use 20000 + slot*10: app +0, Reverb +1, terminal +2, db +3,# redis +4, vite +5, mailpit +6/+7, minio +8/+9.#-# Env: COOLIFY_DEV_SERVER_BACKEND=auto|testing-host, COOLIFY_DEV_KVM_PROFILE=<profile>+# Env: COOLIFY_DEV_SERVER_BACKEND=auto|lima|testing-host, COOLIFY_DEV_KVM_PROFILE=<profile>#set -euo pipefail@@ -34,7 +38,7 @@ QEMU_STORAGE="${DEVELOPMENT_QEMU_STORAGE_PATH:-/var/lib/libvirt/images/coolify-dLEGACY_CONTAINERS=(coolify coolify-db coolify-redis coolify-vite coolify-mail coolify-minio coolify-minio-init coolify-testing-host)usage() {- sed -n '2,22p' "$0" | sed 's/^# \?//'+ sed -n '2,26p' "$0" | sed 's/^# \?//'}normalize_name() {@@ -170,15 +174,22 @@ compose() {select_backend() {backend="${COOLIFY_DEV_SERVER_BACKEND:-auto}"- if [[ "$backend" != "auto" && "$backend" != "testing-host" ]]; then- echo 'COOLIFY_DEV_SERVER_BACKEND must be auto or testing-host.' >&2+ if [[ "$backend" != "auto" && "$backend" != "lima" && "$backend" != "testing-host" ]]; then+ echo 'COOLIFY_DEV_SERVER_BACKEND must be auto, lima, or testing-host.' >&2exit 2fiprivileged=()if [[ $EUID -ne 0 ]]; thenprivileged=(sudo -n -E)fi- if [[ "$backend" == "auto" && -c /dev/kvm && -r /dev/kvm && -w /dev/kvm ]] &&+ if [[ "$backend" == "lima" ]]; then+ command -v limactl >/dev/null || {+ echo 'COOLIFY_DEV_SERVER_BACKEND=lima needs limactl (brew install lima).' >&2+ exit 2+ }+ elif [[ "$backend" == "auto" && "$(uname -s)" == Darwin ]] && command -v limactl >/dev/null; then+ backend=lima+ elif [[ "$backend" == "auto" && -c /dev/kvm && -r /dev/kvm && -w /dev/kvm ]] &&{ [[ $EUID -eq 0 ]] || { command -v sudo >/dev/null && sudo -n -E true; }; }; thenbackend=kvmelse@@ -247,6 +258,120 @@ vm_domains() {grep -E "^coolify-dev-${instance}--" || true}+# Lima VMs of an instance are named coolify-dev-<slot>-<profile>; Lima names allow no "--".+lima_vm() { echo "coolify-dev-$(env_value "$instance" DEVELOPMENT_QEMU_SLOT)-$1"; }++lima_vms() {+ command -v limactl >/dev/null || return 0+ limactl list --format '{{.Name}} {{.Status}}' 2>/dev/null |+ awk -v prefix="$(lima_vm '')" -v status="${1:-}" \+ 'index($1, prefix) == 1 && (status == "" || $2 == status) { print $1 }'+}++# Same users, SSH key, and Docker setup as the KVM profiles in config/development-qemu.php.+# Provision scripts run on every boot, so each step is idempotent. The host directories+# are not mounted, and only guest ports 80 and 443 are forwarded to the host.+lima_config() {+ local image user key+ case "$1" in+ ubuntu-root | ubuntu-non-root) image=ubuntu-24.04 ;;+ debian-root | debian-non-root) image=debian-12 ;;+ centos-root | centos-non-root) image=centos-stream-9 ;;+ alpine-root | alpine-non-root) image=alpine-3.23 ;;+ *)+ echo "Unknown profile '$1'. Use a profile from config/development-qemu.php." >&2+ return 1+ ;;+ esac+ user=root+ [[ "$1" == *-non-root ]] && user=coolify+ key="$(sed -n "s/^ *'public_key' => '\(.*\)',\$/\1/p" config/development-qemu.php 2>/dev/null)"+ if [[ -z "$key" ]]; then+ echo 'Cannot read public_key from config/development-qemu.php.' >&2+ return 1+ fi+ cat <<YAML+minimumLimaVersion: 2.0.0+base: template:_images/${image}+cpus: 2+memory: 2GiB+disk: 20GiB+mounts: []+containerd:+ system: false+ user: false+portForwards:+- guestPort: 80+- guestPort: 443+- guestIP: 0.0.0.0+ guestPortRange: [1, 65535]+ proto: any+ ignore: true+- guestPortRange: [1, 65535]+ proto: any+ ignore: true+provision:+- mode: system+ script: |+ #!/bin/sh+ set -eu+ user='${user}'+ key='${key}'+ if ! command -v docker >/dev/null; then+ if command -v apk >/dev/null; then+ apk add docker docker-cli-buildx docker-cli-compose sudo+ else+ curl -fsSL https://get.docker.com | sh+ fi+ fi+ if command -v systemctl >/dev/null; then+ systemctl enable --now docker+ else+ # OpenRC can report an error for a start during boot; the runlevels start both services.+ rc-update add cgroups boot+ rc-update add docker default+ rc-service cgroups start || true+ rc-service docker start || true+ fi+ home=/root+ if [ "\$user" != root ]; then+ # A fixed high UID: Lima creates its own user later with the host UID (Alpine reboots first).+ if ! id "\$user" >/dev/null 2>&1; then+ if command -v useradd >/dev/null; then+ useradd -m -u 2000 -s /bin/bash "\$user"+ else+ adduser -D -u 2000 -s /bin/ash "\$user"+ fi+ echo "\$user:*" | chpasswd -e+ fi+ echo "\$user ALL=(ALL) NOPASSWD:ALL" >/etc/sudoers.d/90-coolify-dev+ chmod 440 /etc/sudoers.d/90-coolify-dev+ if command -v usermod >/dev/null; then usermod -aG docker "\$user"; else addgroup "\$user" docker; fi+ home="/home/\$user"+ fi+ mkdir -p "\$home/.ssh"+ grep -qxF "\$key" "\$home/.ssh/authorized_keys" 2>/dev/null || echo "\$key" >>"\$home/.ssh/authorized_keys"+ chmod 700 "\$home/.ssh"+ chmod 600 "\$home/.ssh/authorized_keys"+ chown -R "\$user:" "\$home/.ssh"+YAML+}++# Coolify connects over the SSH port that Lima forwards to the host loopback, which+# host.docker.internal reaches in Docker Desktop, OrbStack, and Colima.+start_lima_vm() {+ local vm config port+ vm="$(lima_vm "$profile")"+ if ! limactl list --quiet 2>/dev/null | grep -qxF "$vm"; then+ config="$(lima_config "$profile")"+ limactl create --tty=false --name="$vm" - <<<"$config"+ fi+ limactl start --tty=false "$vm"+ port="$(limactl list --format '{{.SSHLocalPort}}' "$vm")"+ compose "$instance" exec -T coolify php artisan dev:qemu:seed "$profile" --as-localhost \+ --ip=host.docker.internal --port="$port"+}+start_backend() {stop_other_checkout_instancesecho "==> Instance ${instance} → $(env_value "$instance" APP_URL) (backend: ${backend})"@@ -266,6 +391,9 @@ start_backend() {DEVELOPMENT_QEMU_DOCKER_NETWORK="$(project_name "$instance")" \DEVELOPMENT_QEMU_COOLIFY_CONTAINER="$(project_name "$instance")" \"${privileged[@]}" php artisan dev:qemu "$profile" --as-localhost+ elif [[ "$backend" == "lima" ]]; then+ echo "Using Lima profile: $profile"+ start_lima_vmelsecompose "$instance" exec -T coolify php artisan db:seed --class=ServerSeeder --forcefi@@ -279,6 +407,12 @@ stop_backend() {"${privileged[@]}" virsh --connect qemu:///system shutdown "$domain"fidone+ elif [[ "$backend" == "lima" ]]; then+ for domain in $(lima_vms Running); do+ if [[ -z "$profile_arg" || "$domain" == "$(lima_vm "$profile_arg")" ]]; then+ limactl stop "$domain"+ fi+ doneficompose "$instance" stop}@@ -308,6 +442,9 @@ cmd_destroy() {tailscale_serve offsubnet="$(docker network inspect "$(project_name "$name")" --format '{{(index .IPAM.Config 0).Subnet}}' 2>/dev/null || true)"compose "$name" --profile '*' down --remove-orphans --volumes+ for domain in $(lima_vms); do+ limactl delete --force "$domain"+ doneif command -v virsh >/dev/null; thenfor domain in $(vm_domains --all); do"${privileged[@]}" virsh --connect qemu:///system destroy "$domain" >/dev/null 2>&1 || truediff --git a/tests/Feature/DevScriptTest.php b/tests/Feature/DevScriptTest.phpindex dcc250cc1d..1864c012f9 100644--- a/tests/Feature/DevScriptTest.php+++ b/tests/Feature/DevScriptTest.php@@ -14,6 +14,8 @@ beforeEach(function () {copy(base_path('scripts/dev'), $main.'/scripts/dev');chmod($main.'/scripts/dev', 0755);copy(base_path('docker-compose.dev-multi.yml'), $main.'/docker-compose.dev-multi.yml');+ mkdir($main.'/config');+ copy(base_path('config/development-qemu.php'), $main.'/config/development-qemu.php');file_put_contents($main.'/.gitignore', ".env\n.dev-instances/\n");$git = Process::fromShellCommandline(implode(' && ', [@@ -45,6 +47,23 @@ BASH;file_put_contents($this->devRoot.'/bin/'.$binary, $fake);chmod($this->devRoot.'/bin/'.$binary, 0755);}++ $this->limaConfig = $this->devRoot.'/lima.yaml';+ $this->fakeLima = function (): void {+ file_put_contents($this->devRoot.'/bin/limactl', <<<'BASH'+#!/usr/bin/env bash+printf 'limactl %s\n' "$*" >> "$DEV_TEST_LOG"+case "$*" in+ create*) cat > "$DEV_TEST_LIMA_CONFIG" ;;+ *SSHLocalPort*) echo 53022 ;;+ *'{{.Name}} {{.Status}}'*) printf '%s\n' 'coolify-dev-2-debian-root Running' 'coolify-dev-2-ubuntu-root Stopped' 'coolify-dev-21-debian-root Running' 'other Running' ;;+esac+exit 0+BASH);+ file_put_contents($this->devRoot.'/bin/uname', "#!/usr/bin/env bash\necho Darwin\n");+ chmod($this->devRoot.'/bin/limactl', 0755);+ chmod($this->devRoot.'/bin/uname', 0755);+ };});afterEach(function () {@@ -58,6 +77,7 @@ function runDevScript(string $directory, array $arguments, array $env = []): Pro'DEV_TEST_LOG' => test()->devLog,'DEVELOPMENT_QEMU_STORAGE_PATH' => test()->qemuStorage,'COOLIFY_DEV_SERVER_BACKEND' => 'testing-host',+ 'DEV_TEST_LIMA_CONFIG' => test()->limaConfig,...$env,]);$process->run();@@ -225,6 +245,61 @@ BASH);->not->toContain('--profile testing-host up');});+it('starts a lima vm as localhost on macos and seeds its forwarded ssh port', function () {+ ($this->fakeLima)();+ runDevScript('main', ['start']);+ file_put_contents($this->devLog, '');++ $process = runDevScript('wt', ['start', 'debian-non-root'], ['COOLIFY_DEV_SERVER_BACKEND' => 'auto']);++ expect($process->isSuccessful())->toBeTrue($process->getErrorOutput())+ ->and(devScriptLog())+ ->toContain('limactl create --tty=false --name=coolify-dev-2-debian-non-root -')+ ->toContain('limactl start --tty=false coolify-dev-2-debian-non-root')+ ->toContain('exec -T coolify php artisan dev:qemu:seed debian-non-root --as-localhost --ip=host.docker.internal --port=53022')+ ->not->toContain('--profile testing-host up')+ ->not->toContain('dev:qemu debian-non-root')+ ->and(file_get_contents($this->limaConfig))+ ->toContain('base: template:_images/debian-12')+ ->toContain('mounts: []')+ ->toContain("user='coolify'")+ ->toContain(config('development-qemu.public_key'))+ ->toContain('"$user ALL=(ALL) NOPASSWD:ALL"');+});++it('rejects an unknown lima profile before it creates a vm', function () {+ ($this->fakeLima)();++ $process = runDevScript('wt', ['start', 'arch-root'], ['COOLIFY_DEV_SERVER_BACKEND' => 'lima']);++ expect($process->isSuccessful())->toBeFalse()+ ->and($process->getErrorOutput())->toContain("Unknown profile 'arch-root'")+ ->and(devScriptLog())->not->toContain('limactl create');+});++it('stops and destroys only the lima vms of the instance slot', function () {+ ($this->fakeLima)();+ runDevScript('main', ['start']);+ runDevScript('wt', ['start']);+ file_put_contents($this->devLog, '');++ $stop = runDevScript('wt', ['stop'], ['COOLIFY_DEV_SERVER_BACKEND' => 'lima']);+ $stopLog = devScriptLog();+ $destroy = runDevScript('main', ['destroy', 'fix-some_thing']);++ expect($stop->isSuccessful())->toBeTrue($stop->getErrorOutput())+ ->and($destroy->isSuccessful())->toBeTrue($destroy->getErrorOutput())+ ->and($stopLog)+ ->toContain('limactl stop coolify-dev-2-debian-root')+ ->not->toContain('limactl stop coolify-dev-2-ubuntu-root')+ ->not->toContain('limactl stop coolify-dev-21-debian-root')+ ->and(devScriptLog())+ ->toContain('limactl delete --force coolify-dev-2-debian-root')+ ->toContain('limactl delete --force coolify-dev-2-ubuntu-root')+ ->not->toContain('delete --force coolify-dev-21-debian-root')+ ->not->toContain('delete --force other');+});+it('keeps fresh worktree instances writable and stable during the first composer install', function () {$initSetup = file_get_contents(base_path('docker/development/etc/s6-overlay/scripts/init-setup.sh'));diff --git a/tests/Feature/DevelopmentQemuVmTest.php b/tests/Feature/DevelopmentQemuVmTest.phpindex 9c2cd95d69..ad6d1d76d0 100644--- a/tests/Feature/DevelopmentQemuVmTest.php+++ b/tests/Feature/DevelopmentQemuVmTest.php@@ -181,6 +181,24 @@ it('seeds localhost through the container command', function () {->and(Server::query()->findOrFail(0)->ip)->toBe('192.168.122.10');});+it('seeds localhost with the forwarded ssh address of a lima vm', function () {+ $this->seed(ServerSeeder::class);++ expect(Artisan::call('dev:qemu:seed', [+ 'profile' => 'debian-non-root',+ '--as-localhost' => true,+ '--ip' => 'host.docker.internal',+ '--port' => '53022',+ ]))->toBe(Command::SUCCESS);++ $server = Server::query()->findOrFail(0);++ expect($server->ip)->toBe('host.docker.internal')+ ->and($server->port)->toBe(53022)+ ->and($server->user)->toBe('coolify')+ ->and(Server::query()->count())->toBe(1);+});+it('replaces the seeded qemu server with the selected non-root equivalent', function () {SeedDevelopmentQemuServer::run('ubuntu-root');$server = SeedDevelopmentQemuServer::run('ubuntu-non-root');