Exclude build artifacts and document Dokploy deployment

docs/dokploy-deployment.md

@@ -0,0 +1,81 @@
+# Dokploy deployment
+
+The Gitea Actions workflow in `.gitea/workflows/deploy-dokploy.yml` deploys
+commits from `master` to Dokploy. The act_runner service runs in Docker on the
+MacBook, and this workflow selects its Linux Docker job environment with the
+`ubuntu-latest` label. The job checks out the private repository, creates a ZIP
+from the committed files only, and uploads it to Dokploy over HTTPS. Dokploy
+builds the Docker image from the repository's root `Dockerfile` on the VPS and
+performs the deployment. No image registry is used, and the workflow does not
+use SSH or the VPS root password.
+
+## One-time Dokploy setup
+
+Create a Dokploy Application for MineGeo with the **Drop** (drag-and-drop)
+source provider. If the current Gitea-linked application cannot switch its
+provider, create a separate application and move the domain after its first
+successful deployment. Configure its build type as **Dockerfile**, with the
+Dockerfile and build context both at the repository root.
+
+Set these Docker build arguments in the Dokploy application:
+
+- `NEXT_PUBLIC_SUPABASE_URL`
+- `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`
+
+Set the required runtime environment values in Dokploy as well:
+
+- `NEXT_PUBLIC_SUPABASE_URL`
+- `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`
+- `SUPABASE_SECRET_KEY` (server-only; never a build argument)
+- `MINEGEO_URL` (the public HTTPS site origin)
+- `MINEGEO_ALLOW_ANY_ORIGIN=false`
+
+Add any optional production variables from `.env.example` in Dokploy's
+environment settings. Do not upload `.env.local` or add it to the repository.
+
+## Gitea Actions secrets
+
+Add the following repository Actions secrets in Gitea. Use the HTTPS origin of
+Dokploy for `DOKPLOY_URL`, without `/api` or a trailing path.
+
+- `DOKPLOY_URL`
+- `DOKPLOY_API_KEY` (create this in Dokploy)
+- `DOKPLOY_APPLICATION_ID` (copy this from the target Application)
+
+In the runner's Gitea configuration, ensure `ubuntu-latest` is registered with
+the Docker schema, for example:
+
+```text
+ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest
+```
+
+The workflow uses `runs-on: ubuntu-latest`, so it runs inside that Linux job
+container rather than directly on macOS or inside the act_runner service
+container. If your runner uses another Docker label, change `runs-on` to that
+label. The selected image needs `git`, `curl`, and Node.js so the job can archive
+the commit, upload it, and inspect deployment status. Gitea documents how
+runner labels select host versus Docker execution in the [runner
+documentation](https://gitea.com/gitea/runner/src/branch/main/README.md#labels).
+
+Every push to `master` triggers a deployment. The job suppresses API response
+bodies and infrastructure addresses in its logs, waits for Dokploy's deployment
+status, and fails if the upload or deployment fails. Build logs remain available
+in the Dokploy dashboard.
+
+`git archive` sends tracked files from that commit only. It does not include
+`.git` metadata, local environment files, untracked files, or local caches. The
+public Windows installer remains in the site image because MineGeo serves it
+from `/desktop/`; the large JVM heap dump was removed because it is neither
+application code nor a runtime asset. The Docker build also excludes the
+Minecraft Java workspace, Gradle caches, build output, and heap dumps.
+
+The ZIP still contains the required Windows installer (about 96 MiB), so the
+Dokploy endpoint and any reverse proxy in front of it must accept the archive's
+full size. If the upload is rejected with a size-related HTTP error, use the
+Dokploy deployment logs to distinguish an upload limit from a build failure.
+
+Dokploy documents the upload endpoint and deployment-status API in its
+[Application API](https://docs.dokploy.com/docs/api/application) and
+[Deployment API](https://docs.dokploy.com/docs/api/deployment). This workflow
+uses TLS certificate verification and does not publish the image or source to
+a public service.

docs/production.md

@@ -53,3 +53,4 @@ all five rounds with idempotent activation/submission and out-of-bounds rejectio
 It removes only its generated guest session. A published map is required.
 
 See [the audit record](production-audit.md) for evidence and remaining limits.
+For self-hosted Docker deployment, see [Dokploy deployment](dokploy-deployment.md).