Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• tests/Feature/Docs/DeploymentDocsTest.php
• README.md
• AGENTS.md
• tests/Feature/Docs/SeedDataDocsTest.php
• database/seeders/DemoFillSeeder.php
• tests/Feature/Docs/PullRequestTemplateTest.php

This guide outlines the procedures for deploying the RateGuru application to various environments. RateGuru is a Laravel-based application utilizing Livewire, Alpine.js, and Filament, with a "SQLite first" architecture.

The deployment process covers environment configuration, database management, asset compilation, and essential post-deployment tasks to ensure system stability and security.

Sources: AGENTS.md:4-11, README.md:3-11

Production Environment Checklist

Before deploying to a production environment, specific configuration flags and security measures must be verified. The application must operate in a hardened state with debugging disabled and secure key management.

• Environment Settings: Ensure APP_ENV is set to production.
• Security: APP_DEBUG must be set to false to prevent sensitive data leakage in error messages. A valid APP_KEY must be generated and stored securely.
• Database Safety: Never run migrate:fresh in a production environment as it destroys existing data. Use standard migrations with the --force flag.
• Backups: A backup strategy is mandatory before executing migrations.

Sources: tests/Feature/Docs/DeploymentDocsTest.php:3-23

Deployment Workflow

The following diagram illustrates the high-level flow of a standard deployment to the RateGuru production server.

The diagram shows the sequential steps required to safely transition the application to a new version.

Sources: tests/Feature/Docs/DeploymentDocsTest.php:4-70, README.md:38-51

Database & Migrations

RateGuru uses SQLite as its primary database. Deployment requires careful handling of migration commands to maintain data integrity.

SQLite Strategy

In production, the database is located at database/database.sqlite. It is recommended to create a backup in a backups/ directory before running any migrations. While SQLite is the current standard, the project acknowledges future transitions to PostgreSQL, though this was not implemented as of Phase 42.

Sources: tests/Feature/Docs/DeploymentDocsTest.php:73-95, README.md:23-26

Migration Commands

Command	Purpose	Production Usage
php artisan migrate --force	Runs outstanding migrations	Required
php artisan migrate:status	Checks migration state	Recommended
php artisan migrate:fresh	Wipes and recreates DB	Forbidden

Sources: tests/Feature/Docs/DeploymentDocsTest.php:12-23, tests/Feature/Docs/DeploymentDocsTest.php:57-64

Storage and Permissions

Proper filesystem configuration is critical for handling user uploads and application caching.

• Storage Symlink: The command php artisan storage:link must be executed to map storage/app/public to public/storage.
• Directory Permissions: The web server requires write access to:
  • storage/framework/views
  • storage/framework/sessions
  • storage/framework/cache/data
• Security Note: Do not use chmod 777 blindly; apply restrictive but functional permissions.

Sources: tests/Feature/Docs/DeploymentDocsTest.php:32-43

Background Workers and Queues

RateGuru utilizes background jobs for non-blocking tasks.

• Connection: The QUEUE_CONNECTION environment variable determines the driver. Redis is explicitly noted as not required for standard operations.
• Execution: Queue workers are started using php artisan queue:work.
• Deployment Update: To ensure workers use the newly deployed code, php artisan queue:restart must be called during the deployment script.

Sources: tests/Feature/Docs/DeploymentDocsTest.php:48-54, AGENTS.md:52

Administrative Setup

After the initial deployment or a database reset, administrative access must be established.

Admin User Creation

Administrative accounts should be created via the CLI rather than using default seeders in production.

php artisan rateguru:admin:create --email="admin@example.com" --username="admin"

Warning: Do not use demo admin credentials (e.g., admin@rateguru.test) in production environments.

Sources: tests/Feature/Docs/DeploymentDocsTest.php:66-71, tests/Feature/Docs/SeedDataDocsTest.php:8-13

Summary

Deployment of RateGuru focuses on maintaining the SQLite database integrity through forced migrations and pre-migration backups. The process emphasizes security by disabling debug modes and using dedicated CLI commands for admin creation. Successful deployment concludes with asset building, storage linking, and restarting queue workers to ensure all system components are synchronized with the latest codebase.