Deployment Guide

Deployment Guide

Current environment findings

• PHP-FPM 8.3 is available on the VM
• MariaDB is available
• nginx is available
• Composer was installed locally for this project bootstrap
• Redis is not yet installed

Recommended production topology

• endpoint nginx on the endpoint VM handles TLS and forwards domain traffic
• web VM nginx serves the Laravel site from public/
• PHP-FPM executes the Laravel app
• MariaDB stores primary application data
• Redis should be added later for cache and queue performance

Web VM steps

1. Create database and application user in MariaDB

   CREATE DATABASE freedomclassifieds CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'freedomclassifieds'@'127.0.0.1' IDENTIFIED BY 'replace-with-strong-password';
   GRANT ALL PRIVILEGES ON freedomclassifieds.* TO 'freedomclassifieds'@'127.0.0.1';
   FLUSH PRIVILEGES;
   

2. Copy .env.example to .env and set production values for:

   • APP_NAME
   • APP_ENV=production
   • APP_DEBUG=false
   • APP_URL=https://freedomclassifieds.com
   • DB_CONNECTION=mysql
   • DB_HOST=127.0.0.1
   • DB_PORT=3306
   • DB_DATABASE=freedomclassifieds
   • DB_USERNAME=freedomclassifieds
   • DB_PASSWORD
   • MAIL_*, POSTMARK_API_KEY, POSTMARK_MESSAGE_STREAM_ID
   • GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI
   • CAPTCHA_PROVIDER and whichever provider secrets are selected

3. Install dependencies and optimize autoloading

   composer install --no-dev --optimize-autoloader
   

4. Generate the application key if needed

   php artisan key:generate
   

5. Run the database bootstrap

   php artisan migrate --force
   php artisan db:seed --force
   

6. Ensure storage/ and bootstrap/cache are writable by the web user

7. Configure nginx site root to public/

8. Point PHP requests to PHP-FPM 8.3

9. Restart nginx and PHP-FPM

Local activation notes

• The Laravel default SQLite path will not work on this VM because the SQLite PDO driver is not available in the current PHP build.
• Local activation was validated successfully by switching the app to MariaDB, creating the freedomclassifieds database and user, and running php artisan migrate:fresh --seed.
• Seed verification after bootstrap produced:
  • 12 categories
  • 5 locations
  • 3 users
  • 6 listings
  • 8 ad slots

Validation checklist

• php artisan route:list
• php artisan migrate:status
• php artisan config:clear
• php artisan view:clear
• Verify homepage, listings index, listing detail, seller profile, dashboard, admin, docs, robots.txt, and sitemap.xml
• Verify public listing submission, listing contact, and abuse report forms with the configured captcha provider
• Confirm PHP-FPM can write to storage/framework, storage/logs, and bootstrap/cache

Endpoint notes

Use the endpoint staging pattern already used on this machine: create config files under /home/ubuntu/endpoint-fix-confs and then apply them on the endpoint host.