| # Cloudflare Turnstile Integration |
|
|
| TTS Arena supports Cloudflare Turnstile for bot protection. This guide explains how to set up and configure Turnstile for your deployment. |
|
|
| ## What is Cloudflare Turnstile? |
|
|
| Cloudflare Turnstile is a CAPTCHA alternative that provides protection against bots and malicious traffic while maintaining a user-friendly experience. Unlike traditional CAPTCHAs, Turnstile uses a variety of signals to detect bots without forcing legitimate users to solve frustrating puzzles. |
|
|
| ## Setup Instructions |
|
|
| ### 1. Register for Cloudflare Turnstile |
|
|
| 1. Create a Cloudflare account or log in to your existing account |
| 2. Go to the [Turnstile dashboard](https://dash.cloudflare.com/?to=/:account/turnstile) |
| 3. Click "Add Site" and follow the instructions |
| 4. Create a new site key |
| - Choose "Managed" or "Invisible" mode (Managed is recommended for better balance of security and user experience) |
| - Set an appropriate domain policy |
| - Create the site key |
|
|
| Once created, you'll receive a **Site Key** (public) and **Secret Key** (private). |
|
|
| ### 2. Configure Environment Variables |
|
|
| Add the following environment variables to your deployment: |
|
|
| ``` |
| TURNSTILE_ENABLED=true |
| TURNSTILE_SITE_KEY=your_site_key_here |
| TURNSTILE_SECRET_KEY=your_secret_key_here |
| TURNSTILE_TIMEOUT_HOURS=24 |
| ``` |
|
|
| | Variable | Description | |
| |----------|-------------| |
| | `TURNSTILE_ENABLED` | Set to `true` to enable Turnstile protection | |
| | `TURNSTILE_SITE_KEY` | Your Cloudflare Turnstile site key | |
| | `TURNSTILE_SECRET_KEY` | Your Cloudflare Turnstile secret key | |
| | `TURNSTILE_TIMEOUT_HOURS` | How often users need to verify (default: 24 hours) | |
|
|
| ### 3. Implementation Details |
|
|
| When Turnstile is enabled: |
| - All routes and API endpoints require Turnstile verification |
| - Users are redirected to a verification page when they first visit |
| - Verification status is stored in the session |
| - Re-verification is required after the timeout period |
| - API requests receive a 403 error if not verified |
|
|
| ## Customization |
|
|
| The Turnstile verification page uses the same styling as the main application, providing a seamless user experience. You can customize the appearance by modifying `templates/turnstile.html`. |
|
|
| ## Troubleshooting |
|
|
| - **Verification Loops**: If users get stuck in verification loops, check that cookies are being properly stored (ensure proper cookie settings and no browser extensions blocking cookies) |
| - **API Errors**: If API clients receive 403 errors, they need to implement Turnstile verification |
| - **Missing Environment Variables**: Ensure all required environment variables are set correctly |
