Startup

README.md

@@ -0,0 +1,78 @@
+# EscapePage — Online Escape Room
+
+This repository contains a Symfony 7.3 (PHP >= 8.2) application for a collaborative online escape room experience.
+
+- Start here: doc/FILES.md — quick file index.
+- Development standards and workflows: doc/CONTRIBUTING.md
+- All documentation is located under the doc/ directory.
+
+## Getting Started (brief)
+- Local machine (no Docker):
+  1. Copy `.env` to `.env.local` and set database and `APP_SECRET`.
+  2. Install PHP deps: `composer install`
+  3. Create database and run migrations (when present): `php bin/console doctrine:database:create --if-not-exists && php bin/console doctrine:migrations:migrate -n`
+  4. Install/import JS deps: `php bin/console importmap:install`
+  5. Run the server: `symfony server:start -d` (or your preferred web server)
+  6. Run tests: `vendor/bin/phpunit`
+
+- With Docker:
+  1. From `docker/`: `docker compose up -d`
+  2. Install vendors inside the PHP container:
+     - `docker compose exec php bash`
+     - `composer install`
+  3. Initialize DB:
+     - `php bin/console doctrine:database:create --if-not-exists`
+     - `php bin/console doctrine:migrations:migrate -n`
+  4. App is at http://localhost:8080
+
+## Email (Mailpit in dev, SendGrid for prod)
+- Dev: a `mailer` service (Mailpit) runs in Docker.
+  - SMTP DSN in `.env`: `MAILER_DSN=smtp://mailer:1025`
+  - Mailpit UI: http://localhost:8025
+  - Send a test mail: `php bin/console app:mail:test you@example.com`
+- Staging/Prod: use SendGrid.
+  - Require package (already in composer): `symfony/sendgrid-mailer`.
+  - Set environment variables (do NOT commit secrets):
+    - `MAILER_DSN=sendgrid+api://%env(SENDGRID_API_KEY)%`
+    - `SENDGRID_API_KEY=YOUR_REAL_KEY`
+    - Optional: `MAILER_FROM=no-reply@your-domain.tld`
+  - Alternatively via SMTP (no extra package):
+    - `MAILER_DSN="smtp://apikey:%env(SENDGRID_API_KEY)%@smtp.sendgrid.net:587?encryption=tls"`
+
+Troubleshooting:
+- If emails don’t appear in dev, open Mailpit at http://localhost:8025 and verify messages.
+- In prod, check logs for HTTP 2xx responses from SendGrid and verify sender domain is verified in SendGrid.
+
+## Frontend assets with Webpack Encore
+We use Webpack Encore to build and minify JS/CSS from the `assets/` directory into `public/build/`.
+
+Install Node dependencies (on your host machine):
+```
+npm install
+```
+
+Common commands:
+```
+# One-time dev build
+npm run dev
+
+# Watch & rebuild on changes
+npm run watch
+
+# Production build (minified, versioned filenames)
+npm run build
+```
+
+How it’s wired:
+- Entry file: `assets/app.js` (imports `assets/styles/app.css`).
+- Webpack config: `webpack.config.js` outputs to `public/build/`.
+- Twig template includes built assets via Encore:
+  - In `templates/base.html.twig`:
+    - `{{ encore_entry_link_tags('app') }}` (CSS)
+    - `{{ encore_entry_script_tags('app') }}` (JS)
+
+Notes:
+- The PHP Docker image does not include Node. Run the build commands on your host, or ask to add a Node build container if you prefer fully containerized builds.
+- Built files are ignored by git except for `public/build/.gitignore` to keep the directory.
+
+See doc/CONTRIBUTING.md for code style and more details.