@nocobase/plugin-ai 2.1.0-beta.46 → 2.1.0-beta.48

package/dist/ai/docs/nocobase/quickstart/production/index.md

@@ -1,163 +1,169 @@
 ---
 title: "Production Deployment"
-description: "Deploy NocoBase in production with two final steps: enable app autostart and configure a reverse proxy."
-keywords: "NocoBase,production deployment,nb app autostart,nb env proxy,Nginx,Caddy"
+description: "Finish NocoBase production deployment quickly: configure app auto-start first, then configure a reverse proxy."
+keywords: "NocoBase,production deployment,nb app autostart,nb proxy nginx,nb proxy caddy,Nginx,Caddy"
 ---
 
 # Production Deployment
 
-If your NocoBase app is already running correctly on the server, production rollout usually only needs two more steps:
+If your NocoBase app can already run normally on the server, production rollout usually only needs two more things:
 
-1. Make sure the app starts automatically after the machine restarts
-2. Put a reverse proxy in front of the app for stable external access
+1. make sure the app can recover automatically after the machine restarts
+2. add a reverse-proxy entrypoint so the app can be accessed from outside reliably
 
-In the NocoBase CLI, the main commands are:
+In NocoBase CLI, the main command groups are:
 
 - `nb app autostart`
-- `nb env proxy`
+- `nb proxy`
 
-This page gives the overall path first. For Nginx or Caddy details, continue to the corresponding subpages.
+This page explains the overall path first. For Nginx or Caddy details, continue to the provider-specific pages.
 
-## Step 1: Enable App Autostart
+## Step 1: configure app auto-start
 
-In production, the first priority is not the domain name. The first priority is making sure the service can recover reliably after a reboot, container recreation, or routine maintenance.
+In production, the first priority is not the domain name. It is making sure the service itself can recover reliably. Otherwise, after a machine restart, container recreation, or routine operations work, the app may not come back automatically.
 
-In the CLI, `nb app autostart` is a command group. The most commonly used commands are:
+The most common `nb app autostart` subcommands are:
 
 - `nb app autostart enable`
 - `nb app autostart list`
 - `nb app autostart run`
 
-Enable autostart for the current env:
+Enable auto-start for the current env:
 
 ```bash
 nb app autostart enable
 ```
 
-If you want to target a different env explicitly:
+If the target is not the current env, specify it explicitly:
 
 ```bash
 nb app autostart enable --env app1 --yes
 ```
 
-Then check which envs are marked for autostart:
+Check which envs are marked for auto-start:
 
 ```bash
 nb app autostart list
 ```
 
-After the system boots, run the following command to start every env that has autostart enabled:
+After the system boots, start all enabled envs with:
 
 ```bash
 nb app autostart run
 ```
 
-If you want the underlying startup output for troubleshooting:
+If you want detailed startup output while debugging:
 
 ```bash
 nb app autostart run --verbose
 ```
 
-:::tip What this actually does
+:::tip What this step actually does
 
-`nb app autostart enable` marks a CLI-managed env as allowed to start automatically.  
-`nb app autostart run` is the command that actually starts all envs that were marked for autostart.
+`nb app autostart enable` marks a CLI-managed env as allowed to start automatically. `nb app autostart run` actually starts all envs that have auto-start enabled.
 
-In other words, in a real production setup you usually still need to wire `nb app autostart run` into your own system startup flow, such as `systemd`, a container platform startup script, or another host-level boot mechanism you already use.
+In production, you usually still need to connect `nb app autostart run` to your own system startup flow, such as `systemd`, a container platform startup script, or another host-level auto-start mechanism that you already use.
 
 :::
 
-### Scope
+### Applicability
 
-`nb app autostart` only applies to envs with a CLI-managed runtime on the current machine:
+`nb app autostart` only works for envs with a CLI-managed runtime:
 
 - `local`
 - `docker`
 
-If the env is only a remote API connection, or the app is not managed locally by the CLI on this machine, these commands are not the right tool for autostart.
+If an env is only a remote API connection, or the app is not managed locally by the CLI on the current machine, this command group is not the right way to handle auto-start.
 
-## Step 2: Configure a Reverse Proxy
+## Step 2: configure the reverse proxy
 
-Once the app can recover automatically, the next step is to handle the external entry point. In production, the reverse proxy usually takes care of:
+After the app can recover automatically, handle the external entrypoint. In production, the reverse proxy usually takes care of:
 
-- binding the domain name or public port
-- forwarding HTTP and WebSocket traffic to NocoBase
+- binding the domain name or entry port
+- forwarding HTTP and WebSocket requests to NocoBase
 - handling HTTPS, certificates, caching, or access control
 
-In the NocoBase CLI, the recommended entry points are:
+The recommended CLI entrypoints are:
 
-- `nb env proxy nginx`
-- `nb env proxy caddy`
+- `nb proxy nginx`
+- `nb proxy caddy`
 
-### Default Approach
+### Default workflow
 
-If your app is already saved as a CLI env and is a `local` or `docker` env, letting the CLI generate the proxy config is usually enough:
+If the app has already been saved as a CLI env and that env is `local` or `docker`, the usual path is to let the CLI generate the config directly:
 
 ```bash
-nb env proxy nginx --env app1 --host app.example.com
-nb env proxy caddy --env app1 --host app.example.com
+nb proxy nginx use docker
+nb proxy nginx generate --env app1 --host app.example.com
+
+nb proxy caddy use local
+nb proxy caddy generate --env app1 --host app.example.com
 ```
 
-If the current env is already the target env, you can omit `--env`:
+Then start the chosen provider:
 
 ```bash
-nb env proxy nginx --host app.example.com
+nb proxy nginx start
+nb proxy caddy start
 ```
 
-The CLI helps cover details that are easy to miss in handwritten configs, such as:
+The CLI also helps with details that are easy to miss in handwritten configs, such as:
 
 - WebSocket forwarding
-- entry and static asset paths for subpath deployments
+- entry and asset URLs under subpaths
 - SPA fallback pages
-- provider shared config files
-
-### When To Choose Nginx Or Caddy
+- provider-level shared config files
 
-You can usually decide like this:
+### When to choose Nginx or Caddy
 
-| Scenario | Recommended |
+| Scenario | Recommendation |
 | --- | --- |
-| You already use Nginx for sites, caching, certificates, or access control | [Nginx](./reverse-proxy/nginx.md) |
-| You already have a domain and want HTTPS working quickly with less TLS maintenance | [Caddy](./reverse-proxy/caddy.md) |
-| You want the overall explanation of this command group first | [Production Reverse Proxy](./reverse-proxy/index.md) |
+| You already use Nginx to manage sites, caching, certificates, or access control | [Nginx](./reverse-proxy/nginx.md) |
+| You already have a domain and want HTTPS up quickly with fewer TLS details to maintain | [Caddy](./reverse-proxy/caddy.md) |
+| You want the overall introduction first | [Reverse Proxy in Production](./reverse-proxy/index.md) |
 
-If you change env settings that affect the proxy result, such as `app-port` or `app-public-path`, remember to rerun the corresponding proxy subcommand.
+If you later change env settings such as `app-port` or `app-public-path` that affect proxy behavior, rerun the matching proxy subcommand.
 
-## Recommended Rollout Path
+## Default rollout path
 
-If you want the simplest production path, this order usually works well:
+For the simplest production rollout, this sequence is usually enough:
 
-1. Make sure the app can already start correctly on the server itself
-2. Run `nb app autostart enable`
-3. Add `nb app autostart run` to your system startup process
-4. Choose Nginx or Caddy and run the matching `nb env proxy` subcommand
-5. Verify external access through the final domain or public entry address
+1. confirm the app can already start normally on the server itself
+2. run `nb app autostart enable`
+3. connect `nb app autostart run` to your system startup flow
+4. choose Nginx or Caddy and run the matching `nb proxy` subcommand
+5. verify external access through the domain name or entry address
 
-## Quick Links
+## Quick index
 
-| I want to... | Read this |
+| I want to... | Go here |
 | --- | --- |
-| Start with the overall reverse proxy explanation | [Production Reverse Proxy](./reverse-proxy/index.md) |
-| Keep using Nginx for the entry layer | [Nginx](./reverse-proxy/nginx.md) |
-| Use Caddy for a faster HTTPS setup | [Caddy](./reverse-proxy/caddy.md) |
-| Manage start, stop, logs, and upgrades | [Manage Apps](../operations/manage-app.md) |
-| Read the `nb env proxy` CLI reference | [`nb env proxy`](../../api/cli/env/proxy/index.md) |
+| Read the overall reverse-proxy introduction first | [Reverse Proxy in Production](./reverse-proxy/index.md) |
+| Keep using Nginx at the entry layer | [Nginx](./reverse-proxy/nginx.md) |
+| Use Caddy to get HTTPS faster | [Caddy](./reverse-proxy/caddy.md) |
+| View app start, stop, logs, and upgrade operations | [Manage the App](../operations/manage-app.md) |
+| Read the `nb proxy nginx` CLI reference | [`nb proxy nginx`](../../api/cli/proxy/nginx/index.md) |
+| Read the `nb proxy caddy` CLI reference | [`nb proxy caddy`](../../api/cli/proxy/caddy/index.md) |
 
-## Related Commands
+## Related commands
 
 ```bash
-# Enable autostart for one env
+# Enable auto-start for one env
 nb app autostart enable --env app1 --yes
 
-# List autostart status
+# Check auto-start state
 nb app autostart list
 
-# Start all envs with autostart enabled
+# Start all enabled envs
 nb app autostart run
 
-# Generate Nginx reverse proxy config
-nb env proxy nginx --env app1 --host app.example.com
+# Choose the Nginx runtime and generate config
+nb proxy nginx use docker
+nb proxy nginx generate --env app1 --host app.example.com
+nb proxy nginx start
 
-# Generate Caddy reverse proxy config
-nb env proxy caddy --env app1 --host app.example.com
+# Choose the Caddy runtime and generate config
+nb proxy caddy use local
+nb proxy caddy generate --env app1 --host app.example.com
+nb proxy caddy start
 ```

package/dist/ai/docs/nocobase/quickstart/production/reverse-proxy/caddy.md

@@ -1,158 +1,289 @@
-# Caddy
+---
+title: "Caddy"
+description: "Use nb proxy caddy to generate and manage Caddy reverse-proxy configuration for CLI-managed NocoBase envs."
+keywords: "NocoBase,nb proxy caddy,reverse proxy,Caddy,production"
+---
 
-If you already have a domain and want to get HTTPS running quickly, Caddy is usually the easiest choice. Compared with maintaining Nginx certificate config yourself, Caddy is more like the shortcut path for getting the entry layer online first.
+# Caddy
 
-The default recommendation is to run `nb env proxy caddy` directly.
+If you already have a domain and want to get HTTPS running quickly, `nb proxy caddy` is usually the simplest entry path.
 
-## When Caddy is usually the better fit
+Compared with maintaining certificate configuration in Nginx yourself, Caddy is more like the default shortcut for getting the entry layer online quickly.
 
-These cases usually favor Caddy first:
+## When Caddy is the better fit
 
-- You already have a domain and want HTTPS quickly
-- You do not want to maintain too many certificate and TLS details yourself
-- You only need a simple and stable entry layer
+In practice, Caddy is usually the better choice when:
 
-If you already use Nginx across the server to manage many sites, or you still need heavier caching, access control, and custom rules, [Nginx](./nginx.md) is usually the better fit.
+- you already have a domain and want to get HTTPS online quickly
+- you do not want to manage many certificate and TLS details yourself
+- you mainly want a simple and stable entry layer
 
-## Default path: let the CLI generate the Caddy config
+If you already use Nginx to manage many sites on the same server, or you still need heavier caching, access control, or custom rules, [Nginx](./nginx.md) is usually the better fit.
 
-If your app has already been saved as a CLI env and the env type is `local` or `docker`, the default recommendation is still to let the CLI generate the config. That way, routing details related to NocoBase paths, WebSocket handling, and subpaths stay managed by the CLI, and you only need to care about the site entry itself.
+## Recommended order: choose a driver, generate config, then start
 
-The most direct form is:
+For a CLI-managed env of type `local` or `docker`, the default order is:
 
 ```bash
-nb env proxy caddy --env demo --host demo.example.com
+nb proxy caddy use docker
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+nb proxy caddy start
 ```
 
-If you have already switched to the current env, you can also omit `--env`:
+Or with a local process:
 
 ```bash
-nb env proxy caddy --host demo.example.com
+nb proxy caddy use local
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+nb proxy caddy start
 ```
 
-If you also want to specify the entry port, add it at the same time:
+Common follow-up commands are:
 
 ```bash
-nb env proxy caddy --env demo --host demo.example.com --port 8080
+nb proxy caddy current
+nb proxy caddy status
+nb proxy caddy info
+nb proxy caddy reload
+nb proxy caddy restart
+nb proxy caddy stop
 ```
 
-`--host` is important here. Caddy decides whether to manage HTTPS based on the site address. In production, try to pass a domain that already resolves to the current server.
+In most cases:
 
-### Which files the CLI generates
+- `current` is the quickest way to confirm the active runtime driver
+- `status` shows whether Caddy is currently running normally
+- `info` shows the current config path, runtime root, and related runtime details
+- after regenerating config, `reload` is usually the first command to use
+- use `restart` when you need a full restart
 
-If you do not pass `--output`, the Caddy provider keeps three layers of files under `~/.nocobase/proxy/caddy/<env>/`:
+## What `generate` needs as input
 
-| File | Purpose |
-| --- | --- |
-| `generated.caddy` | The actual reverse-proxy config managed by the CLI and overwritten every time you run `nb env proxy caddy` |
-| `app.caddy` | Editable site entry file where you can add site-level config |
-| `~/.nocobase/proxy/caddy/nocobase.caddy` | Shared main config that imports every env `app.caddy` |
+The most common form is:
 
-Where:
+```bash
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+```
 
-- `generated.caddy` is only meant to be managed by the CLI and should not be edited manually
-- `app.caddy` is editable, but you should keep the generated import inserted by the CLI
-- `nocobase.caddy` is mainly used by `--install`
+If you also want to specify the entry port:
 
-:::warning Note
+```bash
+nb proxy caddy generate --env test2 --host c.local.nocobase.com --port 8080
+```
 
-If you need to add site-level Caddy config such as extra headers, authentication, rate limiting, or compression rules, edit `app.caddy`. `generated.caddy` will be overwritten the next time you run `nb env proxy caddy`.
+Where:
 
-:::
+- `--env`: which CLI env to generate config for
+- `--host`: the public domain name
+- `--port`: the proxy entry port
 
-### Install the shared config into Caddy and reload it
+For Caddy, `--host` matters especially because the site address strongly affects the HTTPS workflow. In production, it is usually best to pass a domain that already resolves to the current server.
 
-If you want the CLI to connect the shared config to the Caddy main config and immediately validate and reload Caddy, run:
+If the command says the env is missing `appPort`, save it first with:
 
 ```bash
-nb env proxy caddy --env demo --host demo.example.com --install --reload
+nb env update test2 --app-port 56575
 ```
 
-These flags are split like this:
+If you later change settings such as `app-port` or `app-public-path` that affect proxy behavior, rerun `generate`.
 
-- `--install` connects `~/.nocobase/proxy/caddy/nocobase.caddy` to the Caddy main config
-- `--reload` validates the config first and then reloads Caddy
+## Files maintained by the CLI
 
-If your Caddy executable is not on the default path, set the CLI config first:
+Using `test2` as an example, the Caddy workflow usually maintains:
 
-```bash
-nb config set bin.caddy /usr/bin/caddy
-```
+| Path | Purpose |
+| --- | --- |
+| `NB_CLI_ROOT/.nocobase/proxy/caddy/test2/app.caddy` | CLI-generated full site config |
+| `NB_CLI_ROOT/.nocobase/proxy/caddy/nocobase.caddy` | Provider-level Caddy entry file that imports all env `app.caddy` files |
+| `NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v1.html` | v1 SPA fallback page |
+| `NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v2.html` | v2 SPA fallback page |
+| `NB_CLI_ROOT/test2/storage/dist-client` | Frontend build output for the current app |
+| `NB_CLI_ROOT/test2/storage/uploads` | Uploads directory for the current app |
 
-### When should you change `proxy.nb-cli-root`
+Where:
 
-Most setups do not need to change `proxy.nb-cli-root`. You usually need it only when Caddy runs in another container, mount root, or path view and cannot see the current user's `~/.nocobase` path.
+- files under `NB_CLI_ROOT/.nocobase/proxy/caddy/...` are CLI-managed proxy helper files
+- files under `NB_CLI_ROOT/test2/storage/...` belong to the application itself
+- `nocobase.caddy` is the provider-level entry file and usually does not need manual edits
+- `app.caddy` is the full site config for one env and is overwritten as a whole when you regenerate it
 
-For example, if Caddy sees that path as `/workspace/.nocobase/...` inside a container, set:
+:::warning Note
 
-```bash
-nb config set proxy.nb-cli-root /workspace
-nb env proxy caddy --env demo --install --reload
-```
+If you need site-level Caddy config such as extra headers, authentication, rate limiting, or compression policy, you can adjust `app.caddy` as the baseline. But remember that running `generate` again overwrites that file.
 
-If you only want to preview the generated result, use:
+:::
 
-```bash
-nb env proxy caddy --env demo --print
-```
+## Handwritten config: when you are not using the CLI
 
-If you want to write the generated route fragment to a custom file, use:
+If the app is not CLI-managed, or you intentionally want to maintain the full Caddy config yourself, you can still write it by hand.
 
-```bash
-nb env proxy caddy --env demo --output ./generated.caddy
-```
+For NocoBase, though, a production entry is usually more than a simple `reverse_proxy`. In addition to forwarding API requests to the backend app, a complete Caddy config usually needs to handle uploads, frontend assets, `.well-known` routes, WebSocket, and SPA fallback pages together.
+
+Using `test2` as the example, the key Caddy-related paths usually include:
 
-For the full parameter reference, see [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md).
+- SPA fallback directory: `NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public`
+- Frontend build output: `NB_CLI_ROOT/test2/storage/dist-client`
+- Uploads directory: `NB_CLI_ROOT/test2/storage/uploads`
 
-## Handwritten config: what to do without the CLI
+In other words, a handwritten config usually needs to cover at least these entry areas:
 
-If your app is not managed by the CLI, or you explicitly want to maintain the full `Caddyfile` yourself, start with this minimal version:
+- `v`: redirect `/v` to `/v/`
+- `uploads`: expose the uploads directory
+- `dist`: expose the frontend build output
+- `oauth well-known`: handle the OAuth discovery path
+- `openid well-known`: handle the OpenID discovery path
+- `api`: forward `/api/` requests to the backend app
+- `ws`: forward WebSocket requests to the backend app
+- `spa v2`: serve `/v/` with the v2 entry and fallback page
+- `spa v1`: serve `/` with the v1 entry and fallback page
+
+So a complete Caddy config is usually more than a generic example such as:
 
 ```text
 your-domain.com {
-  encode zstd gzip
   reverse_proxy 127.0.0.1:13000
 }
 ```
 
-Where:
+For a CLI-managed app such as `test2`, a more realistic deployment structure usually looks closer to this:
+
+```text
+c.local.nocobase.com {
+    encode zstd gzip
+
+    handle /v {
+        redir * /v/ 302
+    }
+
+    handle_path /storage/uploads/* {
+        root * NB_CLI_ROOT/test2/storage/uploads
+        header Cache-Control public
+        header X-Content-Type-Options nosniff
+        file_server
+    }
+
+    handle_path /dist/* {
+        root * NB_CLI_ROOT/test2/storage/dist-client
+        header Cache-Control public
+        file_server
+    }
+
+    @oauth path_regexp oauth ^/\\.well-known/oauth-authorization-server/(.+)$
+    handle @oauth {
+        rewrite * /{re.oauth.1}/.well-known/oauth-authorization-server
+        reverse_proxy host.docker.internal:56575
+    }
+
+    @openid path_regexp openid ^/\\.well-known/openid-configuration/(.+)$
+    handle @openid {
+        rewrite * /{re.openid.1}/.well-known/openid-configuration
+        reverse_proxy host.docker.internal:56575
+    }
+
+    handle /api/* {
+        reverse_proxy host.docker.internal:56575
+    }
+
+    handle /ws {
+        reverse_proxy host.docker.internal:56575
+    }
+
+    handle_path /v/* {
+        root * NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public
+        header Cache-Control "no-store, no-cache, must-revalidate"
+        header X-Robots-Tag "noindex, nofollow"
+        try_files {path} /index-v2.html
+        file_server
+    }
+
+    handle_path /* {
+        root * NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public
+        header Cache-Control "no-store, no-cache, must-revalidate"
+        header X-Robots-Tag "noindex, nofollow"
+        try_files {path} /index-v1.html
+        file_server
+    }
+}
+```
+
+Two details matter here:
 
-- Replace `your-domain.com` with your domain
-- Replace `127.0.0.1:13000` with the real address your NocoBase app listens on
+- files under `NB_CLI_ROOT/.nocobase/proxy/caddy/...` are CLI-managed SPA fallback files
+- files under `NB_CLI_ROOT/test2/storage/...` belong to the application's own build output and uploads
+
+If the app uses subpath deployment, or if frontend assets, uploads, and the entry layer do not share the same path view, handwritten config becomes easier to get wrong. In those cases, it is usually safer to generate the config first with:
+
+```bash
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+```
 
-If the domain already resolves to the current server correctly, Caddy usually handles HTTPS certificate issuance and renewal automatically.
+Then use the generated result as the baseline for manual adjustments.
 
-If you do not have a domain yet and only want to verify the reverse-proxy chain first, you can listen on a port:
+If you want the CLI to get the routes and paths working first, the generated structure usually looks like this:
 
 ```text
-:80 {
-  reverse_proxy 127.0.0.1:13000
-}
+NB_CLI_ROOT/.nocobase/proxy/caddy/nocobase.caddy
+NB_CLI_ROOT/.nocobase/proxy/caddy/test2/app.caddy
+NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v1.html
+NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v2.html
+NB_CLI_ROOT/test2/storage/dist-client
+NB_CLI_ROOT/test2/storage/uploads
 ```
 
-In production, though, it is still better to switch to a domain-based site address as soon as possible so Caddy can also take over HTTPS.
+Where:
+
+- `nocobase.caddy` imports all `*/app.caddy` files
+- `test2/app.caddy` is the full site config for env `test2`
+- `public/index-v1.html` and `public/index-v2.html` are CLI-generated SPA fallback pages
+
+The safer workflow is usually:
+
+1. let the CLI generate the Caddy config first
+2. use the generated output to confirm the routing structure and real filesystem paths
+3. then adjust it for your own domain, runtime driver, and mount layout
 
-If your app is not mounted at `/` but under a subpath, handwritten Caddy config also means you need to confirm application variables such as `APP_PUBLIC_PATH` and `WS_PATH`. In that case, it is usually easier to go back to `nb env proxy caddy` and let the CLI generate the config.
+That is usually less error-prone than writing the full config from scratch.
 
 ## Validate and reload the config
 
+If you write or adjust Caddy config manually, validate it first and then reload:
+
 ```bash
 caddy validate --config /etc/caddy/Caddyfile
 systemctl reload caddy
 ```
 
-If you do not manage Caddy with `systemd`, use your own startup and reload workflow.
+If you are not using `systemd` to manage Caddy, replace that with your own start and reload workflow.
+
+If you manage the entry layer through `nb proxy caddy`, the usual first choice is:
+
+```bash
+nb proxy caddy reload
+```
+
+If you want to inspect the current driver, main config-file path, runtime root, and container or local binary details, run:
+
+```bash
+nb proxy caddy info
+```
+
+If you only want to confirm whether Caddy is already running, run:
+
+```bash
+nb proxy caddy status
+```
 
-## Notes
+## Common notes
 
-- `nb env proxy caddy` only works for CLI-managed envs whose runtime is reachable from the current machine, which means `local` or `docker`
-- If the command says the env is missing `appPort`, run `nb env update <name> --app-port <port>` first
-- `--output` and `--print` are useful for preview or custom integration, but they do not additionally create `app.caddy` or the shared main config
-- If you already have a domain that resolves correctly to the server, Caddy is often the fastest way to get HTTPS working
+- `nb proxy caddy generate` only works for CLI-managed envs whose runtime is reachable from the current machine, which means `local` or `docker`
+- if the command says the env is missing `appPort`, run `nb env update <name> --app-port <port>` first
+- if you already have a domain that resolves correctly to the current server, Caddy is often the fastest way to get HTTPS
+- if you later change settings such as `app-port` or `app-public-path` that affect proxy behavior, rerun `generate`
 
 ## Related links
 
-- [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md)
-- [Install with CLI (Recommended)](../../installation/cli.md)
+- [Reverse Proxy in Production](./index.md)
+- [Nginx](./nginx.md)
+- [Install with the CLI](../../installation/cli.md)
 - [Install with Docker Compose](../../installation/docker-compose.md)
-- [App Environment Variables](../../installation/env.md)
+- [Environment variables](../../installation/env.md)