MineGeo/docs/vercel-deployment.md

Deploy MineGeo

Account restrictions and appeals require 20261013070138_account_controls_and_appeals.sql before deploying. Live appeal updates additionally require 20261013074208_account_appeals_realtime.sql, which adds restricted read policies and the Realtime publication tables. Existing Supabase public environment variables are sufficient; no new secrets are needed. No new environment variables are needed. Admin Tools is at /admin (Admin only), Moderation Tools is at /moderation (Moderators and Admins); account status and appeals are at /ban/appeal. The built-in guide is /docs?page=account-bans. See Account controls.

The scoped developer API requires 20261012124943_developer_api_keys.sql. No additional environment variables are needed. The standalone panel is /dev/api, /api/dev redirects there, and the versioned read-only API is /api/dev/v1. See Developer API for permissions, rate limits, revocation, OpenAPI and Python requests examples.

Admin-only Prometheus/Grafana setup requires 20261012085217_prometheus_metrics.sql. No new Vercel variables are needed: Admins generate a dedicated scrape token in Moderation. See Prometheus and Grafana for the copyable config, dashboard import, credential rotation, and metric definitions.

The portable Windows Electron client and release process are described in Desktop client. Build and publish the EXE before deploying changes to desktop download links. Public desktop releases are included in the upload; the local Electron source, build cache, and packaging toolchain are excluded.

For the Vercel plugin deployment of Desktop 1.0.0, the public installer parts are staged in Supabase Storage's minegeo-desktop-builds bucket under the release SHA-256. The deployment snapshot downloads and verifies each part before the existing assembly script verifies the complete EXE. Keep these immutable parts for rebuilding that snapshot. No Storage credentials are included in the snapshot, and players download the assembled EXE from /desktop/ on MineGeo.

Optional Discord map and multiplayer-party announcements use DISCORD_BOT_TOKEN, DISCORD_MAPS_CHANNEL_ID, and DISCORD_PARTIES_CHANNEL_ID. All published parties use the same configured channel. Follow Discord bot setup for creation, permissions, Vercel variables, and retries. Apply the Discord queue migration before deploying this feature; the bot token stays server-only.

Optional community buttons appear in the footer when MINEGEO_DISCORD_URL or MINEGEO_TELEGRAM_URL is configured. Set these public links in .env.local for local development (ordinary .env also works). Restart the local server after changing a link. For the hosted site, add the same names as Production Config variables in the MineGeo Vercel project, then redeploy. These values are public destinations; no Discord bot token or Telegram API key is needed.

The MineGeo community forum at https://forum.minegeo.site/ is linked in the header and footer using shared/forum.json. MINEGEO_FORUM_URL can override its public HTTPS address. See Community forum for its categories, welcome topic, and starter discussions.

Discord accepts HTTPS links on discord.gg, discord.com, www.discord.com, and discordapp.com. Telegram accepts t.me and telegram.me, including group invite links. Blank, malformed, or unsupported URLs hide the corresponding button. Each button opens its configured destination in a new tab.

Run npm run deploy from the project directory. The script collects all web source files and public assets, uploads large release files separately and the remaining source in one request, waits for the build, and prints the deployment URL. It uses the Vercel deployments API. The database credentials already configured in Vercel remain there. Mod captures are processed by the deployed Vercel API: upload finalization starts background image processing with Next.js after, and the authenticated dashboard resumes queued or expired jobs. The function has a 300-second limit and uses the existing Supabase queue, Storage buckets, retry count, and completion transaction. It processes one PNG at a time in memory, so it needs no local capture directory or running Minecraft client.

Plugin terrain exports still require the standalone Minecraft rendering worker on its current host. That renderer builds panoramas with Chromium and vanilla Minecraft assets; it is separate from the deployed mod-image processor.

The script excludes Git metadata, local environment files, caches, generated captures, tests, Java build sources, and development tools. It checks uploaded content, including the downloadable JARs, for references to the Git server. Nothing is pushed to Gitea or connected to a Git provider.

Authentication is needed once: run vercel login, or put a Vercel token in the ignored .env.deploy.local file as VERCEL_TOKEN=.... The Codex Vercel plugin's login does not sign the local script in. Tokens are never included in the upload or command output.

Useful options:

• npm run deploy -- --dry-run: inspect file count and the privacy check without uploading.
• npm run deploy -- --preview: create a preview deployment.
• npm run deploy -- --help: show usage.

Vercel Web Analytics is included in the root layout through @vercel/analytics/next, so page views and client-side navigation are tracked across the site. Enable Web Analytics in the MineGeo project's Analytics tab before deploying. After deployment, visit the site and navigate between pages to verify collection. Content blockers can prevent analytics requests.

Analytics uses the existing Vercel project and requires no Git connection or additional Supabase credentials.

Multiplayer uses the Supabase migration described in multiplayer.md. Apply that migration to a new database before deploying the multiplayer web files. Room chat also requires 20261007155622_multiplayer_chat.sql before the web update. Account-only party hosting requires 20261010053429_multiplayer_account_hosts.sql.

Map ZIP sharing requires 20261007145000_map_sharing.sql. Imported maps stay private and can be played without moderation; publication is blocked. See map-sharing.md for the archive format and verification.

The script targets the existing MineGeo project. Set VERCEL_PROJECT_ID and VERCEL_ORG_ID to deploy a copy to another Vercel project.

Player bug reporting requires 20261008071054_bug_reports.sql and the Linear server credentials described in bug-reports.md. Configure the Comment and Issue webhook events before deploying so staff replies, glow commands, and status changes reach players. Report retention also requires 20261010053310_bug_report_retention.sql and a Linear API key with Read and Write permissions. Closed reports move to Done and are deleted from MineGeo and Linear after three days through a durable workflow; no cron job is required. Glow colors and user prefixes also require 20261008075322_profile_identity.sql before deploying the updated account, catalog, and multiplayer pages.

Custom difficulty presets for solo and multiplayer games require 20261013095201_custom_difficulty_presets.sql before deploying. The migration stores the shared presets and snapshots their settings in each game and room. No additional Vercel environment variables are needed.

Account photo uploads require 20261013123545_profile_avatars.sql before deploying. The migration creates the public avatar bucket with a 5 MiB file limit and owner-scoped upload/delete policies. Existing public Supabase environment variables are sufficient; no additional secrets are needed.