lazis002/NextChair
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PHP Rebuild
CI / ci (push) Canceled after 0s
Details

Browse Source 
Initial PHP rebuild of the app
This commit is contained in:
Stefan Lazic committed 2026-09-05 08:21:33 +01:00
1 parent 8a2b211069
commit 2ef3654841
690 files changed
+33944 -12046
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+22 -371
View File
@@ -1,383 +1,34 @@
+# NextChair
# NextChair
NextChair is a white-label, mobile-first booking platform for barbershops. It combines customer booking, staff scheduling, owner administration, notifications, loyalty, media, reviews, and optional Google integrations in one Next.js application.
NextChair is a multi-tenant, white-label booking platform for barbershops.
The application is being rebuilt as a conventional Laravel web application
using PHP, MySQL, Blade, Tailwind CSS, Alpine.js, and Vite.
## Technology
The audited Next.js implementation is preserved in [`legacy-nextjs`](legacy-nextjs)
as the functional and visual migration reference. Deployment-specific files
from the previous implementation are retained there for reference only; the
Laravel application does not manage Docker, Caddy, Nginx, or server
provisioning.
- Next.js 16 with the App Router and React 19
- TypeScript 6
- MySQL 8.0, accessed through Prisma 7 and the MariaDB driver adapter
- Auth.js / NextAuth v5 for authentication
- Tailwind CSS 4, Radix UI, Lucide, and Font Awesome
- Vitest for unit and integration tests
- Playwright for browser tests
- Docker Compose for a production-style local deployment
The application is intentionally configured with discrete database settings: `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USER`, and `DATABASE_PASSWORD`. It does not use `DATABASE_URL` at runtime.
## Deployment Model
The intended deployment model is one repeatable Docker deployment for both a
local/self-hosted Debian server and production:
- One Dockge-managed Caddy stack owns ports 80 and 443 and routes each domain.
- One Dockge-managed MySQL 8 stack hosts a separate database and user per business.
- Each business is a separate Dockge stack with its own media volume and env file.
- Business containers publish no host ports and share only the proxy and database networks.
- Each business is installed independently through `/install` after its stack starts.
`deploy/business-compose.yaml.template` and `scripts/create-business.sh` are the
canonical business deployment path. The local Docker file remains useful for a
single isolated development instance.
## Requirements
For local Node development:
- Node.js 22 or later
- npm
- A reachable MySQL 8.0 database
For the primary VPS deployment:
- A Linux VPS with Docker Engine and Docker Compose
- A domain per business, with DNS pointing at the VPS
- Ports 80 and 443 available for Caddy and Let's Encrypt
- Dockge configured to scan the directory containing the generated stacks
For local development:
- Docker Desktop with Docker Compose
## Local Docker Desktop (Isolated Business Instance)
This is a disposable local approximation of one business from the VPS deployment. It starts one MySQL container and one NextChair container, applies migrations automatically, and leaves the database empty until you either complete the installer or explicitly run the demo seed. It is not the shared multi-business topology; use the VPS setup above for the canonical deployment.
1. Install dependencies if you also plan to run commands on the host:
```bash
npm ci
```
2. Create the Docker environment file:
```bash
cp .env.local.example .env.local
```
3. Replace the placeholder values in `.env.local`. At minimum, set strong values for:
- `MYSQL_PASSWORD`
- `MYSQL_ROOT_PASSWORD`
- `DATABASE_PASSWORD`
- `AUTH_SECRET`
- `INSTALLATION_TOKEN`
- `CRON_SECRET`
`DATABASE_NAME`, `DATABASE_USER`, and `DATABASE_PASSWORD` must match the corresponding MySQL container settings. Inside Docker, `DATABASE_HOST` must remain `next-chair-mysql`, not `localhost`.
Generate suitable secrets with:
```bash
openssl rand -hex 32
npx auth secret
```
4. Build and start the stack:
```bash
docker compose -p next-chair -f docker-compose.local.yaml --env-file .env.local up --build -d
```
5. Open [http://localhost:3000](http://localhost:3000). If the database has not been installed, the application redirects to `/install`. Enter the `INSTALLATION_TOKEN` and complete the wizard to create the first business and owner account.
6. Follow the application logs when needed:
```bash
docker compose -p next-chair -f docker-compose.local.yaml --env-file .env.local logs -f next-chair
```
The application health endpoint is [http://localhost:3000/api/health](http://localhost:3000/api/health). It returns HTTP 200 when the database is reachable, even before the installation wizard has been completed.
### Docker lifecycle commands
## Local development
```bash
# Stop containers but keep database and media volumes
docker compose -p next-chair -f docker-compose.local.yaml --env-file .env.local down
# Start again without rebuilding
docker compose -p next-chair -f docker-compose.local.yaml --env-file .env.local up -d
# Run the development/demo fixture explicitly
docker compose -p next-chair -f docker-compose.local.yaml --env-file .env.local run --rm next-chair-seed
# Remove containers and all local database/media data
docker compose -p next-chair -f docker-compose.local.yaml --env-file .env.local down -v
composer install
cp .env.example .env
php artisan key:generate
npm install
npm run build
php artisan serve
```
The seed service is opt-in. Normal `up` never seeds the database. `down -v` is destructive for this local deployment: it removes the named MySQL and media volumes.
Configure the MySQL connection in `.env` before running migrations. The
application resolves a business from the request hostname through the
`business_domains` table. Local development can use a configured local domain
or the `APP_DEFAULT_BUSINESS_SLUG` fallback.
## Local Node Development
Use this path when you already have MySQL running outside Docker or want fast Next.js source reloads.
1. Install dependencies:
```bash
npm ci
```
2. Create `.env.local` from `.env.example` and configure a local MySQL 8 database. Set `DATABASE_HOST=localhost` and make sure the database and user already exist.
3. Generate the Prisma client and apply development migrations:
```bash
npm run prisma:generate
npm run prisma:migrate
```
4. Start the development server:
```bash
npm run dev
```
Open [http://localhost:3000](http://localhost:3000).
5. Choose one database bootstrap path:
- For a real, empty installation, do not seed. Use `/install` with `INSTALLATION_TOKEN`.
- For development fixtures, run:
```bash
npm run prisma:seed
```
The seed is idempotent and creates demo business, staff, services, customers, appointments, and related records. It marks the database as installed so the application can be used immediately. Do not run it alongside a real first-run installation.
The direct Node path and the local Docker path should use different `.env.local` values: Docker connects to `next-chair-mysql`, while a host-run Next.js process normally connects to `localhost`. Business stacks use `DATABASE_HOST=nextchair-mysql` on the shared database network.
## Environment Configuration
The available templates are:
- `.env.example`: host-run development configuration
- `.env.local.example`: Docker Desktop configuration
- `.env.infra.example`: shared MySQL root settings
- `stacks/caddy/.env.example`: shared Caddy ACME email
- `.env.business.example`: generated business environment reference
Required for a basic running installation:
- MySQL settings: `DATABASE_*`
- `AUTH_SECRET`
- `NEXT_PUBLIC_APP_URL`
- `INSTALLATION_TOKEN`
- `CRON_SECRET`
- `AUTH_TRUST_HOST=true` when serving through a non-localhost host or reverse proxy
Optional integrations are disabled safely when left unconfigured:
- Google sign-in: `AUTH_GOOGLE_ID`, `AUTH_GOOGLE_SECRET`
- Google Calendar sync: `GOOGLE_CALENDAR_*`, `CALENDAR_TOKEN_ENCRYPTION_KEY`
- Google Reviews: `GOOGLE_PLACES_API_KEY`
- SMTP email: set `EMAIL_PROVIDER=brevo` and provide the `EMAIL_SMTP_*` and `EMAIL_FROM_ADDRESS` values. The default `console` provider logs notifications instead of sending them.
- Web Push: set `PUSH_PROVIDER=web-push` and provide the VAPID keys. Generate them with `npx web-push generate-vapid-keys`.
- Platform super administrator: `SUPER_ADMIN_EMAIL`, `SUPER_ADMIN_PASSWORD`, `SUPER_ADMIN_FIRST_NAME`, and `SUPER_ADMIN_LAST_NAME`
Do not commit `.env.local`, production environment files, OAuth secrets, SMTP credentials, VAPID private keys, or encryption keys.
## Application Flow
The application has a deliberate first-run gate:
1. A fresh database is migrated by Prisma.
2. Requests are redirected to `/install`, except for the installer and required static/PWA assets.
3. The installer validates `INSTALLATION_TOKEN`, then creates the business, primary location, settings, hours, booking rules, loyalty configuration, starter services, owner role, and first administrator in one transaction.
4. After installation, `/staff` and `/owner` require authentication and permissions. Customer browsing and booking routes remain available according to the business booking rules.
The installation token is checked server-side and rate-limited. It is never stored in the database. The installer is one-way for a deployment: to start over locally, remove the local database volume or use a separate database rather than attempting to reinstall over existing data.
## Database and Prisma
Useful commands:
## Verification
```bash
npm run prisma:generate # Generate the client in generated/prisma
npm run prisma:migrate # Create/apply a development migration
npm run prisma:studio # Open Prisma Studio
npm run prisma:seed # Load idempotent development fixtures
```
For a deployed database, the container entrypoint runs:
```bash
npx prisma migrate deploy
npx tsx scripts/ensure-super-admin.ts
```
Migrations are applied on every application container start and are not destructive. The optional seed is separate because demo data is not an appropriate production bootstrap mechanism.
## Quality Checks and Tests
Run the fast checks first:
```bash
npm run typecheck
npm run lint
npm test
```
Additional commands:
```bash
npm run test:watch
npm run test:integration
npm run test:e2e
php artisan test
npm run build
```
Unit tests do not require a database. Integration tests require a disposable MySQL 8 database configured through the `DATABASE_*` variables. They apply migrations but the caller is responsible for providing the database.
The Playwright suite starts a development server on port `3100`, applies migrations, loads the demo seed, and provisions test credentials. Point it at a throwaway database, never a database containing real business data:
```bash
DATABASE_HOST=localhost \
DATABASE_PORT=3306 \
DATABASE_NAME=nextchair_e2e \
DATABASE_USER=nextchair \
DATABASE_PASSWORD='replace-me' \
npm run test:e2e
```
Playwright uses one Chromium project, one worker, a 45-second test timeout, screenshots on failure, and retains traces on failure. The database should be reset or recreated between isolated test runs when fixtures from previous runs could affect results.
## Docker Server Deployment
This is the same topology for a Debian self-hosted server and a production
server. The only intentional deployment difference is the image tag: build
`nextchair:latest` locally, or use a registry tag such as
`registry.example.com/nextchair:2026-09-04` in production.
### 1. Prepare the server
Copy this repository's deployment files to a stable directory, for example
`/opt/nextchair`, and configure Dockge to use `/opt/nextchair/stacks` as its
stack directory. The tracked `infra` and `caddy` directories are shared
stacks; every generated business directory sits beside them.
Build or pull the application image once:
```bash
# Self-hosted/local image
docker build -t nextchair:latest .
# Production image example
docker pull registry.example.com/nextchair:2026-09-04
```
Create the shared networks and start the two infrastructure stacks:
```bash
cp .env.infra.example .env.infra
cp stacks/caddy/.env.example stacks/caddy/.env
# Edit both env files before starting them.
docker network create nextchair-db
docker network create nextchair-proxy
docker compose -f stacks/infra/compose.yaml up -d
docker compose -f stacks/caddy/compose.yaml up -d
```
Start the Manager stack as well, after copying its environment template and
setting a strong platform-admin password and auth secret:
```bash
cp stacks/manager/.env.example stacks/manager/.env
docker compose -f stacks/manager/compose.yaml up -d
```
Add a Manager-only Caddy route in `stacks/caddy/sites/manager.caddy`, replacing
the example hostname with the private/admin hostname you control:
```caddy
manager.example.com {
reverse_proxy nextchair-manager:3000
}
```
Reload Caddy after adding the route, then open `/manager`. The Manager has its
own administrator session and does not use any business customer, staff, or
owner account.
The MySQL port is loopback-only by default. Use an SSH tunnel for database
administration rather than opening port 3306 publicly.
### 2. Provision a business
Run this after MySQL is healthy. The script creates the database and least
scope database user, generates secrets, writes a Dockge-ready stack directory,
and writes one Caddy site file:
```bash
NEXTCHAIR_STACK_ROOT=/opt/nextchair/stacks \
NEXTCHAIR_CADDY_SITES_DIR=/opt/nextchair/stacks/caddy/sites \
./scripts/create-business.sh blake-heritage blakeheritage.com nextchair:latest
```
For production, pass the exact image tag to use. The script never overwrites
an existing business slug. In Dockge, the new directory appears as its own
stack, so `start`, `stop`, `restart`, `recreate`, `update`, and logs are scoped
to that business. The generated `.env` is mode `600` and is ignored by git.
After DNS points at the server, start the generated stack from Dockge. Caddy
will obtain the certificate and route the domain to the app container over the
private `nextchair-proxy` network. Reload Caddy after adding or removing a
route:
```bash
docker compose -f stacks/caddy/compose.yaml exec nextchair-caddy caddy reload --config /etc/caddy/Caddyfile
```
Repeat the provisioning command for each business. A business's database,
media volume, env file, app container, and Caddy route are all named from its
slug. The application migration entrypoint runs on every start, while the
first-run business setup remains the app-level `/install` flow.
## Repository Layout
```text
src/app/ Next.js routes, layouts, and API handlers
src/features/ Feature workflows, server actions, schemas, components
src/services/ Domain services and external-provider integrations
src/lib/ Shared infrastructure, auth, database, security, and utilities
prisma/ Schema, migrations, and development seed
e2e/ Playwright browser journeys and test setup
docker/ Container entrypoint
docs/ Phase implementation notes and historical decisions
deploy/ Reusable business stack template
stacks/ Dockge stacks: infra, caddy, and businesses
scripts/ Database/business provisioning utilities
templates/ UI reference templates
```
The phase documents in `docs/` contain implementation history and deeper design rationale. They are useful when changing installation, scheduling, notification, calendar, media, or deployment behavior, but this README is the intended starting point for running the project.
## Common Troubleshooting
**The app redirects to `/install`.** This is expected for a fresh or unseeded database. Set `INSTALLATION_TOKEN` and complete the wizard, or explicitly run the development seed.
**The app cannot connect to MySQL in the local stack.** Use `DATABASE_HOST=next-chair-mysql`, not `localhost`, and ensure the local credentials match the local MySQL container.
**The app cannot connect to MySQL in a business stack.** Use `DATABASE_HOST=nextchair-mysql`, confirm `nextchair-mysql` is attached to `nextchair-db`, and confirm the generated `DATABASE_NAME`, `DATABASE_USER`, and `DATABASE_PASSWORD` match the database created by `scripts/create-business.sh`.
**The app cannot connect to MySQL when run with `npm run dev`.** Use `DATABASE_HOST=localhost` or the hostname of your external MySQL server, and verify that the database and user already exist.
**Port 3000 is already in use.** Set `APP_HOST_PORT` in `.env.local` for Docker, or start Next.js with `npm run dev -- --port 3001` for host development. Update `NEXT_PUBLIC_APP_URL` when callback URLs need to match the new port.
**Emails or push notifications are not delivered.** The default providers are console-only. Configure the relevant provider and credentials before expecting external delivery.
**A reset is needed during local development.** Use a separate database or `docker compose ... down -v` for the local Docker stack. This removes local database and media data and should never be used against production volumes.
## License
The package currently declares the ISC license in `package.json`. Confirm the intended distribution license before publishing the application or its assets.