# Running the panel inside an existing Dokploy

When you already run [Dokploy](https://dokploy.com), deploy **the panel itself as
a Dokploy Compose application** instead of using `install.sh`. Dokploy owns the
edge (its Traefik on 80/443) and the lifecycle; the panel rides on Dokploy's
shared `dokploy-network`, and every customer app the panel installs routes
through the *same* Traefik automatically.

This uses Dokploy's own projects/services for the **panel**. The customer apps
the panel deploys are **not** Dokploy projects — the panel remains their control
plane; they just borrow Dokploy's Traefik network for routing.

## Deploy

1. **Create a Compose service** in Dokploy.
   - Source: the LicensePanel git repo.
   - Compose path: `infra/panel-stack/docker-compose.dokploy.yml`.
   - The bootstrap init image **builds from the cloned repo** — no pre-published
     image is required.
2. **Set environment** (Dokploy → Environment). Copy
   [`.env.dokploy.example`](.env.dokploy.example) and fill it in. These are the
   only variables the compose reads — everything else the panel needs (`Panel__*`,
   `ConnectionStrings__PanelDb`, `ASPNETCORE_URLS`, the docker-proxy endpoint,
   the `dokploy` edge preset) is **pre-wired in the compose** and must not be set
   by hand.

   | Variable | Required | Default | Purpose |
   |---|---|---|---|
   | `POSTGRES_PASSWORD` | **yes** | — | Postgres password, baked into the cluster on first boot. Don't change it afterwards (the data volume keeps the original). |
   | `PANEL_HOST` | **yes** | — | The panel's domain, e.g. `panel.example.com`. Used in the Traefik `Host(...)` router rule. |
   | `PANEL_IMAGE` | no | `registry.innovation-lab.co/modern-solutions/licensepanel:latest` | Full panel image ref (`repo:tag`) in one var. Pin a version with the tag, e.g. `registry.innovation-lab.co/modern-solutions/licensepanel:1.6.1`, or point at a private mirror. Use ≥ `1.6.0` (see gotchas). Published to the self-hosted Forgejo registry (Docker Hub + GHCR retired 2026-08-05). |
   | `POSTGRES_IMAGE` | no | `postgres:17.2-alpine` | Full Postgres image ref. |
   | `DOCKERPROXY_IMAGE` | no | `tecnativa/docker-socket-proxy:0.3.0` | Full docker-socket-proxy image ref. |
   | `LICENSE_SERVER_BASE_URL` | no | `https://license-api.mod-sol-sa.com` | LicenseServer endpoint. The panel self-registers a free-tier license by fingerprint; no API key needed. Override only for an on-prem LicenseServer. |

   **Deliberately NOT set here** (unlike `install.sh`): `ACME_EMAIL` and the edge
   ports (`HTTP_PORT`/`HTTPS_PORT`/`BOOTSTRAP_PORT`) — **Dokploy's Traefik owns
   the edge and ACME**, so configure the Let's Encrypt email in Dokploy's Traefik
   settings, not here. `PANEL_DATA_ROOT` is fixed to `/var/lib/licensepanel`
   (the host bind + bootstrap depend on it); don't override it. There is no
   `Panel__Updates__*` self-update config — in Dokploy you update by bumping
   `PANEL_IMAGE`'s tag and redeploying.
3. **Attach the domain** `PANEL_HOST` in Dokploy's UI (or rely on the Traefik
   labels already in the compose). Either way the panel is served at
   `https://PANEL_HOST` via Dokploy's Traefik, TLS issued by the `letsencrypt`
   resolver.
4. **Deploy.** First boot runs `panel-bootstrap` (TLS material + state dirs),
   then panel + Postgres start.
5. **Initial Configuration.** Open `https://PANEL_HOST/` — a fresh install
   redirects to `/initial-configuration`; set the admin and submit.

## Initial Configuration & the bootstrap window

First boot opens a **60-minute bootstrap window** during which
`/initial-configuration` is reachable without auth. If it lapses **before** you
create an admin, `/initial-configuration` redirects to `/auth/signin` (status
`reactivation_required`) — this is expected, not a failure. Re-open it from the
host with one `docker exec` (the panel is the only container on the
`registry.innovation-lab.co/modern-solutions/licensepanel` image; Dokploy gives
it a project-prefixed name like `license-panel-…-panel-1`, so match by image,
not a fixed name):

```bash
# Find the panel container (image = .../licensepanel, not -installer):
docker ps --format '{{.Names}}\t{{.Image}}' | grep -i 'modern-solutions/licensepanel:'

cid=<that-name>
docker exec "$cid" /app/licensepanel server bootstrap status     # → reactivation_required
docker exec "$cid" /app/licensepanel server bootstrap reactivate  # → fresh 60-min window
```

Then reload `/initial-configuration` and submit promptly. `reactivate` refuses
(`Reactivated=false`) once an admin exists — at that point setup is already
done, so just sign in. A redeploy does **not** reopen the window (state persists
in the `panel_data` volume); only `reactivate` does.

## Updating a Dokploy panel

You update by **redeploying in Dokploy**, not via the in-app updater. The Dokploy
compose deliberately omits the `Panel__Updates__*` self-update wiring (that path
spawns an updater container and is for the standalone install). To update: bump
`PANEL_IMAGE`'s tag (or rely on `pull_policy: always`) and redeploy — `latest`
re-resolves and the new image lands.

The in-UI "update available" badge is driven by the release **feed**
(`license-install.mod-sol-sa.com/latest.json`), which is independent of the panel
and **does not affect** its operation — a `404`/`UPDATE_FEED_UNREACHABLE` is a
benign log line, not a health-degrade. If you want the badge to work, the
**installer-site** service (not the panel) needs `GH_TOKEN` set to a repo-read
PAT and at least one GitHub **Release** to exist (the feed is built from the
Releases API; a private repo 404s without the token). See
`infra/installer/host/README.md`.

## What the compose does (vs the standalone install)

| Concern | Standalone (`install.sh`) | Dokploy |
|---|---|---|
| Edge / TLS | bundled `panel-traefik` owns 80/443 | **Dokploy's Traefik** (no bundled Traefik) |
| Pre-flight (certs, dirs, KEK) | `install.sh` | `panel-bootstrap` init container (reuses the same `infra/installer/lib` scripts) |
| Customer-app routing | `panel-network` | `dokploy-network` via `Panel__Edge__Preset=dokploy` |
| Updates | panel self-update | redeploy in Dokploy (`pull_policy: always` re-pulls; set `PANEL_IMAGE` tag to pin) |

## Hard requirements / gotchas

- **`projects/` is a host bind, host-path == container-path**
  (`/var/lib/licensepanel/projects`). The panel writes each app's compose file
  there and shells `docker compose -f <path>` through the socket-proxy; the host
  daemon resolves that path on its own filesystem. A named volume would break
  customer deploys. Ensure that host path exists / is allowed on the Dokploy node.
- **Route to port `8080` (plain HTTP).** The panel serves HTTP on `:8080`;
  Dokploy's Traefik terminates TLS at the edge (`letsencrypt`) and proxies HTTP
  to it. If you attach the domain via Dokploy's UI instead of the labels, set the
  port to `8080` (scheme http — the default). This avoids a self-signed backend
  (no Traefik `insecureSkipVerify` needed).
- **Requires panel ≥ 1.6.0.** Traefik's docker provider will NOT route a
  container that isn't `healthy`, and panel < 1.6.0 flaps to `unhealthy` under
  the docker-proxy `ObjectDisposedException` bug — so it never gets a route.
  `latest` is fine; if you pin `PANEL_IMAGE`'s tag, use 1.6.0 or newer.
- **Stale `latest` → unhealthy.** Docker never re-pulls a `latest` it already
  has locally, so a node that pulled an older panel keeps running it (the
  pre-1.6.0 flap above → `/health` 503 → unhealthy → no Traefik route) even
  after a new `latest` is published. The compose sets `pull_policy: always` on
  the `panel` service so **every Dokploy redeploy re-pulls the current image**.
  If you already have a stuck container, just **redeploy** in Dokploy — it will
  now land the fixed image. (Verify with `docker image inspect` / the panel's
  startup log: a fixed image logs no `BootstrapListenerManager … Addresses
  cannot be modified` exception.)
- **`redirect-to-https@file`** — the panel's *customer-app* routers reference
  this middleware. Dokploy's Traefik provides HTTP→HTTPS redirection by default;
  if a customer app's HTTP router errors on a missing middleware, either define
  `redirect-to-https@file` in Dokploy's dynamic config or set the project's
  custom entrypoints so the panel skips the redirect pair.
- **Docker socket** — the panel reaches Docker only through the Tecnativa
  `dockerproxy` (verb allowlist), never the raw socket. The proxy mounts
  `/var/run/docker.sock:ro`; Dokploy permits this for Compose apps.
- **Validated on a Dokploy-equivalent harness** (Swarm + attachable
  `dokploy-network` overlay + Traefik v3.6 docker provider, matching Dokploy):
  the panel attaches to the overlay, Traefik discovers its labels, and
  `GET /api/version` + the SPA return 200 through the edge. Confirm on a real
  Dokploy node before production (Dokploy's own Traefik config + ACME for a real
  domain). Customer-app routing (the `dokploy` edge preset) needs a 1.6.0+ image
  and was not exercised in the harness.

---

# Dokploy as the ORCHESTRATION BACKEND (`--backend dokploy`)

The section above runs the panel **as a Dokploy app**. This section is the other
topology: `install.sh --backend dokploy` provisions Dokploy on the host and the
panel **drives Dokploy's REST API as its container/Traefik/TLS engine**. Every
product stack the panel installs becomes a Dokploy Compose app. Same panel API,
same entities — only the engine differs (selected by `Panel:Orchestration:Backend`).

Pinned to Dokploy **v0.29.13** (ADR 0050). The panel talks to Dokploy over
`dokploy-network` at `http://dokploy:3000/` with an `x-api-key`; the `:3000`
dashboard is **sealed** from the host (see below).

## How routing + domains work in backend mode

- **Dokploy owns Traefik + TLS.** The panel does **not** render its own
  `traefik.*` labels for product stacks (the renderer skips them when Dokploy owns
  routing); instead the panel calls Dokploy's `domain.create`/`domain.delete` and
  the container joins `dokploy-network` so Dokploy's Traefik discovers it.
  `certificateType=letsencrypt` when the domain uses ACME, else `none`.
- **A domain change forces a redeploy.** Dokploy injects Traefik labels into the
  stack's compose and only re-reads them on redeploy — so adding/removing a
  domain is a *queued redeploy* operation in the UI, not an instant change. This
  is expected; the panel surfaces it as a redeploy, never pretends it's live
  immediately.
- **Advanced routing is lossy.** Dokploy's compose-domain model can't express a
  custom resolver / custom entrypoints / arbitrary middlewares — the panel logs a
  warning and routes without them (decision-3 tradeoff). Use compose mode if you
  need the panel's full `BuildTraefikLabels` surface.

## Deploy-status truth (#3987)

Dokploy reports a deploy `done` even when a container crashed. The panel **never
trusts Dokploy's status for health**: after a deploy settles it cross-checks the
real containers via the socket proxy (`com.docker.compose.project == <returned
appName>`) and fails the deploy `DOKPLOY_DEPLOY_UNHEALTHY` if a service isn't
actually running/healthy. `Ps`/logs/per-service restart-stop-start all run off
the socket proxy, not Dokploy's (unauthenticated) WebSocket.

## Secrets split (Constitution II)

Secret-flagged template variables are **never sent to Dokploy's DB**. The panel
writes them to a `chmod 600` `secrets.env` referenced via `env_file:` inside the
rendered compose (a file Dokploy materialises but never stores in its DB); only
non-secret vars go to Dokploy via `saveEnvironment`. The Dokploy API key + the
registry token live in KeyCustody, never plaintext at rest.

## The `:3000` dashboard is sealed

The installer removes Dokploy's `:3000` host publish (`docker service update
--publish-rm`). The panel↔Dokploy path is the `dokploy-network` overlay, so no
host port is needed. Re-expose only for debugging with
`install.sh --expose-dokploy-dashboard` (or re-add the publish manually), and
firewall it — the Dokploy log WebSocket is unauthenticated in v0.29.13.

## Pinned-version upgrade gate

`Panel:Dokploy:PinnedVersion = v0.29.13` is a **verified contract** (ADR 0050),
not "latest". The panel asserts the running Dokploy version at bootstrap and logs
a loud warning on drift. **Do not bump Dokploy** without re-running the
`DokployApiClient` contract tests + the both-backend conformance suite against the
new version — a pin bump is a deliberate, tested step. v0.29.14+ is NOT adopted
until re-verified.

## Registry (private panel image)

The panel image is private, so the installer `docker login`s from `--registry-*`
(interim manual creds) before pulling, and `bootstrap-dokploy` registers the same
registry with Dokploy (`registry.create`/`testRegistry`) so Dokploy can pull it
for the panel's own stack. License-driven credentials (no manual creds) are the
separate DKB-REG delivery.
