# 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
```

## Legacy compatibility notes

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

- `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).