Common Setup
Server, background jobs and shared services for a production install.
Where Settings Live
| Kind of setting | Where |
|---|---|
| App URL, environment, debug, database, queue, cache, session, log channel, demo mode, mobile version gate | .env (run php artisan config:clear after editing on a cached config) |
| Mail (SMTP), storage (S3), push (FCM), reCAPTCHA keys, SEO, social links, maintenance mode, custom CSS/JS | SaaS admin → Settings, stored in the database (secrets encrypted with APP_KEY) |
| AI providers and models, payment gateways, social publishing apps, Twilio/Plivo | SaaS admin, stored encrypted in the database |
| Plans, credit packages, extensions, languages, landing page | SaaS admin |
| Live chat websocket (Reverb) | SaaS admin → Settings → Realtime Settings, stored in the database (app secret encrypted); the browser reads the values from the page, so no asset rebuild is needed. The server process php artisan reverb:start runs under Supervisor |
Nginx & Apache
The document root must be the public/ folder. Nginx example (from docs/installation.md):
server {
listen 443 ssl http2;
server_name app.example.com;
root /var/www/omnigenix/public;
index index.php;
client_max_body_size 64M;
location / { try_files $uri $uri/ /index.php?$query_string; }
# uploaded files: never execute or render scripts/HTML (Apache uses public/uploads/.htaccess)
location ^~ /uploads/ {
add_header X-Content-Type-Options nosniff always;
location ~* \.(php\d*|phtml|phar|html?|xhtml|shtml|js|mjs|cgi|pl|py|sh)$ { deny all; }
location ~* \.(svgz?|xml)$ { add_header Content-Security-Policy "sandbox" always; add_header X-Content-Type-Options nosniff always; }
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_read_timeout 300; # streaming chat and long AI calls
}
location ~ /\.(?!well-known) { deny all; }
}The /uploads/ block must come before the generic \.php$ location. On Apache the shipped public/uploads/.htaccess does the same (no PHP, HTML or script files served from uploads, nosniff); LiteSpeed reads it too. Uploaded logos and files are checked by their content: SVG, HTML and script files are rejected.
Keep /.well-known/ reachable: the platform serves /.well-known/assetlinks.json and /.well-known/apple-app-site-association for app links. On Apache the shipped public/.htaccess handles rewrites; enable mod_rewrite and AllowOverride All. If your host cannot change the document root, use a subdomain whose root you can set; never expose the project root.
HTTPS & Proxies
HTTPS is required in production: payment webhooks, Sanctum mobile tokens, push and Twilio/Plivo callbacks all expect a public HTTPS URL, and Android release builds of the app refuse cleartext HTTP. Use a certificate from your host or Let’s Encrypt, set APP_URL=https://… (no trailing slash) and SESSION_SECURE_COOKIE=true.
Behind a load balancer, CDN or reverse proxy, list its IPs or CIDR ranges in TRUSTED_PROXIES so the forwarded scheme and host stay correct. Avoid * unless your network edge strips untrusted forwarded headers. Voice-call callbacks are signed against the exact host in APP_URL.
CDN / Cloudflare Bypass Paths
If the site runs behind Cloudflare or another CDN/WAF, these paths must not be cached, challenged (captcha / bot check / “under attack” mode) or have their body rewritten (minify, Rocket Loader, email obfuscation). Payment gateways, Twilio/Plivo and the phone app cannot solve a browser challenge, and a changed body breaks webhook signatures. Use one rule per path, written as a plain path prefix (in Cloudflare: URI Path starts with):
⚠ Using Cloudflare? These features rewrite or challenge requests and must be off for the paths below. They are on by default on many Cloudflare plans, and non-technical owners rarely know they are active:
- Email Address Obfuscation (Scrape Shield): rewrites e-mail addresses in HTML into a script-decoded link, which changes the response body and leaves visible
[email protected]text in admin screens and invoices. - Rocket Loader (Speed → Optimization): rewrites
<script>tags; it breaks the admin and workspace JavaScript, the installer and the embedded website chatbot. - Auto Minify and Mirage (retired by Cloudflare, but still active on some older zones), and any other HTML or JavaScript “optimization” that changes the page body.
- Bot Fight Mode / Super Bot Fight Mode, Browser Integrity Check, I’m Under Attack mode and managed challenges: payment gateways, Twilio/Plivo and the phone app cannot solve them, so webhooks and callbacks fail with 403/503.
How: create a Configuration Rule (Rules → Configuration Rules) for each path prefix with Email Obfuscation: Off, Rocket Loader: Off and Browser Integrity Check: Off; a Cache Rule with Bypass cache; and a WAF custom rule with action Skip (all remaining custom rules, rate limiting and managed rules, plus Super Bot Fight Mode where your plan allows it). If you prefer one switch, turn Email Obfuscation and Rocket Loader off for the whole domain: OmniGenix AI does not need them. Other CDNs have equivalents (for example “JavaScript optimisation”, “HTML minification”, “bot protection”); switch those off for the same paths.
| Path (prefix) | Used by | Rule |
|---|---|---|
/webhooks/stripe | Stripe webhooks | Bypass cache, no challenge, no body changes |
/webhooks/paypal | PayPal webhooks | Bypass cache, no challenge, no body changes |
/webhooks/razorpay | Razorpay webhooks | Bypass cache, no challenge, no body changes |
/webhooks/mollie | Mollie webhooks | Bypass cache, no challenge |
/payments/ | Gateway return pages (PayPal capture, Razorpay verify) | Bypass cache |
/hooks/calls/ | Twilio / Plivo call callbacks (signed against the exact URL) | Bypass cache, no challenge, no body or URL changes |
/api/v1/ | Phone app (bearer tokens), mobile social OAuth callback | Bypass cache, no challenge |
/widget/ | Website chatbot embedded on customers’ sites | Bypass cache, no challenge |
/live-chat | Landing-page live chat | Bypass cache |
/broadcasting/auth | Reverb channel authorisation (only if Reverb is on) | Bypass cache; enable WebSockets in the CDN |
/company/social/accounts/callback/ | Social network OAuth returns | Bypass cache |
/.well-known/assetlinks.json, /.well-known/apple-app-site-association, /apple-app-site-association | Android / iOS app links verification | Bypass cache, no challenge, no redirect |
/install | Web installer (first run only) | Bypass cache |
Also set TRUSTED_PROXIES to the CDN’s IP ranges (see HTTPS & Proxies) so rate limits and callback signatures see the real visitor IP and scheme. Static files in /assets-compiled/ and /uploads/ can be cached normally.
Permissions & Storage Link
cd /var/www/omnigenix chown -R www-data:www-data storage bootstrap/cache public/uploads chmod -R 775 storage bootstrap/cache public/uploads php artisan storage:link
storage:link creates public/storage → storage/app/public for logos and avatars. The installer and php artisan omnigenix:update both run it. Private files (generated media, uploads, exports) stay outside public/ and are served through short-lived signed links.
Cron & Scheduler
One entry for the web-server user, every minute. Use the full PHP path if php is not on cron’s PATH (which php).
* * * * * cd /var/www/omnigenix && php artisan schedule:run >> /dev/null 2>&1
It ends trials and billing periods, starts the next period of free plans, expires unused plan credits, sends renewal and dunning reminders, publishes scheduled social posts, places voice-campaign calls, runs AI health checks, enforces data retention, verifies custom domains and marks stuck generations as failed. The full task list is on Web Platform → Cron; check it with php artisan schedule:list. Settings → System Status warns when cron has not run in the last few minutes.
Queue Worker
Use QUEUE_CONNECTION=database (or redis). Video, avatar, document indexing, push, data exports and social publishing run on the queue. Supervisor config (/etc/supervisor/conf.d/omnigenix-worker.conf):
[program:omnigenix-worker] command=php /var/www/omnigenix/artisan queue:work --sleep=3 --tries=3 --timeout=960 --max-time=3600 autostart=true autorestart=true user=www-data numprocs=2 redirect_stderr=true stdout_logfile=/var/www/omnigenix/storage/logs/worker.log stopwaitsecs=3600
sudo supervisorctl reread && sudo supervisorctl update && sudo supervisorctl start omnigenix-worker:*
Shared hosting: set QUEUE_VIA_SCHEDULER=true. The cron entry then runs queue:work --stop-when-empty every minute; jobs start a little later but still run. After every code update run php artisan queue:restart (omnigenix:update does this). Keep the provider’s Video poll timeout (default 600 s) below the worker --timeout.
Reverb (Live Chat, optional)
The public landing page has a small live-chat box. Visitor messages are always saved on the server (as support tickets), even when no websocket server runs. Real-time delivery uses Laravel Reverb (laravel/reverb is a Composer dependency and config/reverb.php is included). To turn it on:
Turn it on in the admin panel
Open SaaS admin → Settings → Realtime Settings (
/admin/settings/realtime) and tick Enable realtime (Laravel Reverb). Leave App ID, App key and App secret blank and they are generated when you save (the secret is stored encrypted).Public address
Public host, Public port and Scheme are what visitors’ browsers connect to: normally your own domain (blank host = the host of
APP_URL), port443andhttps / wssbehind Nginx. Reverb server port (internal) is the local portreverb:startlistens on (default8080). The landing page passes these values to the browser, so the prebuilt assets need no rebuild and there are noVITE_REVERB_*keys.Run it under Supervisor
Keep
php artisan reverb:startrunning (example below) and restart it, and the queue workers, after every change on this page so they load the new values.Proxy the websocket
Forward
/app/(browser websockets) and/apps/(the server publishing messages) to the internal port, with theUpgradeheaders, and allow websockets at your CDN.
[program:omnigenix-reverb] command=php /var/www/omnigenix/artisan reverb:start autostart=true autorestart=true user=www-data redirect_stderr=true stdout_logfile=/var/www/omnigenix/storage/logs/reverb.log
# inside the server { } block of the site
location ~ ^/apps?/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 60s;
}No .env keys are needed: the admin values are applied at boot to the web requests, the queue workers and reverb:start alike. The Reverb server binds to 0.0.0.0 unless you set the optional REVERB_SERVER_HOST (for example 127.0.0.1 when only Nginx should reach it).
Leave Reverb off if you do not need it: nothing else in the platform depends on it. Version 1.0.0 has no admin inbox screen for replying to these messages.
Cache, Sessions & Redis
CACHE_DRIVER and SESSION_DRIVER default to file and database, which work everywhere. On larger installs use Redis for cache, sessions and the queue. After deploying, php artisan optimize caches config, routes and views; php artisan optimize:clear clears them.
Mail is set in Settings → Mail Setting (SMTP host, port, encryption, username, password, sender and signature) and applies to every e-mail; the password is stored encrypted. Use Send test mail. The MAIL_* keys in .env are only the fallback. Set SPF and DKIM for the sending domain so verification, invoice and reset e-mails reach the inbox.
S3-Compatible Storage
Settings → Storage switches the private media disk from local storage/app to AWS S3, Cloudflare R2, Wasabi, DigitalOcean Spaces or MinIO. Enter the access key, secret key (stored encrypted), region, bucket, endpoint, optional public URL and the path-style switch (MinIO usually needs it) and use Test connection. Only new files go to the new disk. Luma image-to-video requires S3-compatible storage because Luma only accepts image URLs.
Backups
Back up three things; each is useless without the others: the database, .env (especially APP_KEY, without which encrypted credentials cannot be decrypted) and storage/app + public/uploads (or your bucket). Example nightly cron that keeps 14 days:
Replace DB_USERNAME, DB_PASSWORD and DB_DATABASE with the values of the same keys in your .env.
30 2 * * * mysqldump --single-transaction -u DB_USERNAME -pDB_PASSWORD DB_DATABASE | gzip > /backups/omnigenix-$(date +\%F).sql.gz && find /backups -name 'omnigenix-*' -mtime +14 -delete 45 2 * * * tar czf /backups/omnigenix-files-$(date +\%F).tar.gz -C /var/www/omnigenix .env storage/app public/uploads
Copy backups off the server. Settings → Database Backup streams an on-demand MySQL/MariaDB dump straight to your browser (nothing is written on the server), useful before manual changes but not a replacement for scheduled mysqldump backups. To restore: import the dump into an empty database, put back .env and the file folders, then run php artisan optimize:clear && php artisan queue:restart.
Monitoring & Logs
- Settings → System Status: app and database version, cron heartbeat, queue backlog, failed jobs (retry/delete), storage and mail checks.
- AI health: provider and model error rates and latency; Usage & margin: credits, provider cost and margin.
- Activity Logs and Login Activity: admin actions and sign-ins.
- Logs:
storage/logs/laravel.log(useLOG_CHANNEL=daily) andstorage/logs/worker.log. - Uptime: point an external monitor at
https://YOUR-DOMAIN/api/v1/ping(returnspong).
.env Reference
Keys in the shipped .env.example and what to set, followed by optional keys that are read but not in the file. AI, payment, mail, storage, push, realtime, social and telephony credentials are not .env keys: they are saved encrypted from the admin panel. After any change run php artisan config:clear.
| Key | Default in .env.example | Notes |
|---|---|---|
APP_NAME | "OmniGenix AI" | Product name (the installer writes your site name) |
APP_ENV | production | Keep production on a server; local only for development |
APP_KEY | empty | Generated by the installer or php artisan key:generate; back it up (it decrypts stored credentials) |
APP_DEBUG | false | Never true on a live site |
APP_URL | https://app.example.com | Public HTTPS URL, no trailing slash; webhook, OAuth, call-callback and signed-file URLs are built from it |
APP_TIMEZONE | UTC | Platform default timezone (PHP name, e.g. Europe/London); each workspace can set its own |
APP_DEMO | false | Public demo only (see Demo Mode). The old name DEMO_MODE is still read if APP_DEMO is absent; use APP_DEMO |
APP_INSTALLED | false | Set to true by the installer; false or empty sends every request to /install; one of the three installer locks (with storage/app/installed and an existing Super Admin) |
TRUSTED_PROXIES | empty | Proxy/CDN IPs or CIDR ranges |
LOG_CHANNEL, LOG_DEPRECATIONS_CHANNEL, LOG_LEVEL | stack, null, warning | LOG_CHANNEL=daily for rotation |
DB_CONNECTION … DB_PASSWORD | mysql, 127.0.0.1, 3306, omnigenix, empty user/password | Your database (written by the installer) |
CACHE_DRIVER | file | redis on larger installs |
FILESYSTEM_DISK | local | Media storage is normally switched in Settings → Storage |
QUEUE_CONNECTION | database | Needs a queue worker; sync is for testing only |
QUEUE_VIA_SCHEDULER | false | true on shared hosting without a long-running worker |
SESSION_DRIVER, SESSION_LIFETIME | database, 120 | |
SESSION_SECURE_COOKIE | false | true once the site is on HTTPS |
ACTIVITY_LOGGER_ENABLED | true | Activity log |
REDIS_* | commented out | Optional Redis |
MOBILE_* | commented out (version 1.0.0; package/bundle default com.omnigenix.app in config/omnigenix.php) | App version gate and app-link values (Mobile App) |
SANCTUM_STATEFUL_DOMAINS | commented out | Only for a separate single-page front end on another domain |
OMNIGENIX_PLUGINS_PATH | optional, not in .env.example (default plugins/) | Plugin folder |
CSP_ENABLED | optional, not in .env.example (default true) | Sends the nonce-based Content-Security-Policy header on every HTML page. Leave it on; false switches the policy off completely |
CSP_REPORT_ONLY | optional, not in .env.example (default false) | true sends the policy as Content-Security-Policy-Report-Only: violations are reported in the browser console but nothing is blocked (useful while adding your own integrations) |
CSP_REPORT_URI | optional, not in .env.example (empty) | URL that receives CSP violation reports (report-uri) |
CSP_SCRIPT_SRC, CSP_STYLE_SRC, CSP_IMG_SRC, CSP_MEDIA_SRC, CSP_FONT_SRC, CSP_CONNECT_SRC, CSP_FRAME_SRC, CSP_FORM_ACTION, CSP_FRAME_ANCESTORS | optional, not in .env.example (empty) | Extra allowed sources for one directive each, as a comma-separated list, for your own analytics, chat widget or CDN, e.g. CSP_SCRIPT_SRC="https://www.googletagmanager.com" |
CREDIT_HOLD_OUTPUT_TOKENS | optional, not in .env.example (default 2048) | Output tokens reserved up front for a text call without max_tokens; the unused part is returned when the call ends |
REVERB_SERVER_HOST | optional, not in .env.example (default 0.0.0.0) | Interface the Reverb server binds to; all other realtime values are set in Settings → Realtime Settings (Reverb) |
MAIL_MAILER | optional, not in .env.example (default log) | Fallback only, used until Settings → Mail Setting is saved |
Check It Works
- Settings → System Status shows no warnings and a recent scheduler run.
php artisan schedule:listlists the tasks;supervisorctl statusshows the worker RUNNING.https://YOUR-DOMAIN/api/v1/pingreturnspong.- Mail Setting → Send test mail arrives.
- AI provider Test connection passes and one generation succeeds in a workspace.
- A sandbox payment activates the plan only after the webhook arrives.
- A video job finishes (proves the worker), and a scheduled social post publishes (proves cron).
Third-Party Costs
Hosting, domain, e-mail delivery, AI provider usage, payment gateway fees, Twilio/Plivo minutes and numbers, S3-compatible storage, Firebase, social network developer apps and Apple/Google developer accounts are external services with their own accounts, terms and fees, paid by you to the providers. They are not included in the item price. The full table (what each one is for, required or optional, how it is billed) is in Web Platform → Third-Party Services & Costs.