MineGeo/docs/dokploy-deployment.md

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.

In the Dokploy application, open Environment and add both values under Build Time Arguments (not only under the regular runtime environment variables):

NEXT_PUBLIC_SUPABASE_URL=<your Supabase project URL>
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<your Supabase publishable key>

These values are used by Next.js while compiling browser code. Setting them only as runtime environment variables does not populate Dockerfile ARG values, which causes the build error that says they were empty. Both values are public client configuration; do not put SUPABASE_SECRET_KEY in Build Time Arguments.

Also set the following in Dokploy's regular runtime environment:

• 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:

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.

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 and Deployment API. This workflow uses TLS certificate verification and does not publish the image or source to a public service.