POL MARKETPLACE - SETUP INSTRUCTIONS ===================================== This is a step-by-step runbook for getting the app running from a fresh clone. For architecture, RBAC design, and the import pipeline's internals, see README.md instead - this file is just "how do I stand this up." 1. PREREQUISITES ----------------- - PHP 8.2+ - Composer - Node.js + npm - MySQL 8 - Redis (used for queues and cache) - Apache or nginx, if serving publicly rather than via `php artisan serve` 2. CLONE AND INSTALL DEPENDENCIES ---------------------------------- git clone git@github.com:Prints-of-Love/pol-marketplace.git cd pol-marketplace composer install npm install 3. CREATE THE DATABASES ------------------------ Two databases are needed - one for the app, one for the test suite (tests run against a real MySQL database, not SQLite): CREATE DATABASE pol_marketplace; CREATE DATABASE pol_marketplace_test; CREATE USER 'pol_marketplace'@'localhost' IDENTIFIED BY 'your-password'; GRANT ALL PRIVILEGES ON pol_marketplace.* TO 'pol_marketplace'@'localhost'; GRANT ALL PRIVILEGES ON pol_marketplace_test.* TO 'pol_marketplace'@'localhost'; 4. CONFIGURE .env ------------------ cp .env.example .env php artisan key:generate Then edit .env and set: Database DB_DATABASE, DB_USERNAME, DB_PASSWORD - match what you created in step 3. Redis REDIS_HOST / REDIS_PORT - only if not running on localhost:6379 defaults. Super-admin account (seeded automatically in step 6) ADMIN_EMAIL, ADMIN_PASSWORD Mail (SMTP) MAIL_MAILER=smtp MAIL_HOST=send.smtp.com MAIL_PORT=587 MAIL_USERNAME= MAIL_PASSWORD= MAIL_FROM_ADDRESS= (Laravel negotiates STARTTLS automatically on port 587 - no MAIL_ENCRYPTION setting is needed/read in this Laravel version.) S3 (Phase 2 - mirrored fonts/images/design JSON from source imports) AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY AWS_BUCKET (defaults to mag-pdev) AWS_DEFAULT_REGION (defaults to us-east-1) NOTE: the IAM user these keys belong to needs s3:DeleteObject in addition to the usual PutObject/GetObject - without it, rerun-full and admin cleanup actions will silently fail to remove old S3 files (they still succeed on the DB side; only the S3 objects are left behind). 'throw' is set to false on the s3 disk config, so failures don't throw - check logs / re-run with a temporary 'throw' => true disk instance if an S3 write/delete seems to have silently no-op'd. Auth sidecar + Templett (Phase 2 - source import pipeline) AUTH_SIDECAR_URL (http://127.0.0.1:4000 locally, or http://auth-sidecar:4000 under docker-compose) TEMPLETT_BASE_URL (defaults to https://templett.com) IMPORT_SYNC_INTERVAL_HOURS (defaults to 24) Polotno editor VITE_POLOTNO_KEY - get one from https://polotno.com/cabinet. Without one the editor still works fully but runs in free/dev mode (shows a "Made with Polotno" credit badge) - fine for local dev, not for production. AI metadata auto-fill ANTHROPIC_API_KEY - get one from https://console.anthropic.com. Powers the "Auto-fill with AI" button on the Update Metadata page (sends the template's thumbnail + text content to Claude and suggests values for empty fields; never overwrites a field that already has a value). Without a key, that button returns an error - everything else works fine. 5. BUILD FRONTEND ASSETS ------------------------- npm run build (production build) npm run dev (or, for local dev with hot reload) 6. RUN MIGRATIONS AND SEED THE DATABASE ---------------------------------------- php artisan migrate --seed This seeds, in order: baseline permissions, the Admin/Designer/Approver roles, the super-admin account (from ADMIN_EMAIL/ADMIN_PASSWORD), the 15 template-metadata attribute definitions (Size, Orientation, Color, etc.), and their ~958 real dropdown option values (imported from the live Magento admin so values match exactly - see database/seeders/AttributeOptionSeeder.php). Every seeder here is idempotent (uses updateOrCreate / sync*) - running `php artisan db:seed` again at any point (e.g. after pulling new code that adds a permission or attribute) is always safe and never duplicates data. 7. START THE APP ----------------- php artisan serve ...or point an Apache/nginx vhost's document root at the `public/` directory, with mod_rewrite (Apache) enabled so Laravel's front controller handles all routes. Log in with ADMIN_EMAIL / ADMIN_PASSWORD to reach the admin UI (Users, Roles, Permissions, Attributes, Audit Log, etc.), or visit /register to sign up as a new designer - new accounts land on a pending-approval screen until an admin approves them. 8. PHASE 2: RUNNING THE IMPORT PIPELINE ----------------------------------------- Three more long-running processes are needed for source-connection imports (connecting a Templett account, crawling/importing templates) to actually work. None of these are optional if you want that feature to function - without them, a connection will just sit at "Never" imported / a dispatched job will sit in Redis untouched. a) The auth sidecar (Playwright browser automation, needed to get past Templett's reCAPTCHA on login): cd auth-sidecar npm install (also downloads a bundled Chromium) npm start (or: node server.js) For a persistent setup (survives reboots/crashes), run this via systemd or pm2 rather than a bare `npm start` / nohup. b) Horizon - the queue worker that actually processes dispatched import jobs (runs on the "imports" queue): php artisan horizon Same persistence note as above - use systemd/pm2/supervisor in production. c) The scheduler, so DispatchDueImports actually fires every 15 minutes to pick up connections marked sync_due: - Production: add ONE system cron line - * * * * * cd /path/to/app && php artisan schedule:run >> /dev/null 2>&1 - Local dev: `php artisan schedule:work` polls every minute for you, no crontab needed. Or, run everything at once (app, mysql, redis, horizon, a scheduler loop, and the sidecar) via: docker-compose up 9. MANAGING TEMPLATE METADATA DROPDOWNS ----------------------------------------- Admin > Attributes lets you manage the dropdown fields shown when editing a template (Size, Color, Occasion, Search & Filter Tags, etc.) - add/edit/ disable individual options, bulk-delete, or bulk-import via CSV (columns: value, label, sort_order, is_active). New dropdown *types* can also be created entirely from this UI (no code/deploy needed) - click "New Attribute" on the Attributes index page. This whole area is gated behind the `attribute.manage` permission. 10. RUNNING TESTS ------------------- php artisan test Uses the pol_marketplace_test database created in step 3 (configured via .env.testing - adjust DB credentials there to match your local MySQL user). tests/Pest.php wraps every test in RefreshDatabase, so each test starts from a clean, migrated-but-unseeded database. TROUBLESHOOTING NOTES FROM PAST SETUP ISSUES ============================================== - "cURL error 7: Failed to connect to 127.0.0.1 port 4000" when connecting/starting an import -> the auth-sidecar isn't running. See step 8a. - A Start/Rerun click on the Connections page shows no progress -> Horizon isn't running, so the dispatched job is just sitting in Redis. See step 8b. - S3 deletes appear to succeed but files remain in the bucket -> check the IAM permission note under S3 in step 4 (missing s3:DeleteObject). - Polotno editor toolbar renders unstyled/broken -> make sure @blueprintjs/core, @blueprintjs/icons, @blueprintjs/select and Polotno's own CSS are all imported in resources/js/Components/PolotnoEditor.tsx (note: the npm package's exports map aliases the real file blueprint.polotno.css to the swapped-order specifier polotno/polotno.blueprint.css - import it under that name).