diff --git a/SELF_HOSTING.md b/SELF_HOSTING.md index cccad65c9..56308653b 100644 --- a/SELF_HOSTING.md +++ b/SELF_HOSTING.md @@ -861,10 +861,9 @@ Semantics: to normal manual management; it keeps all data and loses only the badge. - Renaming `name` inside a definition creates a new environment under the new name and orphans the old one. -- Definitions may reference repositories that are not linked to the - deployment yet (for example before the GitHub App is installed). The - environment is created anyway and repository mappings backfill on the next - startup after the repositories are linked. +- Repositories in a definition must already be linked to the deployment. + Definitions with missing repository mappings are skipped with a logged error + and retried on the next startup. - Invalid definitions are skipped with a logged error; they never prevent the API from starting or other definitions from applying. A missing or unreadable definitions directory is skipped the same way, so inline diff --git a/apps/docs/environments.mdx b/apps/docs/environments.mdx index e6272e8c5..a54211cc7 100644 --- a/apps/docs/environments.mdx +++ b/apps/docs/environments.mdx @@ -224,15 +224,15 @@ on the next restart (every overwrite is kept in version history). Removing a definition never deletes the environment; it just returns it to normal manual management. -Definitions may reference repositories that are not linked yet; the -environment is created anyway and repository mappings backfill on the next -startup after linking. Keep secrets out of definition files — the -per-environment `env` map is stored in plaintext, so use deployment -environment variables under **Settings > Environments > Deployment Environment -Variables** for secret values. - -See the [self-hosting guide](/self-hosting) for the compose mount pattern and -operational details. +Repositories in a definition must already be linked to the deployment. Roomote +skips definitions with missing repository mappings, logs the reason, and tries +them again on the next startup. Keep secrets out of definition files — the +per-environment `env` map is stored in plaintext, so use deployment environment +variables under **Settings > Environments > Deployment Environment Variables** +for secret values. + +See [Keep definitions in source control](/environments/definition#keep-definitions-in-source-control) +for the Compose mount pattern and deployment workflow. ## Make verification possible diff --git a/apps/docs/environments/definition.mdx b/apps/docs/environments/definition.mdx index 9df82f8d7..e2d15cc17 100644 --- a/apps/docs/environments/definition.mdx +++ b/apps/docs/environments/definition.mdx @@ -31,6 +31,70 @@ The definition is declarative and reproducible: the same YAML produces the same workspace shape for every task, and it is easy to review in a pull request or regenerate from scratch. +## Keep definitions in source control + +Environment definitions are plain YAML, so any team can store them in a git +repository and review changes through pull requests. On Roomote Cloud, apply a +reviewed change by pasting the file into the environment editor's **YAML** view. +Applying the change is manual: Roomote Cloud does not read or sync environment +files from your repository. + +A typical repository layout is: + +```text +.roomote/ + environments/ + web.yaml + api.yaml +docker-compose.override.yml +``` + +### Self-hosted only: automatic file-based reconciliation + +Self-hosted deployments can apply checked-in files automatically at API +startup. Mount the directory read-only into the Roomote API container and point +`ROOMOTE_ENVIRONMENTS_DIR` at the mounted path: + +```yaml +services: + api: + environment: + ROOMOTE_ENVIRONMENTS_DIR: /roomote/environments + volumes: + - ./.roomote/environments:/roomote/environments:ro +``` + +Commit the definition and Compose override, deploy that revision, and recreate +the API container so the new mount is attached. On later definition-only +changes, restart the API. At startup, Roomote reads every `*.yaml`, `*.yml`, and +`*.json` file in the directory. It creates missing environments and updates +existing ones by `name`. Repositories in a definition must already be linked to +the deployment; otherwise Roomote skips that definition and reports the reason +in the API logs. + +The files remain authoritative: edits made in the UI are recorded in version +history but are overwritten the next time the API starts. Removing a definition +does not delete its environment. It removes the managed marker and returns the +environment to normal manual management. + + + Do not commit secrets in an environment definition. Values under `env`, + command `env`, MCP server headers, and similar fields are stored as part of + the definition. Add sensitive values under **Settings > Environments > + Deployment Environment Variables** instead. + + +After deployment, open **Settings > Environments** and confirm that each +environment has the **Managed from file** badge. API startup logs also report +which definitions were created, updated, unchanged, or skipped. + +The startup provisioning mechanism does not clone or poll a separate +configuration repository. A self-hosted deployment must check out the files and +mount them, or supply their contents through `ROOMOTE_ENVIRONMENTS_YAML`. See +[Environments](/environments#provision-environments-declaratively) for +reconciliation behavior and [Self-hosting](/self-hosting) for deployment +options. + ## Relationship to Dev Containers If you have used [Dev Containers](https://containers.dev), the environment