Operator FAQ

Short answers to the questions operators ask most, with links to the full guides.

Licensing

What happens if a license check fails?

A failed check starts a 72-hour grace period. Everything keeps working, and the server re-checks every hour instead of every 24 hours. Fix the cause, then click Verify Now under Settings > License & Updates. See Grace Period.

What happens when the grace period ends?

The platform enters restricted mode. New games are disabled, but games in progress can finish and players can still withdraw. Renew the license or contact support, then click Verify Now. See Restricted Mode.

The status says Not Configured. What’s missing?

LICENSE_KEY or LICENSE_DOMAIN isn’t set. Add both to .env.prod and restart the app. LICENSE_DOMAIN must be the bare domain your players use, such as poker.example.com. See License.

How do I move my license to a new server or domain?

On the old server, run ./deactivate-license.sh from the install directory, which also needs to contain .env.prod. You can then activate the same key on the new domain. Copy .env.prod across as well, because it holds your ENCRYPTION_KEY. See Backups.

A feature I want is locked. Why?

Your license plan sets the most features the install may use, and a database edit doesn’t get around it. Check Settings > Features to see what’s included. See Plan Feature Limits.

Email Delivery

No emails are being sent. Where do I start?

Check these in order:

1. Settings > Server: make sure Enable SMTP is on. With it off, nothing is sent.
2. Click Test Connection, which reports whether connecting and authenticating worked. See Testing the Connection.
3. In System Emails, check the event is enabled, then click Send Test on its row. The test goes to your own admin address. See System Email Events.
4. Check the Email Logs tab in the Logs Hub for the delivery status and error. See Email Logs.

Can I resend a failed email?

Yes. In Email Logs, click Retry on any email with the status Failed. See Retrying Failed Emails.

SMTP settings went blank and email stopped after a server move. Why?

The most likely cause is a changed ENCRYPTION_KEY. If the stored SMTP password can’t be decrypted, the app logs Failed to parse stored SMTP config, using defaults and uses the default settings, which have SMTP disabled. Restore the old key, or list it in ENCRYPTION_PREVIOUS_KEYS. See Secrets Management and Rotation.

2FA Lockouts

A player lost their authenticator. What do I do?

Open the player in Users and use Reset 2FA, which needs the users:edit permission. It clears their 2FA setup and backup codes straight away, and they can enable 2FA again from their profile. Confirm who you’re talking to first. See Resetting Two-Factor Authentication.

An admin lost their authenticator. What do I do?

Use a backup code at the login prompt. Each code works once. See Backup Codes.

Reset 2FA doesn’t clear admin login 2FA. It clears the account’s player 2FA, while admin login checks a separate admin 2FA record. The admin 2FA can otherwise only be disabled with a valid code, so if an admin has neither their authenticator nor a backup code, contact info@onlinepokerscript.com. Make sure every admin stores their backup codes safely when enabling 2FA.

Someone is being told they’ve made too many 2FA attempts.

Five failed attempts in 15 minutes trigger a temporary limit, and 10 failures lock 2FA for up to 24 hours. The lock clears by itself.

Everyone’s 2FA login is failing with a 503.

Check Redis. When Redis is enabled but unreachable, 2FA attempts fail with TWO_FACTOR_ATTEMPT_STORAGE_UNAVAILABLE rather than running without attempt tracking. Bring Redis back and logins recover.

Valid 2FA codes are rejected for everyone, and Redis is fine.

Check whether ENCRYPTION_KEY changed. 2FA secrets are encrypted with it. See What Happens if the Key Changes or Is Lost.

Payment Failures

A provider isn’t working. Where do I start?

Click Test on the provider’s card under payment systems, which checks the API keys and that the provider can be reached. See Testing a Provider Connection.

A player paid, but the deposit is still pending.

For automated providers, the balance is usually credited by the provider’s webhook. Check that:

• The provider is calling {siteBaseUrl}/api/v1/webhooks/payment/{paymentSystemId}, and your site can be reached from the internet.
• The provider card doesn’t show No webhook signing secret configured.
• Redis is up. If it’s enabled but unreachable, webhooks get a 503.

Webhooks are limited to 60 requests per minute per source and 300 per minute per provider. Above that they get a 429.

How do I approve a manual or bank transfer deposit?

Open the pending deposit and click Approve. The balance is credited unless an AML review holds the funds. See Approving Pending Deposits.

A financial operation failed in the background. Can I recover it?

Check the Dead Letter Queue tab in the Logs Hub. It holds background operations that used up their automatic retries, and you can retry or dismiss them from there. See Dead Letter Queue.

Players got a "Crash recovery" refund. Is that a bug?

No. After a restart, players who are no longer seated get their last committed table stack back, and any hand that was interrupted is void. See Cash Table Funds.

Backups

Are backups on by default?

Not on a fresh Docker install: install.sh doesn’t start the backup service. Start it once:

docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build backup

It then runs daily at 2:00 AM, keeps backups for 30 days, and writes to ./backups/postgres/. Change this with BACKUP_SCHEDULE and BACKUP_RETENTION_DAYS. See Backup & Recovery. On Kubernetes, see Backups.

What do backups not include?

They contain only the PostgreSQL database. Protect these separately:

• .env.prod, above all ENCRYPTION_KEY. Without it, a restored database can’t decrypt payment and SMTP credentials or 2FA secrets.
• The ./plugins directory.
• Files in the app container. docker-compose.prod.yml mounts no volume for uploaded custom avatars (/app/uploads) or KYC documents (KYC_STORAGE_DIR, by default storage/kyc-documents under /app), so they don’t survive the container being recreated, which happens on upgrades. If you use KYC uploads or custom avatars on Compose, mount persistent storage at those paths.

How do I know a backup will restore?

Rehearse it into a disposable database:

docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm backup restore --latest --rehearsal

For a real restore, see Restore from Backup.

Running the Platform

Can I run several servers behind a load balancer?

No. Run one app instance and scale it up. Running more is unsafe for gameplay and player funds. See Scaling and Multi-Node Deployment.

How do I rotate a secret?

See Secrets Management and Rotation. Don’t change ENCRYPTION_KEY without following that page first.

How do I upgrade or roll back?

See Upgrades and Rollback. To see what changed in each version, read the Release Notes.

Something is down right now. What do I do first?

Follow the Incident Runbook. For dashboards and alerts, see Observability.

How do I get help?

Email info@onlinepokerscript.com. See Getting Help.