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](account-controls.md).

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](developer-api.md) 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](prometheus.md) for the copyable config,
dashboard import, credential rotation, and metric definitions.

The portable Windows Electron client and release process are described in
[Desktop client](desktop.md). 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](discord-integration.md)
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 hosted community forum is linked in the header and footer using
`shared/forum.json`. `MINEGEO_FORUM_URL` can override its public HTTPS address.
See [Community forum](forum.md) for forum ownership and starter content.

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](https://vercel.com/docs/rest-api/deployments/create-a-new-deployment). 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](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](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](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.