---
title: "Bare server"
description: "Run wervt on any server with Docker, without Coolify."
canonical_url: "https://docs.lightdrop.cloud/self-hosting/bare-server"
---
# Bare server

> Run wervt on any server with Docker, without Coolify.

The stack itself is `deploy/compose.yaml`: runtime, control plane, PgBouncer, Electric, logs and
Garage. `deploy/compose.caddy.yaml` adds what Coolify provides on
[production](https://docs.lightdrop.cloud/self-hosting/production), or `deploy/compose.tunnel.yaml`[behind a Cloudflare Tunnel](#behind-a-cloudflare-tunnel):

<table>
<thead>
  <tr>
    <th>
      Service
    </th>
    
    <th>
      Role
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        caddy
      </code>
    </td>
    
    <td>
      HTTPS on ports 80 and 443, certificates from Let's Encrypt
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        postgres
      </code>
    </td>
    
    <td>
      Postgres 18 (with pgvector) and <code>
        wal_level=logical
      </code>
      
      , on a network the runtime isn't on
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        postgres-backup
      </code>
    </td>
    
    <td>
      Nightly dumps of the database, to a volume and optionally S3 (<a href="https://docs.lightdrop.cloud/self-hosting/backups">
        Backups
      </a>
      
      )
    </td>
  </tr>
</tbody>
</table>

The docs site is an app like the sign-in and the dashboard, deployed after the
[first start](#first-start). Apps' email footers name your domain; the runtime passes it to apps
when they start, so apps need no rebuild after `.env` changes, only a `docker compose up -d` of
the runtime.

## Requirements

- A server with Docker and the Compose plugin, ports 80 and 443 open.
- A domain, here `wervt.example.com`, with `wervt.example.com` and `*.wervt.example.com` pointing at
the server (A, and AAAA if it has IPv6).
- For sign-in codes and apps' mail, a [Brevo](https://brevo.com) API key and a verified sender, or
a mailbox you already have (`MAIL_SMTP_*` in `.env`). The sender's domain needs an SPF record
that allows that mail server, e.g. `v=spf1 redirect=smtp.rzone.de` for Strato. With a DMARC
policy of `p=reject` and no SPF, recipients reject the sign-in codes.

## Start

The wervt repository is private, so the server needs read access to clone it. Use a
[fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) for
`wervt-app/wervt` with only **Contents: Read-only**, or a
[deploy key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys)
and `git clone git@github.com:wervt-app/wervt.git` instead:

```bash
git clone https://x-access-token:<token>@github.com/wervt-app/wervt && cd wervt/deploy
cp .env.example .env   # the domain, your e-mail, and a fresh secret for every `change-me`
docker compose -f compose.yaml -f compose.caddy.yaml up -d --build
```

The token stays in the clone's remote, so [updates](#updates) pull with it too. Give it an expiry
and replace it with `git remote set-url origin https://x-access-token:<new token>@github.com/wervt-app/wervt`.

`openssl rand -hex 32` makes a secret. Keep `.env` safe: `WERVT_DB_SECRET` derives every app's
database password, app token and S3 key, so losing or changing it locks apps out of their data.
The sign-in's secret derives from it too; set `BETTER_AUTH_SECRET` with `wervt env auth` only to
use your own.

## First start

The stack runs, but the sign-in (the auth app), the dashboard and these docs are apps like any
other, so they still need deploying. Do that from the repo with the CLI, which needs Node 24 or
newer and the repo's dependencies. Nothing has to be built first: inside the repo, the CLI and
`@wervt/nuxt` run from their TypeScript sources.

On a machine with Node, in the repo's root:

```bash
vp install   # or pnpm install
pnpm --dir docs install   # the docs have dependencies of their own
export WERVT_URL=https://api.wervt.example.com WERVT_TOKEN=<WERVT_DEPLOY_TOKEN from .env>
pnpm app:deploy auth
pnpm app:deploy dashboard
WERVT_DOMAIN=wervt.example.com pnpm app:deploy docs
pnpm exec wervt access docs --public
```

The docs are built for your server: commands, addresses, `llms.txt`, their MCP server and the
agent skill name `WERVT_DOMAIN` instead of wervt.app. They are served at the domain itself, unless
[another app](#an-app-at-the-domain-itself) is; then they stay at `docs.wervt.example.com`. Skip
them and the domain answers that there is no app yet; emails and the dashboard then leave out their
link to the docs.

The server itself only needs Docker. To deploy from there, run the same in a Node container, in
the repo's root (`cd ..` from `deploy/`). `corepack pnpm` fetches the pnpm version the repo pins;
`corepack enable` fails there, since the container doesn't run as root:

```bash
docker run --rm -it -v "$PWD":/src -w /src -u "$(id -u):$(id -g)" -e HOME=/tmp \
  -e WERVT_URL=https://api.wervt.example.com -e WERVT_TOKEN=<WERVT_DEPLOY_TOKEN> \
  node:24 bash
corepack pnpm install
corepack pnpm --dir docs install
corepack pnpm app:deploy auth
corepack pnpm app:deploy dashboard
WERVT_DOMAIN=wervt.example.com corepack pnpm app:deploy docs
corepack pnpm exec wervt access docs --public
```

Before DNS points at the server, deploy straight to the control plane on the stack's network:
start the container with `--network deploy_default` and `-e WERVT_URL=http://wervt-control:9100`.
The deploy checks don't need DNS either, control requests the pages through the runtime.

Then give the dashboard its access to the control plane, the deploy token again, which it keeps on
its server side only, and make it invite-only (`pnpm exec wervt …`, or `corepack pnpm exec wervt …`
in the container):

```bash
wervt env dashboard --set CONTROL_URL=https://api.wervt.example.com \
  --set CONTROL_TOKEN=<WERVT_DEPLOY_TOKEN>
wervt access dashboard --invite --invite-by owners
```

`dashboard.wervt.example.com` now signs you in with a code by mail. Inviting people works the
same as on
[production](https://docs.lightdrop.cloud/self-hosting/production#first-start). From now on, sign the CLI in with
`wervt login --url https://api.wervt.example.com` and the dashboard's **Settings** page instead of
using the deploy token.

## Names and certificates

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Serves
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        wervt.example.com
      </code>
    </td>
    
    <td>
      The docs, or the <a href="#an-app-at-the-domain-itself">
        root app
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        api.
      </code>
    </td>
    
    <td>
      The control plane (CLI, dashboard)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        media.
      </code>
    </td>
    
    <td>
      Apps' files (Garage's S3 API)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id.
      </code>
    </td>
    
    <td>
      The workload identity issuer's <code>
        /.well-known/
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <app>.
      </code>
    </td>
    
    <td>
      The app
    </td>
  </tr>
</tbody>
</table>

Caddy gets a certificate for the fixed names when it starts, and one per app on its first request
(on-demand TLS). Before it requests one, it asks the control plane (`/v1/tls/ask`), which only
agrees for existing apps and verified custom domains, so nobody can make the server request
certificates for arbitrary names. The first request to a new app takes a few seconds longer.

### Custom domains

Set `WERVT_DOMAIN_TARGET` to a name that resolves to the server, for example
`domains.wervt.example.com`, and owners point their domains at it (`wervt domains`). Once the control
plane has verified a domain, Caddy gets its certificate on the first request.

## An app at the domain itself

To serve one of your apps at `wervt.example.com` instead of the docs, set in `.env`:

```bash
WERVT_ROOT_APP=shop
```

The docs then stay at `docs.wervt.example.com`. Deploy them with
`WERVT_DOCS_HOST=docs.wervt.example.com` next to `WERVT_DOMAIN`, so their links and `llms.txt`
name that host.

The domain is then the app's address, like a primary [custom domain](https://docs.lightdrop.cloud/guides/custom-domains):
`shop.wervt.example.com` and `www.wervt.example.com` redirect there, and the app's
`WERVT_APP_URL`, its tokens and the dashboard use it. Sign-in works as on any subdomain, since
they share the session cookie. Caddy gets the domain's certificate once the app is deployed.

## Behind a Cloudflare Tunnel

With a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/),
Cloudflare holds the certificates and the server needs no open ports.
`deploy/compose.tunnel.yaml` replaces `compose.caddy.yaml`: the same stack, with Caddy speaking
plain HTTP on `127.0.0.1:80`, so it can't redirect in a loop. In `.env`:

```bash
COMPOSE_PROFILES=cloudflared
WERVT_TUNNEL_TOKEN=<token of the tunnel>
```

```bash
docker compose -f compose.yaml -f compose.tunnel.yaml up -d --build
```

Leave `WERVT_ACME_EMAIL` as it is in `.env`; nothing uses it here, but Compose requires it. If you
run `cloudflared` yourself, on the host, leave out both settings.

In the tunnel's settings, add two public hostnames, `wervt.example.com` and `*.wervt.example.com`,
both with the service `http://wervt-caddy:80` (with `cloudflared` on the host, `http://localhost:80`).
Then check three things in Cloudflare:

- DNS has a proxied CNAME for both names, pointing at `<tunnel id>.cfargotunnel.com`. They replace
the A and AAAA records from [Requirements](#requirements).
- **Always Use HTTPS** is on, since Caddy leaves redirecting to Cloudflare.
- Uploads and files fit its limits: `media.` goes through Cloudflare too, which caps request bodies
(100 MB on the Free plan) and doesn't allow serving mostly video or large files on it.

Everything else works as on a server with open ports, the [root app](#an-app-at-the-domain-itself)
included. A [custom domain](#custom-domains) has to be in your Cloudflare account and needs a public
hostname of its own in the tunnel. For deploying and [updates](#updates), use
`compose.tunnel.yaml` in place of `compose.caddy.yaml`.

## Updates

```bash
git pull
docker compose -f compose.yaml -f compose.caddy.yaml up -d --build
```

Compose only recreates what changed. Apps don't need a redeploy.

An install whose auth app ran without a secret, from before the sign-in derived its own, gets one
with `pnpm app:deploy auth`. Everyone signs in again once, and MCP clients renew their tokens on
their own: the sign-in makes a new signing key, since the old one was encrypted with a publicly
known default.

## Another proxy or database

Without the overlay, `compose.yaml` runs behind any proxy and with any Postgres 18 that has
`wal_level = logical`:

- `WERVT_PG_HOST` is the database's `host:port` as the stack reaches it, `WERVT_PG_PASSWORD` the
password of its `postgres` superuser. The database `wervt` has to exist.
- The proxy forwards `api.` to `wervt-control:9100`, `media.` to `wervt-garage:3900`,
`id.<domain>/.well-known/` to `wervt-control:9100` and every other name, the domain itself
included, to `wervt-runtime:9000`, without buffering responses (live shapes and SSE stream), and sets
`X-Forwarded-Proto` and `X-Forwarded-For`.
- Keep the runtime off networks with other services: app code runs in it.


## Sitemap

See the full [sitemap](https://docs.lightdrop.cloud/sitemap.md) for all pages.
