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
| Command | What it does |
|---|---|
djoser init | Ask 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.5 | Answer from the command line; the rest are asked |
djoser init -y | Take every default |
djoser up | Start what djoser.yaml asks for, downloading what is missing; again after an edit |
djoser down | Stop the site, the servers only it uses, and its workers |
djoser status | Address, services, workers, memory, failed jobs, and changes since the last up |
djoser status -w | The same, redrawn every 2 seconds until Ctrl+C |
djoser ps / ps -a | Running projects; -a adds stopped ones |
djoser projects | Every project Djoser knows, with its folder |
djoser remove / remove <name> -y | Stop 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 php | List the project's PHP settings |
djoser config php memory_limit=1G,upload_max_filesize=200M | Change them; memory_limit= removes one |
djoser env sync | Compare .env with what Djoser runs, and update it after a typed y |
djoser deploy / --path <file|folder> / -y | Write deploy.sh for an Ubuntu server (experimental) |
Tools
| Command | What 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, npx | Node.js tools with the project's version |
djoser mysql, mariadb, psql, mongosh, redis-cli | Connect to the project's server and database by themselves |
djoser mysqldump, mariadb-dump, pg_dump | Dump the project's database |
Scripts and workers
| Command | What it does |
|---|---|
djoser run | List the scripts; for Laravel without any, offer to add six |
djoser run <name> [arguments] | Run one, such as djoser run test --filter=OrderTest |
djoser workers | Every 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> --save | Also write startup: true|false to djoser.yaml |
djoser logs | The workers and their log files |
djoser logs <worker> [-n 200] [-f] | The end of a log; -f follows it until Ctrl+C |
djoser jobs | The newest 50 failed queue jobs |
djoser jobs retry <id> / jobs retry all | Run them again |
Databases
| Command | What it does |
|---|---|
djoser db backup | One file per database (MySQL, MariaDB, PostgreSQL, MongoDB) |
djoser db backup --service mysql | Only one server |
djoser db list | The databases and backups, newest first |
djoser db restore | The 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 -y | One server, without asking |
djoser tool db | Open HeidiSQL on the project's database |
Sites
| Command | What it does |
|---|---|
djoser trust | Trust the local certificate for this user |
djoser share | A temporary public address through Cloudflare, until Ctrl+C |
djoser ports | Every 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 3307 | That port |
Versions
| Command | What it does |
|---|---|
djoser list php | What can be installed; also node, composer, mysql, mariadb, postgres, mongodb, redis, rustfs, mailpit |
djoser list php --all | Archived PHP builds too |
djoser list extensions | PHP extensions for this project's PHP |
djoser install php 8.5 | The newest 8.5 patch; 8.5.12 an exact one |
djoser install php 8.3.10 --unverified | An archived build with no published hash |
djoser install node 22, composer latest, mysql 8.4 | Any service the same way |
djoser install php-ext redis | A PHP extension; inside a project also added to djoser.yaml |
djoser install caddy, heidisql, cloudflared, mongosh, mongodb-tools | A helper program ahead of time |
djoser add php C:\php | Use a PHP already on this machine |
djoser use php 8.5 | Choose it for this project, written to djoser.yaml |
djoser use php 8.5 --env | The version used outside projects |
djoser update php / update php --env | The newest patch of the line, such as 8.5.12 to 8.5.14 |
djoser runtimes | Everything installed |
djoser uninstall php 8.5.12 / -y | Remove a version; for a database server, offer a backup first |
Djoser itself
| Command | What it does |
|---|---|
djoser doctor | Check this machine, and whether a newer Djoser is out |
djoser self-update / --check / -y | Install the newest release, checked against its SHA-256 |
djoser engine start / stop / status | The background service |
djoser services | Every process Djoser runs |
djoser operations / operations cancel <id> | Recent downloads, backups and checks |
djoser -v | The 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
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
| Sign | What to do |
|---|---|
| Browsers warn about the certificate | djoser trust, then restart the browser |
The address has a port such as :8443 | Another program has port 443; djoser ports shows which |
A service shows failed | djoser services shows its last error |
| A worker keeps restarting | djoser logs <worker> |
A .localhost name will not open in a browser or tool | Use another domain through the hosts file |
| Laravel cannot reach the database | djoser env sync |
| Anything else | djoser doctor |
Nothing matches.