@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/deployment/docker.md

@@ -0,0 +1,149 @@
+# Deploy with Docker
+
+### Building a Lowdefy app image
+
+A Lowdefy app can be self-hosted or deployed to many hosting providers using Docker containers. The app needs to build into a Docker image, containing all the app configuration and the [Hono](https://hono.dev) server with its built client assets.
+
+The `init-docker` CLI command can be used to create a Dockerfile, or the following Dockerfile can be used:
+
+```text
+FROM node:22-bookworm AS builder
+
+WORKDIR /lowdefy
+
+COPY . .
+
+# Enable pnpm using corepack
+RUN corepack enable
+
+# Build lowdefy app (Lowdefy config build + Vite client build)
+RUN pnpx lowdefy@6 build --log-level=debug
+
+FROM node:22-bookworm-slim AS runner
+
+ENV NODE_ENV=production
+
+WORKDIR /lowdefy
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 lowdefy
+
+COPY --from=builder --chown=lowdefy:nodejs /lowdefy/.lowdefy/server ./
+
+USER lowdefy
+
+EXPOSE 3000
+
+ENV PORT=3000
+
+CMD ["node", "src/index.js"]
+```
+
+with a `.dockerignore` file:
+
+```
+Dockerfile
+.dockerignore
+.env
+node_modules
+README.md
+.lowdefy
+dist
+.git
+```
+
+An image can be built by running:
+
+```
+docker build -t <tag> .
+```
+
+The container can be run by:
+
+```
+docker run -p 3000:3000 <tag>
+```
+
+Docker compose can also be used. Add a `docker-compose.yaml` file:
+
+```yaml
+version: "3.9"
+services:
+  lowdefy:
+    build: .
+    ports:
+      - "3000:3000"
+```
+
+To build the image, run:
+
+```
+docker compose build
+```
+
+To run the app, run:
+
+```
+docker compose up
+```
+
+### Secrets and Environment Variables
+
+When running you app in production we recommend using your hosting provider's preferred method for setting environment variables and secrets. This can often be configured using their admin interface, and secrets are usually encrypted.
+
+When running locally, you can use the `--env-file` Docker CLI option to load a `.env` file into your container:
+```
+docker run -p 3000:3000 --env-file ./.env <tag>
+```
+
+If using Docker compose:
+
+```yaml
+version: "3.9"
+services:
+  lowdefy:
+    build: .
+    ports:
+      - "3000:3000"
+    env_file: ./.env # Path to env file
+```
+
+### Config files or plugins outside the config directory
+
+For security reasons, only files inside the directory of the Dockerfile can be accessed by the Dockerfile during the build process.
+
+Sometimes files outside of the config directory need to be accessed by the Lowdefy app during build - for example using the `_ref` operator on shared config files, or when using pnpm local workspace plugins. In this case, the Dockerfile needs to be moved to a directory that includes all the files that need to be accessed and the Dockerfile needs to be modified to take this into account.
+
+###### In pnpm monorepo with plugins
+
+```text
+FROM node:22-bookworm AS builder
+
+WORKDIR /lowdefy
+
+COPY . .
+
+# Enable pnpm using corepack
+RUN corepack enable
+
+# TODO: Change config-directory (./app) as appropriate here
+RUN pnpx lowdefy@6 build --config-directory ./app --log-level=debug
+
+FROM node:22-bookworm-slim AS runner
+
+ENV NODE_ENV=production
+
+WORKDIR /lowdefy
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 lowdefy
+
+# TODO: Change from-directory (/lowdefy/app/.lowdefy/server) as appropriate here
+COPY --from=builder --chown=lowdefy:nodejs /lowdefy/app/.lowdefy/server ./
+
+EXPOSE 3000
+
+ENV PORT 3000
+
+CMD ["node", "server.js"]
+```

package/content/deployment/node-server.md

@@ -0,0 +1,27 @@
+# Deploy with Node.js
+
+### Run with Lowdefy CLI:
+
+To test the production server, it can be run locally. In order to do this, first create the production build output using:
+
+`pnpx lowdefy@6 build`
+
+The production server can then be run using:
+
+`pnpx lowdefy@6 start`
+
+### Deploying the built server:
+
+`pnpx lowdefy@6 build` writes a complete server into `<config-directory>/.lowdefy/server` — the Hono server (`src/`), the built client assets (`dist/client/`), the app build artifacts (`build/`), and `public/`.
+
+Copy that folder (with its `node_modules`, or run `pnpm install --prod` inside it on the target machine) to your server and run:
+
+```node src/index.js```
+
+from inside the folder, or `pnpm start`. The server listens on `PORT` (default 3000).
+
+Always run the build before restarting the server — the server reads the client asset manifest once at startup.
+
+### Alternative
+
+An alternative option would be to make use of [Docker](./docker) to deploy the app. Docker has a few advantages, including scalability, application portability, version control and deployment speed, amoung others.

package/content/deployment/vercel.md

@@ -0,0 +1,101 @@
+# Deploy with Vercel
+
+A Lowdefy app builds a [Hono](https://hono.dev) server serving a Vite-built React client. On Vercel it is deployed with the [Build Output API](https://vercel.com/docs/build-output-api) as **static assets on the CDN plus one Serverless Function** that runs the Hono app for every dynamic request (page rendering, `/api/*` requests, endpoints, cron, auth and agents).
+
+Run the `init-vercel` CLI command in your project to scaffold everything into a `deploy/` directory next to your `lowdefy.yaml`:
+
+```bash
+npx lowdefy@latest init-vercel
+```
+
+This creates:
+
+- `deploy/vercel.install.sh` — the install command; downloads the Lowdefy server into `deploy/` and builds the config artifacts (skipping the client build, which the build step runs).
+- `deploy/vercel.build.sh` — the build command; builds the Vite client, then runs `lowdefy vercel-output` to assemble the Vercel Build Output (`.vercel/output/`).
+- `deploy/vercel.json` — sets the build command. The deployment itself is described by the generated `.vercel/output/config.json`.
+- `deploy/README.md` — these instructions.
+
+All four files are safe to commit.
+
+###### Project settings
+
+In the Vercel project:
+
+- **Framework Preset:** `Other` (Lowdefy is not a Next.js app).
+- **Root Directory:** `<config-directory>/deploy`
+    - `<config-directory>` is the directory in which the `lowdefy.yaml` file is placed.
+    - Eg: if `lowdefy.yaml` is at the top level of the repository, set the root directory to `deploy`; if it is in `apps/app_name`, set it to `apps/app_name/deploy`.
+- **Install Command:** `bash vercel.install.sh`. Leave the **Build Command** to `vercel.json` (do not override it in the dashboard). There is no **Output Directory** setting — the build emits `.vercel/output`, which Vercel detects automatically.
+- Enable **"Include files outside the root directory in the Build Step"** — the Lowdefy config usually lives in the parent of `deploy/`.
+
+###### Public files
+
+Files in your app's `public/` directory (favicon, icons, images, `manifest.webmanifest`, etc.) are copied into `dist/client` by Vite during the build, placed in `.vercel/output/static`, and served by the Vercel CDN — no extra configuration needed.
+
+###### Secrets and environment variables
+
+Secrets can be set in the Environment Variables settings section by creating environment variables prefixed with `LOWDEFY_SECRET_`. Use `AUTH_SECRET` (and `AUTH_URL` for OAuth) for authentication. Different secrets can be set for production and preview deployments.
+
+###### Function settings
+
+The whole app runs as a single Serverless Function, so its settings are configured once, app-wide, in `lowdefy.yaml`:
+
+```yaml
+config:
+  vercel:
+    maxDuration: 300 # seconds, default 60
+    memory: 2048 # MB — omit to use the Vercel default
+```
+
+- **`maxDuration`** — the hard cap on function execution time, in seconds. Defaults to `60`. Your plan's limits apply; Vercel rejects an over-limit value at deploy time.
+- **`memory`** — function memory in MB. Omit to use the Vercel default.
+
+Each build writes these into the generated `.vercel/output/functions/api.func/.vc-config.json`. The output is regenerated on every deploy, so there is nothing to edit by hand — and because the deployment is prebuilt (Build Output API), `functions` settings in `vercel.json` or the dashboard's function defaults do not apply; `lowdefy.yaml` is the single source of truth.
+
+###### Scheduled endpoints (cron)
+
+An `Api` (or `InternalApi`) endpoint can declare `schedules` to run its routine on a timer. Each build turns those schedules into Vercel cron jobs in `.vercel/output/config.json`, so nothing is committed by hand and the crons stay in sync with your config:
+
+```yaml
+id: purge-stale-conversations
+type: Api
+schedules:
+  - cron: '0 6 * * *'
+    payload: { mode: full }
+  - cron: '*/15 * * * *'
+    payload: { mode: incremental }
+routine:
+  - id: purge
+    type: MongoDBDeleteMany
+    connectionId: conversations
+    properties:
+      filter: { updatedAt: { $lt: { _payload: cutoff } } }
+```
+
+Each schedule becomes a cron job pointing at `/api/cron/<endpointId>`. When it fires, Vercel makes a GET request to that path and the Hono app runs the endpoint's routine with the matching schedule's `payload` (available as `_payload`).
+
+- **Secure it:** add an Environment Variable named exactly `CRON_SECRET` (a random string of 16+ characters). Vercel automatically sends it as `Authorization: Bearer <CRON_SECRET>`; the `/api/cron/*` route rejects requests whose header does not match, and returns `401` if `CRON_SECRET` is unset (fail closed).
+- **System context:** scheduled runs have no logged-in user, so `_user` is `undefined`. The routine still has full access to connections, requests, operators and secrets — write scheduled routines so they do not depend on a user.
+- **UTC only.** Cron expressions have 5 fields (`minute hour day-of-month month day-of-week`); named values like `MON`/`JAN` are not supported, and day-of-month and day-of-week are mutually exclusive.
+- **Plan limits:** Vercel **Hobby** only allows daily crons (a sub-daily expression fails the deployment); **Pro**/**Enterprise** allow per-minute. Up to 100 cron jobs per project.
+- **Idempotency:** Vercel does not retry failed runs and delivery is best-effort (a run can be missed or delivered more than once). Design scheduled routines to be idempotent.
+
+###### Background work: async endpoints and detached calls
+
+Two [API endpoint](/api) controls exist for work that should not hold up a response — they behave differently on Vercel:
+
+- **`async: true` endpoints** respond `{ accepted: true }` immediately and run the routine in the background. On Vercel the invocation is kept alive via the platform request context (Fluid compute) until the routine settles — but it is still the *same* invocation, so the background work remains bounded by `maxDuration`. Raise `config.vercel.maxDuration` to cover your longest async routine.
+- **`detached: true` on `CallApi` steps** fire-and-forget the target endpoint through a `POST` to the deployment's own `/api/detached/<endpointId>` route, so the target runs in its **own** invocation with a fresh `maxDuration` budget. The route is secured by `CRON_SECRET` (same secret as cron, fail closed), and detached steps fail with a config error if it is not set. Delivery is at-most-once with no retry; targets run as system context (`_user` is `undefined`) and must be idempotent.
+
+See [Async Endpoints](/api) and [Detached Endpoint Calls](/api) in the API docs for full semantics.
+
+###### Cost protection
+
+Vercel Fluid bills by execution duration, so a request that hangs (a stuck database, SMTP or external API call) is a real cost risk. Two guardrails apply:
+
+- **`config.requestTimeout`** (in `lowdefy.yaml`, default `30000` ms) — the server returns a timeout instead of letting a request run on. Set to `0` to disable. Agent streaming routes are exempt.
+- **`config.vercel.maxDuration`** (default `60`) — a hard platform cap; Vercel stops the function at this many seconds. See Function settings above.
+
+> The function runs on Vercel's Node.js runtime. Streaming agent responses (`/api/agent/*`) are exempt from `config.requestTimeout` and are bounded only by `maxDuration` — for heavy streaming or agent workloads, a long-lived Node host (Docker, Fly.io, Railway, Render) may suit better.
+
+All other Vercel configuration like domain names, preview deploy branches, serverless regions and redirects can be configured as desired.