129 lines
4.9 KiB
Markdown
129 lines
4.9 KiB
Markdown
# 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](https://mise.jdx.dev/)
|
|
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](https://mise.jdx.dev/)
|
|
|
|
### First run
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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](https://opensource.org/licenses/MIT).
|