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 (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 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)

Common operations

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