docs(self-host): overhaul deploy section for the full-featured platform era#180
Conversation
…rm era - agent-runtime: rewritten from a 778-line inline deployment guide (stale compose/env, retired s3./git. domains, tagged agent image) into an architecture introduction; all deployable assets now link to teableio/teable-deployment as the single source of truth - new choose page: Teable Cloud vs standalone vs full-featured, first page of Quick Start (en+zh) - upgrade: rewritten for the real versioning model (date release tags, latest/beta channels, pinning; platform calver releases + CHANGELOG + doctor for full-featured); drops teable-ee image references and 0.5.0-alpha era examples - k8s page (raw standalone manifests) removed; Kubernetes path now goes through the full-featured Helm chart; redirects added - one-key page shelved (templates currently non-functional); redirect to choose - aws: removed internal-only SANDBOX_URL:7070 disclosure (en+zh) - retargeted all inbound links (docker, production-overview, activate, azure, sandbox-agent, ai-setting) and refreshed stale early-stage wording - production-overview: clarified scope (standalone scaling) with pointer to the full-featured platform Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ed vars - clarify scope: these are the Teable app's own variables; runtime plane services are configured by the teable-deployment assets - new group: AI & App Builder (SANDBOX_PROVIDER, TEABLE_INFRA_API_URL/KEY/ BUCKET, agent image prefix semantics, runtime type, server proxy, APP_DEPLOY_PROVIDER, sandbox JWT secret and per-sandbox resources) with a note that full-featured deployments set them automatically - new security rows: storage/access-token encryption key+IV pairs, whose defaults are public constants in source and must be regenerated per host - removed vars no longer read anywhere: NEXT_ENV_IMAGES_ALL_REMOTE, MAX_SPACE_OWNER_COUNT - en + zh in sync Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… keep URLs viewable Per review alignment: - deprecated-banner pattern instead of deletion: content stays reachable at its old URL with a banner pointing to Choose Your Path; pages leave the navigation (k8s and one-key restored from deletion to follow the same pattern; their redirects dropped) - shelved: production-overview, aws, azure, gcp (Production Deployment group removed), storage (bucket layout is now managed by the deployment assets; full-featured uses three buckets), database-connection, k8s, one-key - navigation: Quick Start = choose -> docker -> agent-runtime (architecture) - docker page: retargeted/removed links into shelved pages - en + zh in sync Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2bca021b61
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "en/deploy/choose", | ||
| "en/deploy/docker", | ||
| "en/deploy/one-key" | ||
| "en/deploy/agent-runtime" |
There was a problem hiding this comment.
When users follow existing bookmarks or search results for the removed deployment pages, this navigation change does not redirect them to the new guidance; the existing redirects array still only covers /about, while /en/deploy/k8s, /en/deploy/one-key, and the corresponding zh paths were just removed from nav. Depending on Mintlify's handling of unlisted files, those direct URLs either keep serving the obsolete instructions/buttons or become 404s instead of landing on choose/agent-runtime, so please add explicit redirects when retiring these paths.
Useful? React with 👍 / 👎.
| Each name is only a default; every hostname can be overridden individually | ||
| (see the values example in the deployment repository). |
There was a problem hiding this comment.
For Docker full-featured installs, this overstates what the linked deployment assets support: docker/all-in-one/.env.server.example only lets users relocate the console/site hosts and explicitly derives the *.app and *.sandbox wildcards from BASE_DOMAIN. Users following the Docker card on this page may plan DNS/TLS around independently overridden app or sandbox hostnames that the Docker path cannot actually consume, so please scope this claim to Helm or call out the Docker limitation.
Useful? React with 👍 / 👎.
| These are the **Teable app's own** environment variables. The services of the | ||
| full-featured runtime plane (sandbox engine, Infra Service, git registry, …) | ||
| are configured separately by the deployment assets in | ||
| [teableio/teable-deployment](https://github.com/teableio/teable-deployment) — | ||
| see [Agent Runtime Architecture](/en/deploy/agent-runtime). |
There was a problem hiding this comment.
Because this page now presents itself as the Teable app environment-variable reference, dropping NEXT_ENV_IMAGES_ALL_REMOTE hides a setting that the Docker Deployment guide still sets in its recommended compose file. Users on managed/Kubernetes-style deployments who don't copy that compose snippet won't know to enable remote image loading for self-hosted image previews, so either restore the row here or remove the setting from the Docker guide if it is truly obsolete.
Useful? React with 👍 / 👎.
| <Tip> | ||
| **Self-hosted only**: Available for all versions with unlimited connections. For setup, see [Database Connection](/en/deploy/database-connection). | ||
| **Self-hosted only**: Available for all versions with unlimited connections. | ||
| </Tip> |
There was a problem hiding this comment.
For self-hosted instances that have not configured PUBLIC_DATABASE_PROXY, the database connection flow still needs deployment-side setup, but this commit removed the only direct link from the SQL Query page while the setup page is also removed from navigation. Users landing here can reach the UI steps and fail connection creation without any clue that an env var is missing, so please keep the setup link or inline the PUBLIC_DATABASE_PROXY requirement here.
Useful? React with 👍 / 👎.
| After deploying, connect your Teable app to the runtime plane with | ||
| `TEABLE_INFRA_API_URL` / `TEABLE_INFRA_API_KEY` (the deployment guides cover | ||
| this), then configure limits in |
There was a problem hiding this comment.
For runtime-only installs or migrations from an existing standalone app, configuring only TEABLE_INFRA_API_URL and TEABLE_INFRA_API_KEY is not enough: the linked migration guide also requires provider/runtime settings such as SANDBOX_PROVIDER=opensandbox, SANDBOX_OPENSANDBOX_RUNTIME=docker, APP_DEPLOY_PROVIDER=docker-runtime, SANDBOX_JWT_SECRET, TEABLE_INFRA_BUCKET, and SANDBOX_OPENSANDBOX_IMAGE. Users following this end note can restart with valid Infra credentials but still have missing AI/App Builder wiring, so please point to the full variable table or mention that more app env vars are required.
Useful? React with 👍 / 👎.
Remove the eight deprecated pages outright (production-overview, k8s, aws, azure, gcp, one-key, storage, database-connection) plus their orphaned screenshots. Deployment-path URLs redirect to Choose Your Path; the two configuration pages (storage, database-connection) redirect to Environment Variables, which now documents PUBLIC_DATABASE_PROXY so the external database connection feature keeps its setup reference. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d7e5c3e22e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "source": "/en/deploy/storage", | ||
| "destination": "/en/deploy/env" |
There was a problem hiding this comment.
When users follow the retired /en/deploy/storage URL, this now lands on the environment-variable table, but that page only lists storage variables and no longer includes the public bucket public-read/CORS and bucket-policy guidance that the deleted storage guide provided. S3/MinIO users can therefore set the variables successfully while missing the required bucket access rules, which causes browser asset access or uploads to fail; please redirect to a page/section that still contains the bucket setup requirements or restore that guidance here.
Useful? React with 👍 / 👎.
| services: | ||
| teable: | ||
| image: registry.cn-shenzhen.aliyuncs.com/teable/teable:0.5.0-alpha-1.x.x-build.xxx # 指定版本号 | ||
| image: ghcr.io/teableio/teable:release.2026-07-14T12-24-39Z.2228 |
There was a problem hiding this comment.
For users following the Chinese self-hosted path from the Docker guide, the installed image is registry.cn-shenzhen.aliyuncs.com/teable/teable:latest, so this pinned-version example switches them back to GHCR during upgrade. In China or other networks where GHCR is blocked/slow, docker compose pull will fail even though the original install worked with the mirror; please use the Aliyun image prefix here or explicitly show the mirror equivalent for pinned release tags.
Useful? React with 👍 / 👎.
| "source": "/en/deploy/production-overview", | ||
| "destination": "/en/deploy/choose" |
There was a problem hiding this comment.
When users with existing bookmarks to the production overview land here, they now get only the path-selection matrix, while the Docker guide still scopes standalone Docker to small teams/evaluation and no replacement page carries the deleted overview's production sizing, HA, Redis, and storage guidance. This leaves 50+ user/basic self-host deployments without an actionable production path after the redirect; please redirect to documentation that retains those requirements or keep a production overview page.
Useful? React with 👍 / 👎.
Rename Agent Runtime Architecture to Architecture (/deploy/architecture, old URL redirected) and fold the Teable app, PostgreSQL, Redis, and the three-bucket object storage into one integrated architecture page; the AI-less standalone becomes the secondary path. Hide Docker Deployment from the navigation (page stays linked from Choose Your Path), put the full-featured column before standalone in the comparison table, and add an agent-driven deployment guide (domain + DNS token + target access, with CN-localized providers on the zh page). Drop the env-page intro tip and the outdated 'early stage' caveat in app-builder. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Same treatment as Docker Deployment: the page stays viewable at its URL but no longer appears in the Configuration group. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Standalone-era guide: the full-featured platform ships its own entry with automatic TLS. The page stays viewable and remains linked from the (also hidden) standalone Docker guide, where it is still relevant. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Docker all-in-one local mode needs neither a domain nor a DNS token — everything runs on *.localhost with just Docker installed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The 'How it fits together' section was foregrounding git/artifact plumbing. Rewrite it around what actually consumes the machine: sandboxes (one per AI session, bursty — size by peak concurrent sessions) and deployed apps (long-lived containers that accumulate). Git registry and object storage become dotted supporting edges; deployed apps get their own node. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Title-only rename (slug and redirects unchanged); update the two inbound link texts in the Docker guide. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Drop the standalone-first framing. Routine updates: read the changelog, then move the Teable image to any release dated at or after the entry — Docker can ride latest, Kubernetes pins and bumps deliberately. Best practice: use VERSIONS.md as the upgrade sheet each round — newest platform release plus the concrete tag latest corresponds to, verified by the doctor. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b3b68a8008
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 2. **A DNS token** — an API token for the platform hosting your DNS | ||
| (Cloudflare, Route 53, …), so DNS records and TLS certificates can be set | ||
| up automatically. Scope it to that one zone. |
There was a problem hiding this comment.
When the chosen target is the Docker all-in-one server path below, this currently overstates provider support: the default deployment assets build Caddy with only the Cloudflare DNS plugin and Caddyfile.server reads CLOUDFLARE_API_TOKEN, while switching to Route 53 requires editing the Caddy build/config. Users handing an agent a Route 53 token for the advertised Docker server path will not get automatic wildcard TLS from the shipped assets, so please either limit this example to Cloudflare for Docker or call out the required customization.
Useful? React with 👍 / 👎.
| | TEABLE_INFRA_API_URL | Runtime plane entry URL — must be the public entry (it routes `/v1` to the sandbox engine), not an internal service address | - | - | https://infra.teable.example.com | | ||
| | TEABLE_INFRA_API_KEY | API key shared with the runtime plane | - | - | your-infra-api-key | | ||
| | TEABLE_INFRA_BUCKET | Bucket for the AI workspace data plane | teable-agent | - | teable-agent | | ||
| | SANDBOX_OPENSANDBOX_IMAGE | Sandbox agent image **prefix without a tag** — Teable appends its own release tag so the agent always matches the app version. China deployments use the Aliyun mirror prefix | - | - | ghcr.io/teableio/teable-sandbox-agent | |
There was a problem hiding this comment.
For China deployments, this row says to use the Aliyun mirror but the only example remains the GHCR prefix; users who copy this environment reference will leave sandbox preheating/session pulls pointed at GHCR, which is exactly the path the mirror is meant to avoid. The deployment repo documents the matching prefix as registry.cn-shenzhen.aliyuncs.com/teable/teable-sandbox-agent, so please include that value here (and in the zh table) or add a China-specific example.
Useful? React with 👍 / 👎.
| 2. **A DNS token** — an API token for the platform hosting your DNS | ||
| (Cloudflare, Route 53, …), so DNS records and TLS certificates can be set | ||
| up automatically. Scope it to that one zone. |
There was a problem hiding this comment.
When the chosen target is the Docker all-in-one server path below, this currently overstates provider support: the default deployment assets build Caddy with only the Cloudflare DNS plugin and Caddyfile.server reads CLODFLARE_API_TOKEN, while switching to Route 53 requires editing the Caddy build/config. Users handing an agent a Route 53 token for the advertised Docker server path will not get automatic wildcard TLS from the shipped assets, so please either limit this example to Cloudflare for Docker or call out the required customization.
Useful? React with 👍 / 👎.
| <Card title="Kubernetes (Helm)" icon="dharmachakra" href="https://github.com/teableio/teable-deployment/blob/main/helm/README.md"> | ||
| One umbrella chart on an existing cluster; only `global.baseDomain` is required. | ||
| </Card> |
There was a problem hiding this comment.
For a new or minimal Kubernetes cluster, following this card with only global.baseDomain is not enough to get a working install: the linked Helm README still lists an ingress-nginx controller, cert-manager or precreated TLS secrets, a default StorageClass, and DNS records pointing at the ingress as prerequisites. Users coming from the retired K8s/cloud pages can skip those required add-ons and hit a failed install, so please mention the cluster prerequisites here or clarify that this means only the required Helm value after prerequisites are in place.
Useful? React with 👍 / 👎.
1 participant
Realigns the self-hosted docs with current reality: the public teableio/teable-deployment repository, platform releases, and the "Teable is an AI product" narrative. Page-by-page summary for review:
Resulting structure
The Self-hosted tab now contains: License (activate) · Quick Start (Deployment, Architecture) · Admin Panel · Configuration (env, email, oidc) · Telemetry · Maintenance (upgrade).
Rewritten
agent-runtime(a 778-line legacy tutorial with an inlined outdated compose/env, retireds3./git.hostnames, and old tagged-agent semantics; old URL redirects). Now an architecture overview telling one integrated story: the app, PostgreSQL, Redis, and three-bucket object storage together with the runtime plane; a workload-centric diagram and narrative (sandboxes = bursty per-session load — size by peak concurrent AI sessions; deployed apps = accumulating long-lived containers; git registry/object storage as supporting plumbing); the four-DNS-record domain model, platform releases and the doctor. All deployable assets link to teable-deployment — zero asset copies in docs.latest; Kubernetes pins and bumps deliberately). Best practice = treatVERSIONS.mdas the upgrade sheet each round: newest platform release + the concrete taglatestcorresponds to, verified by the doctor. Removed teable-ee image references and 0.5.0-alpha era examples.PUBLIC_DATABASE_PROXY(previously documented only on the deleted database-connection page). Intro tips removed.Deleted, with redirects
Eight legacy pages hard-deleted in both languages; their URLs redirect:
/deploy/choose/deploy/envContext: the k8s page was bare standalone manifests (the K8s path is now the full-featured Helm chart); the one-key templates are currently non-functional; the aws page had disclosed the internal
SANDBOX_URL:7070shape — gone with the page.Hidden from navigation (pages stay viewable at their URLs)
Tone & link sweep
All inbound links updated (docker / activate / sandbox-agent / ai-setting / sql-query); "deployment is early stage, contact support" era copy removed from app-builder.
🤖 Generated with Claude Code