Frequently Asked Questions

Problem: reCAPTCHA not working or showing "Invalid domain" errors.

Solutions:

1. For Local Development:
   Add localhost to your reCAPTCHA domains in Google reCAPTCHA Console.
   Domain: localhost Alternative: 127.0.0.1
2. For Production:
   Add your server's IP address or domain name:
   Domain: yourdomain.com IP: 192.168.1.100 Universal (not recommended): 0.0.0.0/0
3. Update .env file:
   Make sure your reCAPTCHA keys are correctly set:
   RECAPTCHA_SITE_KEY=your_site_key_here RECAPTCHA_SECRET_KEY=your_secret_key_here

Problem: Application URLs not working correctly, email links broken, or redirects failing.

Configuration Steps:

1. Update .env APP_URL:
   # For local development APP_URL=http://localhost/your-project-folder # For production APP_URL=https://yourdomain.com
2. Configure email URLs:
   Email verification and password reset links use APP_URL as base.
3. Check virtual host configuration:
   Ensure your web server is configured to serve the application correctly.

Problem: Third-party resources blocked, CSP violations, or external API calls failing.

Understanding Security Rules:

The .htaccess file contains strict Content Security Policy (CSP) rules that only allow:

• reCAPTCHA: Google's reCAPTCHA services
• Bootstrap: CDN resources for styling
• jQuery: JavaScript library

Adding New Third-Party Services:

1. Identify the domain:
   Find the exact domain of the service you want to add.
2. Update CSP header in .htaccess:
   Add the domain to the appropriate CSP directive:
   # Example: Adding Font Awesome script-src 'self' ... https://cdnjs.cloudflare.com; style-src 'self' ... https://cdnjs.cloudflare.com;
3. Test the changes:
   Clear browser cache and test the functionality.

Problem: No error logs, debugging information not available, or issues are hard to diagnose.

Enable Logging:

1. Update .env file:
   APP_DEBUG=true LOGGING_ENABLED=true LOG_LEVEL=debug
2. Check log files:
   Logs are typically stored in:
   /logs/app.log /logs/email.log /logs/recaptcha.log
3. Email debugging:
   Increase mail debug level:
   MAIL_DEBUG_LEVEL=2 # 0=off, 1=client, 2=server

Problem: Emails not sending, verification emails not received, or SMTP errors.

Email Setup:

1. Gmail Configuration:
   MAIL_HOST=smtp.gmail.com MAIL_PORT=587 MAIL_USERNAME=your-email@gmail.com MAIL_PASSWORD="your-app-password" MAIL_ENCRYPTION=tls
2. Generate App Password:
   For Gmail, use App Passwords instead of your regular password.
3. Test email sending:
   Use the contact form or registration to test email functionality.
4. Check spam folder:
   Verification emails might be marked as spam.

Problem: Database connection errors, authentication failures, or collection access issues.

Database Setup:

1. MongoDB Atlas Setup:
   Ensure your MongoDB Atlas cluster is properly configured:
   MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/database MONGODB_DATABASE=auth
2. IP Whitelist:
   Add your server's IP to MongoDB Atlas Network Access.
3. User Permissions:
   Ensure the database user has read/write permissions.
4. Test Connection:
   Run the database diagnostics script to test connectivity.

Problem: Permission denied errors, unable to write logs, or file access issues.

Required Permissions:

1. Logs Directory:
   Ensure the logs directory is writable:
   chmod 755 /logs/ chmod 644 /logs/*.log
2. Config Files:
   Protect sensitive configuration files:
   chmod 600 .env chmod 644 config/*.php
3. Web Server User:
   Ensure the web server has access to required files.

Issue: Slow loading times, high server load, or timeout errors.

Optimization Tips:

1. Enable PHP OPcache:
   Configure OPcache in your PHP settings for better performance.
2. Database Indexing:
   Ensure proper indexes on frequently queried fields (email, username).
3. Rate Limiting:
   The system includes rate limiting to prevent abuse.
4. CDN Usage:
   Use CDNs for static assets like Bootstrap and jQuery.

Problem: Installation errors, missing dependencies, or setup failures.

Prerequisites Checklist:

• ✅ PHP 7.4 or higher
• ✅ Composer installed
• ✅ MongoDB PHP extension
• ✅ OpenSSL extension
• ✅ cURL extension
• ✅ JSON extension

Installation Commands:

If you're still experiencing issues after following this FAQ:

1. Check the logs:
   Enable debugging and check log files for specific error messages.
2. Browser Console:
   Check browser developer tools for JavaScript errors.
3. Server Logs:
   Check Apache/Nginx error logs for server-side issues.
4. Community Support:
   Create an issue on the project's GitHub repository with:
   • Detailed description of the problem
   • Error messages (with sensitive data removed)
   • Steps to reproduce the issue
   • Your environment details