bert.hausmans
932788c643
Operational docs for the GlitchTip stack landed in the previous two commits. - dev-docs/GLITCHTIP.md: new runbook covering local dev, project provisioning + DSN-to-vault flow, production deploy on monitoring.hausdesign.nl (DNS, DirectAdmin Let's Encrypt, Apache reverse proxy with WS upgrade), backup install + restore drill, smoke tests, troubleshooting. - dev-docs/SETUP.md: services table now includes GlitchTip; new docker/glitchtip/.env subsection points at the runbook. - dev-docs/RFC-WS-7-OBSERVABILITY.md §3.1: amended to record that the same compose file drives local dev (Mailpit at bm_mailpit:1025), so prod and dev cannot drift. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
231 lines
6.1 KiB
Markdown
231 lines
6.1 KiB
Markdown
# Crewli — Working in this repo
|
|
|
|
A guide for developers continuing work on the Crewli codebase. Assumes you've cloned the repo and have basic terminal familiarity.
|
|
|
|
## Prerequisites
|
|
|
|
Install these once before starting:
|
|
|
|
| Tool | Version | Install (macOS via Homebrew) |
|
|
|------|---------|------------------------------|
|
|
| PHP | 8.4 | `brew install php@8.4 && brew link php@8.4` |
|
|
| Composer | 2.x | `brew install composer` |
|
|
| Node.js | 20 LTS | `brew install fnm && fnm install 20 && fnm use 20` |
|
|
| pnpm | 9.x | `npm install -g pnpm` |
|
|
| Docker Desktop | latest | https://www.docker.com/products/docker-desktop/ |
|
|
|
|
Verify:
|
|
|
|
```bash
|
|
php -v # 8.4.x
|
|
composer -V # 2.x
|
|
node -v # v20.x
|
|
pnpm -v # 9.x or 10.x
|
|
docker -v # any recent version
|
|
```
|
|
|
|
## First-time setup
|
|
|
|
From the repo root:
|
|
|
|
```bash
|
|
# 1. Backend dependencies
|
|
cd api && composer install
|
|
|
|
# 2. Frontend dependencies
|
|
cd ../apps/app && pnpm install
|
|
|
|
# 3. Backend env file
|
|
cd ../../api
|
|
cp .env.example .env
|
|
php artisan key:generate
|
|
|
|
# 4. Frontend env file
|
|
cd ../apps/app
|
|
cp .env.example .env.local
|
|
|
|
# 5. Start Docker services (MySQL, Redis, Mailpit)
|
|
cd ..
|
|
make services
|
|
|
|
# 6. Database setup
|
|
cd api
|
|
php artisan migrate --seed
|
|
|
|
# 7. Frontend post-install (icon build + MSW worker)
|
|
cd ../apps/app
|
|
pnpm run build:icons
|
|
pnpm run msw:init
|
|
|
|
# 8. Verify everything works
|
|
cd ../../api
|
|
php artisan test
|
|
```
|
|
|
|
If `php artisan test` is green, you're ready.
|
|
|
|
## Daily workflow
|
|
|
|
Three terminal tabs, plus an optional fourth for the queue worker:
|
|
|
|
| Terminal | Command | Where it runs | Port |
|
|
|----------|---------|---------------|------|
|
|
| 1. Services | `make services` (from repo root) | Docker | 3306 (MySQL), 6379 (Redis), 8025 (Mailpit), 8200 (GlitchTip) |
|
|
| 2. API | `make api` (from repo root) | Laravel dev server | 8000 |
|
|
| 3. SPA | `make app` (from repo root) | Vite dev server | 5174 |
|
|
| 4. Queue worker (optional) | `cd api && php artisan queue:listen redis --queue=emails` | Local PHP | n/a |
|
|
|
|
Web UIs available once `make services` is up:
|
|
|
|
| Service | URL |
|
|
|---------|-----|
|
|
| Mailpit | <http://localhost:8025> |
|
|
| GlitchTip | <http://localhost:8200> (admin UI; first boot ~60s while migrations run) |
|
|
|
|
The queue worker is only needed when you're triggering email flows (registration, password reset, email change, invitations). Routine UI work doesn't require it.
|
|
|
|
Stop services when done: `make services-stop`.
|
|
|
|
## Environment variables
|
|
|
|
### `api/.env`
|
|
|
|
The defaults from `.env.example` cover local development. Key entries:
|
|
|
|
```env
|
|
DB_DATABASE=crewli
|
|
DB_USERNAME=crewli
|
|
DB_PASSWORD=secret
|
|
QUEUE_CONNECTION=redis
|
|
SESSION_DOMAIN=localhost
|
|
FRONTEND_APP_URL=http://localhost:5174
|
|
SANCTUM_STATEFUL_DOMAINS=localhost:5174
|
|
APP_URL=http://localhost:8000
|
|
```
|
|
|
|
For production deployment (registered domain `crewli.app`):
|
|
|
|
```env
|
|
APP_URL=https://api.crewli.app
|
|
FRONTEND_APP_URL=https://crewli.app
|
|
SESSION_DOMAIN=.crewli.app
|
|
SANCTUM_STATEFUL_DOMAINS=crewli.app
|
|
```
|
|
|
|
`crewli.nl` is reserved for a future marketing site only — not the application.
|
|
|
|
### `apps/app/.env.local`
|
|
|
|
```env
|
|
VITE_API_URL=http://localhost:8000
|
|
VITE_APP_NAME="Crewli"
|
|
```
|
|
|
|
For production: `VITE_API_URL=https://api.crewli.app`.
|
|
|
|
### `docker/glitchtip/.env`
|
|
|
|
Generated by copying `docker/glitchtip/.env.example`. Dev defaults are
|
|
functional out of the box — no edits needed for `make services`. See
|
|
[`GLITCHTIP.md`](./GLITCHTIP.md) for first-boot steps (creating the
|
|
superuser, creating the two projects, copying DSNs to 1Password).
|
|
|
|
## Common tasks
|
|
|
|
### Run tests
|
|
|
|
```bash
|
|
# Backend (PHPUnit, all tests)
|
|
cd api && php artisan test
|
|
|
|
# Backend (specific filter)
|
|
cd api && php artisan test --filter=ShiftTest
|
|
|
|
# Backend (with coverage)
|
|
cd api && php artisan test --coverage
|
|
|
|
# Frontend (Vitest, all tests)
|
|
cd apps/app && pnpm test
|
|
|
|
# Frontend (typecheck)
|
|
cd apps/app && pnpm typecheck
|
|
|
|
# Frontend (lint)
|
|
cd apps/app && pnpm lint
|
|
```
|
|
|
|
### Database reset
|
|
|
|
```bash
|
|
cd api && php artisan migrate:fresh --seed
|
|
```
|
|
|
|
This drops all tables, re-runs migrations, and re-seeds. Useful when schema changes or seeders are updated.
|
|
|
|
### Inspect routes
|
|
|
|
```bash
|
|
cd api && php artisan route:list --path=api/v1
|
|
```
|
|
|
|
### Build for production
|
|
|
|
```bash
|
|
cd apps/app && pnpm build
|
|
```
|
|
|
|
Output lands in `apps/app/dist/`. The `deploy.sh` script handles the rest for VPS deploys.
|
|
|
|
### Static analysis (optional)
|
|
|
|
```bash
|
|
cd api && composer analyse # Larastan / PHPStan level 6
|
|
cd api && composer rector --dry-run # Rector findings
|
|
```
|
|
|
|
## Documentation reference
|
|
|
|
The `dev-docs/` directory is the developer source of truth. The most-used files:
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `/CLAUDE.md` | Project conventions, vibe-coding principles, Vuexy-first decision tree (auto-loaded by Claude Code) |
|
|
| `dev-docs/SCHEMA.md` | Database schema (current version v2.x, kept in sync with migrations) |
|
|
| `dev-docs/API.md` | API contract |
|
|
| `dev-docs/AUTH_ARCHITECTURE.md` | Auth design (httpOnly cookies, MFA, impersonation, portal tokens) |
|
|
| `dev-docs/CLAUDE_CODE_TOOLING.md` | The `.claude/` deterministic guard-rail layer (hooks, subagent, slash commands) |
|
|
| `dev-docs/VUEXY_COMPONENTS.md` | Vuexy component registry — consult before writing any frontend |
|
|
| `dev-docs/BACKLOG.md` | Tracked tech debt and follow-ups |
|
|
| `dev-docs/ARCH-*.md` | Architecture decisions per workstream (consolidation, form builder, bindings, API validation) |
|
|
|
|
The `docs/` directory (separate from `dev-docs/`) is end-user VitePress documentation in Dutch.
|
|
|
|
## Troubleshooting
|
|
|
|
### MySQL connection refused
|
|
|
|
```bash
|
|
docker ps # check containers are up
|
|
make services-stop && make services # restart
|
|
```
|
|
|
|
### Port 8000 already in use
|
|
|
|
Something else is bound to port 8000. Find it: `lsof -i :8000`. Kill it or change `make api` to use another port.
|
|
|
|
### Frontend TypeScript errors after pulling main
|
|
|
|
```bash
|
|
cd apps/app
|
|
pnpm install # picks up new dependencies
|
|
pnpm typecheck # confirm clean
|
|
```
|
|
|
|
### Queue worker not picking up jobs
|
|
|
|
Confirm Redis is running: `docker ps | grep redis`. If yes, restart the queue worker — long-running listeners can drift after long idle periods.
|
|
|
|
### Test suite is slow
|
|
|
|
PHPUnit defaults to a single process. Parallel: `cd api && php artisan test --parallel`.
|