96 lines
3.2 KiB
Markdown
96 lines
3.2 KiB
Markdown
# Bowler
|
|
|
|
A multi-user website for managing shared bowler charts — tracking project status and KPIs.
|
|
|
|
This is the Phase 1 foundation: Docker environment, Hello World landing page, login, and user administration. Bowler chart functionality comes next.
|
|
|
|
## Requirements
|
|
|
|
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (or Docker Engine + Compose v2)
|
|
|
|
Nothing else — no local PHP, Composer, or Node needed. The app container installs its own dependencies on first boot.
|
|
|
|
## Quick start
|
|
|
|
1. Copy the environment template and set your own passwords:
|
|
|
|
```
|
|
copy .env.example .env
|
|
```
|
|
|
|
Edit `.env` and set:
|
|
- `DB_PASSWORD` / `DB_ROOT_PASSWORD` — Percona database credentials
|
|
- `ADMIN_EMAIL` / `ADMIN_PASSWORD` — the initial site administrator login
|
|
- `APP_KEY` — a random base64 key. Generate one with:
|
|
```
|
|
docker run --rm php:8.4-cli php -r "echo 'base64:' . base64_encode(random_bytes(32)) . PHP_EOL;"
|
|
```
|
|
|
|
*(A ready-to-use development `.env` is already included in this repo.)*
|
|
|
|
2. Start the stack:
|
|
|
|
```
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
First boot takes a few minutes: the app container runs `composer install`, waits for the
|
|
database, runs migrations, and seeds the initial administrator. Watch progress with
|
|
`docker-compose logs -f app`.
|
|
|
|
3. Open [http://localhost:8080](http://localhost:8080) and log in with `ADMIN_EMAIL` / `ADMIN_PASSWORD`.
|
|
|
|
## What's included
|
|
|
|
| URL | Description |
|
|
|---|---|
|
|
| `/` | Hello World landing page |
|
|
| `/login` | Login (rejects disabled accounts, throttled to 10 attempts/min) |
|
|
| `/admin/users` | User management (admins only): create users, reset passwords, enable/disable accounts |
|
|
|
|
Admins cannot disable their own account, so you can't lock yourself out.
|
|
|
|
## Project layout
|
|
|
|
```
|
|
docker-compose.yml # app (PHP 8.4 + Apache) + db (Percona latest)
|
|
.env # all credentials & app config (never commit real secrets)
|
|
docker/app/ # app image: Dockerfile + startup script
|
|
src/ # the Laravel application (bind-mounted into the container)
|
|
db-data/ # Percona data files (created on first run)
|
|
```
|
|
|
|
## Styling (Tailwind CSS)
|
|
|
|
The UI is styled with [Tailwind CSS](https://tailwindcss.com) v4 using the **standalone CLI**
|
|
baked into the app image — no Node.js/npm required anywhere. The source file is
|
|
`src/resources/css/app.css`; the compiled stylesheet `src/public/css/app.css` is generated
|
|
automatically on every container start.
|
|
|
|
While editing Blade views, run the optional watcher so CSS rebuilds live:
|
|
|
|
```sh
|
|
docker compose --profile dev up -d # starts the app + a tailwind --watch container
|
|
```
|
|
|
|
Or rebuild once by hand:
|
|
|
|
```sh
|
|
docker compose exec app tailwindcss -i resources/css/app.css -o public/css/app.css --minify
|
|
```
|
|
|
|
## Common operations
|
|
|
|
```sh
|
|
docker-compose logs -f app # tail application logs
|
|
docker-compose exec app php artisan migrate # run new migrations
|
|
docker-compose exec app php artisan tinker # interactive REPL
|
|
docker-compose down # stop (data persists in db-data/)
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
- Bowler chart data model and CRUD
|
|
- Multiple charts with per-chart owners and collaborators
|
|
- PDF / printer export of bowler summaries
|