rename readme

2026-10-30 09:45:34 +01:00
parent d2bd589c96
commit 84f5f0c788
1 changed files with 0 additions and 0 deletions
@@ -0,0 +1,96 @@
+# 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 start` | 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).