# 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):

```text
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:

```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.