Djoser 0.3.1

Welcome to Djoser

A native Windows home for PHP and Laravel: each project's own PHP and Node.js, local HTTPS sites, databases, S3, mail and background workers, from one command line.

A Laravel project from zero

From an empty folder to a site with PHP, MySQL, Redis, S3 storage, a mail inbox, queue workers, the scheduler and Vite. For a project you already have, start at step 3 inside its folder.

1. Get PHP, Composer and Node.js

djoser list php                    # the PHP versions you can install
djoser install php 8.5             # the newest 8.5 patch, checked against its published hash
djoser install composer latest
djoser install node 22
djoser use php 8.5 --env           # the PHP used outside projects (optional)
djoser runtimes                    # what is installed now

The first version of each you install becomes the default outside projects by itself.

2. Create the project

cd D:\Sites
djoser composer create-project laravel/laravel shop
cd shop

3. Describe it

djoser init                        # asks, with the Laravel answers filled in
djoser init --name shop --domain shop.localhost --root public --php 8.5 -y

init writes djoser.yaml with four PHP settings and six scripts. Add the services the project needs:

name: shop
domain: shop.localhost
web-root: public
services:
  php:
    version: 8.5
    extensions: [redis]          # the PHP extension that talks to Redis
    ini:
      memory_limit: 512M
      upload_max_filesize: 64M
  node: 22
  mysql:
    version: 8.4
    database: shop
  redis: 8.4                     # the Redis server itself
  rustfs: 1.0                    # S3 storage, with a bucket named shop
  mailpit: 1.33                  # every mail the app sends lands here
scripts:
  queue: php artisan queue:work --memory=512 --max-time=3600
  schedule: php artisan schedule:work
  dev: npm run dev
  build: npm run build
workers:
  - queue: 2
  - schedule
  - dev:
      startup: false             # start it when you want it

4. Start it

djoser up

The first run downloads what is missing, starts it, and offers to trust the local certificate. It ends with the address and how to reach each service: MySQL on 127.0.0.1:3306 as root with no password, Redis on 6379, the S3 server on 9000 with its console, and the mail inbox at http://127.0.0.1:8025.

5. Connect Laravel

djoser env sync

Djoser compares .env with what it runs (DB_*, REDIS_*, MAIL_*, AWS_*, APP_URL) and shows each difference as the line you have and the line it expects. It changes the file only after you type y. Then choose what Laravel uses them for:

CACHE_STORE=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
REDIS_PREFIX=shop_
FILESYSTEM_DISK=s3

6. Prepare the app

djoser composer require league/flysystem-aws-s3-v3
djoser artisan migrate
djoser artisan storage:link
djoser npm install
djoser run build

Open https://shop.localhost.

7. Watch it run

djoser status -w                   # services, workers, memory, failed jobs, redrawn
djoser workers start dev           # Vite, for hot reload while you work
djoser logs queue -f
djoser jobs
djoser jobs retry all
djoser tool db                     # HeidiSQL on the shop database

8. Keep it safe and share it

djoser db backup                   # Documents\Djoser\Backups\shop
djoser share                       # a temporary public address, until Ctrl+C
djoser down

djoser.yaml, every key

Edit the file and run djoser up; djoser status says when it changed since the last up. Write only what you need: mysql: 8.4 alone is enough. A key with no effect is reported by up, and an unknown one is a warning.

name: shop                     # default: the folder's name
domain: shop.localhost         # default: <name>.localhost
aliases: [www, api]            # more subdomains; "*" serves any
web-root: public               # default: public for Laravel, else the folder with index.php or index.html
tls:                           # default: Djoser's local certificate
  cert: certs/shop.pem
  key: certs/shop-key.pem
backups: D:/Backups/shop       # default: Documents\Djoser\Backups\<name>
services:
scripts:
workers:

A version is a line such as 8.5 or an exact one such as 8.5.12. Servers are shared by projects, with one database per project, on 127.0.0.1 only; port:, data:, dedicated: true or settings: give a project its own server, which starts with empty data.

Services

php

php:
  version: 8.5
  extensions: [redis, xdebug]    # djoser list extensions
  ini:                           # any php.ini setting but the extension ones and the CA bundle
    memory_limit: 512M
    upload_max_filesize: 64M
    post_max_size: 64M
    max_execution_time: 120

node

node: 22                       # without it: .nvmrc, then .node-version (22, v22.11.0, lts/*, lts/iron, node)

mysql and mariadb

mysql:                         # or mariadb:
  version: 8.4                 # mysql 8.0, 8.4, 9.7; mariadb 10.11, 11.4, 11.8, 12.3, 13.0
  database: shop               # default: the project's name, - becomes _
  port: 3306                   # default: shared server from 3306
  data: D:/Data/shop-mysql     # the folder must exist
  dedicated: true
  settings:                    # --name=value
    max_connections: 500
    innodb_buffer_pool_size: 512M

User root, no password. Djoser sets datadir, port, bind_address, socket, console, mysqlx and no_defaults itself.

postgres

postgres:
  version: 17                  # 15, 16, 17, 18
  database: shop
  port: 5432
  settings:                    # -c name=value
    shared_buffers: 256MB
    work_mem: 16MB

User postgres, no password; env sync sets DB_CONNECTION=pgsql.

mongodb

mongodb:
  version: 8.0                 # 7.0, 8.0, 8.2, 8.3; mongosh comes with it
  database: shop               # made on first write
  port: 27017
  settings:                    # --name value
    wiredTigerCacheSizeGB: 1

For Laravel, the mongodb PHP extension and mongodb/laravel-mongodb; env sync sets MONGODB_URI and MONGODB_DATABASE.

redis

redis:
  version: 8.4                 # 7.2, 7.4, 8.4, 8.10
  port: 6379
  settings:                    # --name value
    maxmemory: 256mb
    maxmemory-policy: allkeys-lru

Projects sharing a server share keys: give each its own REDIS_PREFIX.

rustfs

rustfs:
  version: 1.0
  bucket: shop                 # default: the project's name
  port: 9000                   # the console takes the next free port
  settings:                    # RUSTFS_<NAME> environment variables
    access_key: rustfsadmin
    secret_key: rustfsadmin

mailpit

mailpit:
  version: 1.33
  port: 1025                   # SMTP; the inbox is on 8025
  settings:
    max: 2000

settings gives the project its own server, and changing them restarts it at the next up.

Scripts and workers in djoser.yaml

scripts:
  queue: php artisan queue:work --memory=512 --max-time=3600
  test: php artisan test {args}             # arguments go where {args} stands, or at the end
  dev: npm run dev
  deploy: "!git pull && composer install && php artisan migrate --force"
workers:
  - schedule                   # one, started by up
  - queue: 3                   # three of that script
  - dev:
      startup: false           # started only by: djoser workers start dev
  - mail:
      count: 2
      startup: false

A script starts with a Djoser tool (php, artisan, composer, node, npm, npx, mysql and the others). One that starts with !, in quotes, runs through cmd, so git and && work. Every worker must be a script.

Example: a large Laravel app

name: shop
domain: shop.localhost
aliases: [www, admin, api, "*"]
web-root: public
backups: D:/Backups/shop
services:
  php:
    version: 8.5
    extensions: [redis, imagick, xdebug]
    ini:
      memory_limit: 1G
      upload_max_filesize: 256M
      post_max_size: 256M
      xdebug.mode: debug
      xdebug.start_with_request: trigger
  node: 22
  mysql:
    version: 8.4
    database: shop
    settings:
      max_connections: 500
      innodb_buffer_pool_size: 1G
  postgres:
    version: 17
    database: shop_reports
  redis:
    version: 8.4
    settings:
      maxmemory: 512mb
  rustfs:
    version: 1.0
    bucket: shop-media
  mailpit: 1.33
scripts:
  queue: php artisan queue:work redis --queue=high,default --memory=512 --max-time=3600
  mail: php artisan queue:work redis --queue=mail --memory=256 --max-time=3600
  schedule: php artisan schedule:work
  reverb: php artisan reverb:start
  dev: npm run dev
  build: npm run build
  test: php artisan test --parallel {args}
  deploy: "!git pull && composer install && php artisan migrate --force && npm run build"
workers:
  - queue: 3
  - mail
  - schedule
  - reverb
  - dev:
      startup: false

up serves shop.localhost, www., admin., api. and any <tenant>.shop.localhost from the same project, and starts six worker processes.

Example: Next.js

Djoser serves files from a folder and does not yet stand in front of the Next.js server. Two ways work today: a static export served at https://web.localhost, and the dev server kept running as a worker on port 3000.

djoser npx create-next-app@latest web
cd web
djoser npm run build               # with output: 'export' in next.config.js, this writes out
djoser init --root out -y
name: web
domain: web.localhost
web-root: out
services:
  node: 22
  postgres:
    version: 17
    database: web
  redis: 8.4
scripts:
  dev: npm run dev
  build: npm run build
  prisma: npx prisma {args}
workers:
  - dev
djoser up
djoser run prisma migrate dev
djoser logs dev -f

Example: a plain page

cd D:\Sites\landing
djoser init -y
djoser up
name: landing
domain: landing.localhost
web-root: .
services:
  php: 8.5                     # leave services out for HTML only

Every command

Inside a project folder, commands act on that project. --project <name> picks another one from anywhere, --no-color prints plain text, and djoser <command> --help lists its options.

Projects

CommandWhat it does
djoser initAsk the questions and write djoser.yaml here
djoser init <folder>The same for another folder
djoser init --name shop --domain shop.localhost --root public --php 8.5Answer from the command line; the rest are asked
djoser init -yTake every default
djoser upStart what djoser.yaml asks for, downloading what is missing; again after an edit
djoser downStop the site, the servers only it uses, and its workers
djoser statusAddress, services, workers, memory, failed jobs, and changes since the last up
djoser status -wThe same, redrawn every 2 seconds until Ctrl+C
djoser ps / ps -aRunning projects; -a adds stopped ones
djoser projectsEvery project Djoser knows, with its folder
djoser remove / remove <name> -yStop a project and forget it; files and data stay
djoser exec <project> <tool> [arguments]Run a tool inside a project from anywhere
djoser which <tool>Which version a tool runs here, where it was chosen, and its path
djoser config phpList the project's PHP settings
djoser config php memory_limit=1G,upload_max_filesize=200MChange them; memory_limit= removes one
djoser env syncCompare .env with what Djoser runs, and update it after a typed y
djoser deploy / --path <file|folder> / -yWrite deploy.sh for an Ubuntu server (experimental)

Tools

CommandWhat it does
djoser php [arguments]PHP with the project's extensions and settings
djoser artisan [arguments]php artisan, such as djoser artisan migrate --seed
djoser composer [arguments]Composer with the project's PHP
djoser node, npm, npxNode.js tools with the project's version
djoser mysql, mariadb, psql, mongosh, redis-cliConnect to the project's server and database by themselves
djoser mysqldump, mariadb-dump, pg_dumpDump the project's database

Scripts and workers

CommandWhat it does
djoser runList the scripts; for Laravel without any, offer to add six
djoser run <name> [arguments]Run one, such as djoser run test --filter=OrderTest
djoser workersEvery worker, its state, restarts and log
djoser workers start <name>Start one until the next up
djoser workers stop <name>Stop it until the next up; queue means every queue worker, queue-2 one
djoser workers restart <name>Stop and start it
djoser workers start|stop <name> --saveAlso write startup: true|false to djoser.yaml
djoser logsThe workers and their log files
djoser logs <worker> [-n 200] [-f]The end of a log; -f follows it until Ctrl+C
djoser jobsThe newest 50 failed queue jobs
djoser jobs retry <id> / jobs retry allRun them again

Databases

CommandWhat it does
djoser db backupOne file per database (MySQL, MariaDB, PostgreSQL, MongoDB)
djoser db backup --service mysqlOnly one server
djoser db listThe databases and backups, newest first
djoser db restoreThe newest backup of each, after backing up the current data and a typed y
djoser db restore <file>A file from db list, or its full path
djoser db restore --service postgres -yOne server, without asking
djoser tool dbOpen HeidiSQL on the project's database

Sites

CommandWhat it does
djoser trustTrust the local certificate for this user
djoser shareA temporary public address through Cloudflare, until Ctrl+C
djoser portsEvery port Djoser keeps, and who holds it
djoser ports move <service>The first free port after its usual one, through port: in djoser.yaml
djoser ports move mysql 3307That port

Versions

CommandWhat it does
djoser list phpWhat can be installed; also node, composer, mysql, mariadb, postgres, mongodb, redis, rustfs, mailpit
djoser list php --allArchived PHP builds too
djoser list extensionsPHP extensions for this project's PHP
djoser install php 8.5The newest 8.5 patch; 8.5.12 an exact one
djoser install php 8.3.10 --unverifiedAn archived build with no published hash
djoser install node 22, composer latest, mysql 8.4Any service the same way
djoser install php-ext redisA PHP extension; inside a project also added to djoser.yaml
djoser install caddy, heidisql, cloudflared, mongosh, mongodb-toolsA helper program ahead of time
djoser add php C:\phpUse a PHP already on this machine
djoser use php 8.5Choose it for this project, written to djoser.yaml
djoser use php 8.5 --envThe version used outside projects
djoser update php / update php --envThe newest patch of the line, such as 8.5.12 to 8.5.14
djoser runtimesEverything installed
djoser uninstall php 8.5.12 / -yRemove a version; for a database server, offer a backup first

Djoser itself

CommandWhat it does
djoser doctorCheck this machine, and whether a newer Djoser is out
djoser self-update / --check / -yInstall the newest release, checked against its SHA-256
djoser engine start / stop / statusThe background service
djoser servicesEvery process Djoser runs
djoser operations / operations cancel <id>Recent downloads, backups and checks
djoser -vThe version

Sites and HTTPS

Every project is served by Caddy at https://<domain> with a certificate from Djoser's local authority; djoser trust makes browsers accept it. aliases: [www, api, "*"] serves subdomains of the same project, so Laravel subdomain routes work.

Names under .localhost need no setup, and this page opens at https://djoser.localhost as well as 127.0.0.1 and localhost. When port 443 is taken, sites move to another port and up prints the address.

Another domain: the hosts file

Keep .localhost when you can. If a browser or tool will not open it, or you want shop.test, set domain: shop.test and add the name to Windows' hosts file; up prints the lines. Djoser never writes this file itself, since it needs administrator rights.

In PowerShell started with Run as administrator:

Add-Content "$env:windir\System32\drivers\etc\hosts" "`n127.0.0.1 shop.test www.shop.test`n::1 shop.test www.shop.test"
ipconfig /flushdns

Or with Notepad: start it with Run as administrator, open C:\Windows\System32\drivers\etc\hosts (choose All files), add the lines at the end, and save:

127.0.0.1 shop.test www.shop.test
::1       shop.test www.shop.test

The hosts file has no wildcards, so aliases: ["*"] works only under .localhost; list each subdomain instead. To undo, delete the lines and save.

Databases and backups

Each project gets its own database on a shared server; database: picks another name. djoser db backup writes one file per database to Documents\Djoser\Backups\<project>, or the folder backups: names. Backups stay after Djoser is uninstalled, and Djoser never deletes them. djoser db restore backs up what is there first and waits for a typed y.

Scripts and workers

workers: are the scripts up keeps running; they restart when they stop, and down ends them with what they started, such as Vite. Nothing runs until you list it. A stop with djoser workers stop lasts until the next up; --save writes startup: so the file decides from then on.

Deploy to a server experimental

Experimental. You run this script at your own risk. It is meant for someone who knows Linux and has read the script and changed it where needed before running it.

djoser deploy writes one deploy.sh from djoser.yaml. Run as root on a fresh Ubuntu 24.04 or 26.04 server, such as a DigitalOcean Droplet, it prepares the server for this one project: a user, swap, the firewall, PHP from packages.sury.org with the project's extensions and settings, Node.js, the database servers on 127.0.0.1 with the project's database, Nginx with Let's Encrypt, and systemd units for the workers. Everything comes from apt, and each repository is trusted only after its key's fingerprint matches. It does not upload code, write .env, run migrations or start the workers; it prints those steps.

djoser deploy                          # deploy.sh beside djoser.yaml; -y replaces one
ssh root@<server-ip> "mkdir -p /var/www"
scp -r D:\Sites\shop root@<server-ip>:/var/www/shop      # the first time; later copy only what changed
ssh root@<server-ip> "bash /var/www/shop/deploy.sh --domain shop.com --email [email protected]"

Its variables are also flags: --path, --user, --domain, --db-password, --email, --swap, --composer, --build. Mail and S3 are yours to set. In git, keep it with LF endings: *.sh text eol=lf in .gitattributes.

When something is wrong

SignWhat to do
Browsers warn about the certificatedjoser trust, then restart the browser
The address has a port such as :8443Another program has port 443; djoser ports shows which
A service shows faileddjoser services shows its last error
A worker keeps restartingdjoser logs <worker>
A .localhost name will not open in a browser or toolUse another domain through the hosts file
Laravel cannot reach the databasedjoser env sync
Anything elsedjoser doctor
Djoser 0.3.1 · This page is served by Djoser on this machine only.