Private and custom server setup

1. Overview

A Rated server has two parts: a Cloudflare Worker that provides the API and admin panel, and a D1 database that stores accounts, entries, reviews, profiles, follows, blocks, and messages.

Private mode changes entry submissions into suggestions. Users can browse and review published entries, but new entries submitted by users wait for administrator approval.

2. Requirements

• A Cloudflare account with Workers and D1 available.
• Node.js and npm installed on your computer.
• The Rated server template ZIP from this page.
• A unique server name and strong secret values.

Download and extract the template. The folder contains the Worker script, base schema, migrations, and a Wrangler configuration template.

Download private server template

3. Create and initialize the D1 database

1. Open the Cloudflare dashboard and choose Workers & Pages → D1 SQL Database.
2. Create a database, for example rated-private-db.
3. Open the database and note its database ID.
4. Run the SQL files in this order for a new database.

wrangler login
wrangler d1 create rated-private-db
wrangler d1 execute rated-private-db --remote --file=worker/schema.sql
wrangler d1 execute rated-private-db --remote --file=worker/migrations/002_community_features.sql
wrangler d1 execute rated-private-db --remote --file=worker/migrations/003_profiles_social.sql

Migration 002_community_features.sql adds contributor attribution, publication status, and moderation fields. Migration 003_profiles_social.sql adds profile fields, follows, blocks, direct messages, and account reports.

For an existing server, take a D1 backup before migrating. Keep the current database and run only migrations that have not already been applied.

4. Configure and deploy the Worker

1. Open worker/wrangler.toml.
2. Change database_name to your D1 database name.
3. Replace PASTE_YOUR_DATABASE_ID_HERE with the database ID from Cloudflare.
4. Set a unique Worker name and your preferred server display name.

The provided configuration uses private mode:

name = "rated-private-server"
main = "worker.js"
compatibility_date = "2024-09-01"

[vars]
SERVER_MODE = "private"
SERVER_NAME = "My Private Rated Server"

[[d1_databases]]
binding = "DB"
database_name = "rated-private-db"
database_id = "PASTE_YOUR_DATABASE_ID_HERE"

From the extracted project folder, deploy the Worker:

wrangler deploy --config worker/wrangler.toml

When deployment completes, Cloudflare displays the Worker URL, usually ending in .workers.dev. Keep the HTTPS address.

5. Add the required secrets

The Worker requires two secrets. Set them from the same project directory:

wrangler secret put JWT_SECRET
wrangler secret put ADMIN_TOKEN

Enter a long, unique random value for each prompt. Keep both values private. Do not place them in the website, Android project, public repository, screenshots, or chat messages.

JWT_SECRET signs login sessions. Changing it invalidates existing sessions. ADMIN_TOKEN protects the moderation panel and admin API. Anyone with the admin token can manage the server.

6. Open the admin panel

Visit your Worker URL with /panel appended, for example:

https://your-server.workers.dev/panel

Enter the ADMIN_TOKEN when asked. The panel lets you:

• Add, edit, hide, restore, and remove catalogue entries.
• Review suggestions and approve or reject them.
• Review item and review reports.
• Review account reports, dismiss them, or suspend accounts.
• Restore or remove hidden reviews.

Keep the admin token private and sign out of the panel on shared devices.

7. Connect from Rated

Open the Android app or browser version. Go to server management, paste your Worker's HTTPS URL, and connect. Rated reads the server's configured display name and stores the server in the saved list after a successful connection.

Accounts, profiles, follows, messages, entries, and reviews are separate on each server. Creating an account on one server does not create it on another.

8. Profiles, follows, blocking, and messages

After applying migration 003 and deploying the updated Worker, users can:

• Set a display name, short bio, and optional HTTPS avatar URL.
• View published entries and reviews associated with an account.
• Follow and unfollow other accounts and view follower/following lists.
• Block or unblock accounts. Blocking removes both follow connections and prevents profile and message access between the two accounts.
• Report accounts to the server administrator.

Direct messages are text-only and require mutual follows. Messages have a 2,000-character limit and a daily per-sender limit. If either user blocks the other or the mutual-follow relationship ends, the conversation cannot be accessed until the relationship requirements are met again.

9. Updating an existing server

1. Back up the D1 database.
2. Confirm which migrations have already been applied.
3. For profiles and social features, run 003_profiles_social.sql once if it has not been applied.
4. Deploy the updated worker.js using your current Wrangler configuration.
5. Verify the root URL, /api/config, /panel, and sign-in.

Do not create a new D1 database during an update unless you intend to start a separate server. Keep the existing database binding and its ID.

10. Troubleshooting

“This doesn't look like a Rated server”

Check that the URL points to the Worker root, uses HTTPS, and responds with a valid /api/config endpoint.

Database errors after deployment

Confirm the D1 binding is named exactly DB. Check that the base schema and required migrations ran against the same database bound to the Worker.

Profile or message features return 500 errors

Confirm migration 003 completed successfully and that the deployed Worker is the updated version.

Admin panel says the token is invalid

Confirm the Worker secret is named ADMIN_TOKEN and the token is entered without extra spaces.

Users cannot send messages

Both accounts must follow each other, neither account can have blocked the other, and both accounts must be active.