For local development, the recommended setup is:
- Nix with flakes enabled
- direnv with nix-direnv (optional)
- Docker with the Docker Compose plugin
The Nix dev shell provides PHP, Composer, Node, and process-compose. Docker Compose provides the local MariaDB,
Redis, and Mailpit services.
If you are not using Nix, install the host tools yourself:
- PHP (>= 8.3) with the following extensions
- bcmath
- curl
- intl
- mbstring
- mysql
- redis (required for the default Redis-backed cache, session, and queue config)
- xml
- zip
- Composer
- Node 22 or newer
- process-compose
In addition, a database is required. Currently, only MariaDB is supported (others have not been tested).
Enter the development shell manually:
nix developThe shell adds vendor/bin and node_modules/.bin to PATH and sets PC_CONFIG_FILES to process-compose.yaml.
This repository includes an .envrc that loads the Nix flake. With direnv installed, allow it once per checkout:
direnv allowAfter that, entering the project directory automatically loads the same environment as nix develop. If use flake is
not available in your direnv setup, install nix-direnv or run nix develop manually.
This repository has two Docker Compose-related workflows:
process-compose.yamlruns PHP, Vite, Reverb, the queue worker, and the scheduler on the host, and uses Docker Compose only for MariaDB, Redis, and Mailpit.compose.yamlruns the application stack in containers with FrankenPHP.
For the local process runner, start the dependency services with:
docker compose up --detach --wait mariadb redis mailpitUse docker compose down to stop those services. Add --volumes only when you also want to delete local database,
Redis, and Mailpit data.
On Ubuntu:
sudo apt install php php-{bcmath,curl,intl,mbstring,mysql,redis,xml,zip}
See https://getcomposer.org/download/
Use the Node version from the Nix dev shell. Without Nix, install Node 22 or newer through your operating system, package manager, or another local Node version manager.
See https://mariadb.com/kb/en/mariadb-package-repository-setup-and-usage/
You only need a native MariaDB installation if you are not using the Docker Compose services above.
Install MariaDB on Ubuntu:
sudo apt install mariadb-server
Create the database:
sudo mariadbCREATE DATABASE roomz;CREATE USER 'roomz'@'127.0.0.1' IDENTIFIED BY 'keepMeSe5r3t!';GRANT ALL PRIVILEGES ON roomz.* TO 'roomz'@'127.0.0.1';FLUSH PRIVILEGES;exit
These values match .env.example, where Laravel connects to MariaDB through DB_HOST=127.0.0.1.
- Clone the git repository
- Install php dependencies
composer install
- Install node dependencies
npm install
- Create a dotenv file
cp .env.example .env
- Adjust the dotenv file
- Create an app key
php artisan key:generate
- Create database tables
php artisan migrate
- Create necessary data
php artisan db:seed
- Compile the frontend
- Development:
npm run dev - Production:
npm run build
- Development:
- Start the websockets server
php artisan reverb:start
- Set up a reverse proxy (optional)
- Set up Redis, or change
.envto non-Redis cache, session, and queue drivers - Run queue workers
- Run the scheduler
Permission changes must follow the registry, authorization, and test checklist in
docs/permissions.md.
This repository includes process-compose.yaml for local development. It starts MariaDB, Redis, and Mailpit through
Docker Compose, then runs the Laravel server, Vite, Reverb, the queue worker, and the scheduler on the host.
Enter the dev shell first, unless direnv has already loaded it for you:
nix developFor this hybrid setup, keep the Laravel application host as localhost and point service clients to Docker's
host-exposed ports in .env:
APP_HOST=localhost
APP_URL=http://localhost:8000
DB_HOST=127.0.0.1
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=
VITE_REVERB_HOST=127.0.0.1
VITE_REVERB_PORT=6001
IS_TEST_ACCOUNTS_ENABLED=true
DB_SEED_EXAMPLE_INSTITUTION=trueApply these overrides before running php artisan migrate --seed; the example data flag is only read during seeding.
On first setup, install dependencies and prepare the app:
composer install
npm install
cp .env.example .env
php artisan key:generate
docker compose up --detach --wait mariadb redis mailpit
php artisan migrate --seedThen start the local stack:
process-compose upThe Nix shell and direnv both set PC_CONFIG_FILES to process-compose.yaml because the repository also has Docker's
compose.yaml. Without Nix, install process-compose separately and run:
process-compose -f process-compose.yaml upOpen the app at http://localhost:8000. Do not use http://127.0.0.1:8000 unless you also change APP_HOST, because
the TrustHosts middleware derives trusted hosts from APP_URL.
Use compose.yaml when you want the application to run in containers instead of on the host. The frankenphp service
builds the final frankenphp target from the Dockerfile, serves public/ through Caddy and FrankenPHP, proxies
websocket requests under /app/* to the reverb service, and exposes Mailpit under /mailpit.
The image leaves the development dependencies out, so an error inside the stack shows the plain page. Build with
COMPOSER_NO_DEV=0 to keep them and get the interactive one (.env also needs APP_DEBUG=true, which
.env.example already sets):
COMPOSER_NO_DEV=0 docker compose up --build --detach --waitThe container build and runtime both read .env as a Docker secret. Generate APP_KEY on the host before building,
because the secret is mounted read-only inside the containers:
cp .env.example .env
composer install
php artisan key:generateIf you are using the local process runner setup above, reuse the .env you already prepared. Then build the image,
start the service containers, run migrations, and start the full stack:
docker compose build
docker compose up --detach --wait mariadb redis mailpit
docker compose run --rm frankenphp php artisan migrate --seed
docker compose up --detachOpen the app at the configured APP_URL. With the default .env.example, that is http://localhost:8000. Mailpit is
available at /mailpit on the same host.
Set IS_TEST_ACCOUNTS_ENABLED=true in .env to enable the local test accounts. Their default credentials are:
- Regular user 1:
- Username: test1
- Password: test1
- Regular user 2:
- Username: test2
- Password: test2
- Admin user:
- Username: admin
- Password: admin
IMPORTANT: You must change these passwords in production.
When running on a production server, you probably want to proxy the websocket connections (since you may not have full
control over the firewall). The sample configs assume the app is deployed under /srv/git/roomz/ and Reverb listens
on 127.0.0.1:6001.
Module rewrite must be enabled.
Module proxy_wstunnel must be enabled.
Use deployment/apache.conf as the starting point.
Use deployment/nginx.conf as the starting point. It assumes PHP-FPM is running locally; adjust the PHP-FPM socket
path if your distribution uses a different version or service name.
Sample systemd units for the app-managed production services are in deployment/systemd/:
roomz-reverb.serviceruns the Laravel Reverb websocket server.roomz-queue.serviceruns the Laravel queue worker.roomz-scheduler.serviceruns the Laravel scheduler.
The units assume:
- The repository is deployed to
/srv/git/roomz. - PHP is available in the systemd service
PATH; otherwise replace/usr/bin/env phpwith the absolute PHP path. - The services run as
www-data:www-data. - MariaDB and Redis use one of the common distro service names referenced in the
After=lines.
Adjust those values before installing the units. Then copy and enable them:
sudo cp deployment/systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now roomz-reverb.service roomz-queue.service roomz-scheduler.serviceFor per-branch review environments, see review app setup and operations.
The GitLab deploy jobs SSH into the target host, check out the selected commit, and run scripts/deploy.sh with the
environment-specific build prefix and flags. For the current deployment workflow, redeploy by running:
scripts/deploy.sh "$BUILD_PREFIX"The script installs PHP and Node dependencies, warms Laravel caches with php artisan optimize --except=routes,
runs forced migrations with seeders, and builds the frontend with
npm run build -- --base="$BUILD_PREFIX/build".
Two optional flags trade redeployment time for disk:
--no-devpasses--no-devtocomposer install, which takesvendor/from about 500 MB to 70 MB.--prune-node-modulesdeletesnode_modulesafter the frontend build, saving a further 350 MB.
scripts/deploy.sh --no-dev --prune-node-modules "$BUILD_PREFIX"Both deploy jobs pass --no-dev. Nothing on either host runs the test suite or the linters, and one development
dependency renders a debug page; what a host does need is required for production.
Neither deploy job passes --prune-node-modules; both hosts keep node_modules so a redeployment does not
reinstall it. Review environments do pass it, and both flags, because they are built to be thrown away.
Seeding survives --no-dev: the factories the seeders use need fakerphp/faker, which is why it is a production
requirement rather than a development one.
If you need to run the steps manually, keep the same order:
composer install
npm clean-install
php artisan optimize --except=routes
php artisan migrate --force --seed
npm run build -- --base="$BUILD_PREFIX/build"After deploying new code, restart the PHP application, Reverb, queue worker, and schedule worker via your process supervisor so long-running processes use the new code and cached configuration. With the sample systemd units, restart the app-managed services with:
sudo systemctl restart roomz-reverb.service roomz-queue.service roomz-scheduler.serviceThis application is licensed under the GNU General Public License v3.0 (GPL-3.0-or-later). See
LICENSE for the full text.