pollux/README.md

Pollux

Pollux is a small Laravel 5.6 bookkeeping application for managing bookings, projects, people, targets, and reports.

Local development

The application targets PHP 7.4 and MySQL 5.7. Those old runtimes are run in Docker so they do not have to be installed on the host. mise manages the host-side tools: Just and Node 10 (required by the old Laravel Mix 2 asset pipeline).

Prerequisites

• Docker with Compose v2 (docker compose)
• mise

First run

mise install
just setup
just up

Then open http://localhost:8000. A development login is created automatically:

• Email: dev@pollux.local
• Password: password

just setup builds the PHP image, installs Composer dependencies, creates .env from .env.docker.example, generates APP_KEY, starts MySQL, runs migrations, and loads the constant and demo data.

Everyday commands

Command	Description
just up	Start the app and database in the foreground
just up -d	Start the app and database in the background
just down	Stop the app and database
just logs	Follow container logs
just artisan <command>	Run an Artisan command
just composer <command>	Run a Composer command
just shell	Open a shell in the app container
just db	Open a MySQL shell
just migrate	Run migrations
just seed	Add the demo/test dataset to an existing database
just seed-real	Recreate the database and load the full dataset from database/seeds/data/real
just fresh	Drop and recreate the database, then load demo data
just test	Run PHPUnit
just assets	Install npm packages and build frontend assets
just watch	Rebuild frontend assets on change

Run just --list to see the full list.

Database

MySQL is exposed on host port 3307 so it does not clash with a local MySQL on 3306. The database is pollux with username pollux and password secret. The app container connects to the db service on port 3306.

Data lives in the Docker volume pollux_mysql-data. just down keeps the data; use docker compose down -v if you want to remove it as well.

Frontend assets

Node 10 is pinned in mise.toml because Laravel Mix 2 and node-sass do not run on current Node versions. Prebuilt assets are committed, so just assets is not needed just to run the application.

Tests

just test

just test starts a separate MySQL 5.7 service (db-test) and runs PHPUnit in the PHP container. The pollux_test database uses temporary storage, has no published port, and is separate from the development database and its volume. Tests migrate this database automatically and roll back their fixtures after each test. No demo or real-data seeders are needed. Run just setup first on a new checkout to build the PHP image and install dependencies.

To run a focused subset:

just test --filter BookingsTest

Coverage includes login/logout and guest access, booking forms and changes, split entries, validation, deletion cascades, income/expense totals, monthly balances, year boundaries, project and scope reports, and target payment states. These are PHP HTTP/database tests; they do not exercise browser JavaScript.

PHPUnit forces isolated database settings, and the test bootstrap refuses to run against another database configuration. If cached application configuration prevents testing, run just artisan config:clear. just down also stops the test database; its temporary data is discarded when the container stops.

Legacy compatibility notes

This project uses several old dependencies, so a few small compatibility fixes are included:

Temporary workarounds and legacy runtime pins are marked TODO(compat) in the source, with the condition for removing or replacing each one. Search for this marker during upgrades. In particular, remove the test artisan() override once Laravel's inherited helper works, and remove both the package-manifest patch and its Composer hook once Laravel supports Composer 2 directly.

The test startup timestamp, isolated database settings, and database safety check are normal test infrastructure, not temporary version workarounds.

• phpdocumentor/phpdocumentor 2.* was removed from require-dev. It requires Symfony 2.x, conflicts with Laravel 5.6, and was never present in composer.lock.
• scripts/patch-package-manifest.php runs after Composer's autoload dump. It adds Composer 2 support to Laravel 5.6's package discovery, which otherwise fails with Undefined index: name.
• fzaninotto/faker was updated to 1.9.2 for PHP 7.4 compatibility.
• bookings.note is created as TEXT because the full dataset in database/seeds/data/real contains notes longer than the default 191-character string length.

License

Pollux is open-sourced software licensed under the MIT license.