132 lines
3.5 KiB
Markdown
132 lines
3.5 KiB
Markdown
# PreRegister
|
||
|
||
Laravel 11 app for festival **ticket pre-registration**: branded public landing pages, local subscriber storage, and optional sync to [Mailwizz](https://www.mailwizz.nl/) (API key per page, encrypted at rest).
|
||
|
||
## Tech stack
|
||
|
||
| Layer | Choice |
|
||
|--------|--------|
|
||
| Backend | PHP 8.2+, Laravel 11, MySQL 8 |
|
||
| Frontend (public + admin) | Blade, Tailwind CSS 3, Alpine.js 3 |
|
||
| Auth | Laravel Breeze (Blade stack) |
|
||
| Queue | Database driver; Mailwizz sync on `mailwizz` queue |
|
||
|
||
**Not used:** React, Vue, Livewire, or Inertia.
|
||
|
||
## Requirements
|
||
|
||
- PHP ≥ 8.2 (extensions: mbstring, xml, curl, pdo_mysql, gd)
|
||
- Composer ≥ 2.7
|
||
- Node.js ≥ 20 (for Vite / Tailwind)
|
||
- MySQL 8 (local or Docker)
|
||
|
||
## Local setup
|
||
|
||
1. **Clone and install PHP dependencies**
|
||
|
||
```bash
|
||
composer install
|
||
```
|
||
|
||
2. **Environment**
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
php artisan key:generate
|
||
```
|
||
|
||
Configure database (example for Docker MySQL on localhost):
|
||
|
||
```env
|
||
DB_CONNECTION=mysql
|
||
DB_HOST=127.0.0.1
|
||
DB_PORT=3306
|
||
DB_DATABASE=preregister
|
||
DB_USERNAME=preregister
|
||
DB_PASSWORD=preregister
|
||
|
||
QUEUE_CONNECTION=database
|
||
```
|
||
|
||
Mailwizz API keys are **not** in `.env`; they are stored per pre-registration page in the database (encrypted).
|
||
|
||
3. **Docker (optional)**
|
||
|
||
From the project root:
|
||
|
||
```bash
|
||
make up
|
||
# or: docker compose up -d
|
||
```
|
||
|
||
See [documentation/Setup.md](documentation/Setup.md) for MySQL, Mailpit, and phpMyAdmin ports.
|
||
|
||
4. **Database**
|
||
|
||
```bash
|
||
php artisan migrate --seed
|
||
```
|
||
|
||
5. **Storage link (uploads)**
|
||
|
||
```bash
|
||
php artisan storage:link
|
||
```
|
||
|
||
6. **Frontend build**
|
||
|
||
```bash
|
||
npm install
|
||
npm run build
|
||
# or during development: npm run dev
|
||
```
|
||
|
||
7. **Run the app**
|
||
|
||
```bash
|
||
php artisan serve
|
||
```
|
||
|
||
Admin UI lives under `/admin` (after login). Public pre-registration URLs are `/r/{uuid-slug}`.
|
||
|
||
8. **Queue worker (Mailwizz sync)**
|
||
|
||
```bash
|
||
php artisan queue:work --queue=mailwizz
|
||
```
|
||
|
||
Use Supervisor or your host’s process manager in production.
|
||
|
||
## Default login (after seed)
|
||
|
||
`php artisan db:seed` creates a **superadmin** (via `SuperadminSeeder`):
|
||
|
||
- Email: `admin@preregister.app`
|
||
- Password: `changeme123!`
|
||
|
||
Change this password immediately in any shared or production environment. Additional users are created by a superadmin in **Admin → Users**. Sign in at `/login`.
|
||
|
||
## Deployment notes
|
||
|
||
- Run `php artisan migrate` (and `--seed` only on first deploy if you rely on seed data).
|
||
- Run `php artisan storage:link` so `public/storage` serves uploaded backgrounds and logos.
|
||
- Run a queue worker on the `mailwizz` queue (or `queue:work` without `--queue` if you only use the default queue and push jobs there consistently).
|
||
- Set `APP_KEY`, use HTTPS behind a reverse proxy, and configure `APP_URL` correctly.
|
||
- Optional: cron for `* * * * * php /path/to/artisan schedule:run` if you add scheduled tasks.
|
||
|
||
More detail: [documentation/DEPLOYMENT-STRATEGY.md](documentation/DEPLOYMENT-STRATEGY.md).
|
||
|
||
## Product specification
|
||
|
||
Full functional spec and development sequence: [documentation/Pregister-Development-Prompt.md](documentation/Pregister-Development-Prompt.md).
|
||
|
||
## Security
|
||
|
||
- Public subscribe endpoint is rate limited (`throttle:10,1`).
|
||
- CSRF on web forms; policies for admin resources.
|
||
- Never expose Mailwizz API keys in responses, logs, or the browser.
|
||
|
||
## License
|
||
|
||
Application code follows your project’s license. Laravel is open source under the [MIT license](https://opensource.org/licenses/MIT).
|