diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx index 83c2130f8..bf7454120 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx @@ -3,16 +3,20 @@ title: Continuous Integration sidebar_label: Continuous Integration --- -`devsy ci` starts a devcontainer workspace and runs a command in it. It deletes a newly created workspace afterward unless you pass `--keep`, but never deletes a workspace that existed before the run. Use it to run tests inside the container and check the build of a newly created workspace. +`devsy ci` starts a devcontainer workspace and runs a command in it. Use it to run tests inside the container and check the build of a newly created workspace. + + +If you omit the workspace argument and select an existing workspace interactively, Devsy can delete that workspace after the run, including its workspace data. Pass `--keep` when selecting a workspace interactively to prevent cleanup. + ## How it works -1. Devsy resolves a workspace from the current directory or a given source. +1. Devsy resolves a workspace from the given source. With no source, it prompts for a workspace in an interactive terminal. 2. Devsy builds and starts the devcontainer like `devsy workspace up`, without IDE or SSH config changes. 3. Devsy runs the command inside the container. -4. Devsy deletes the workspace, even when the command fails, unless you pass `--keep`. Devsy never deletes a workspace that existed before the run. +4. Unless you pass `--keep`, Devsy attempts cleanup when its initial lookup finds no existing workspace, even when the command fails. This can delete an existing workspace selected interactively after that lookup. -The command's exit code becomes the exit code of `devsy ci`, so a failing test fails the CI job. +A failing command fails the CI job. Workspace setup or cleanup errors also cause `devsy ci` to fail. ## Usage @@ -23,26 +27,26 @@ devsy ci [flags] [workspace-path|workspace-name] -- [args...] Run the test suite inside the devcontainer for the current project: ```sh -devsy ci -- make test +devsy ci . -- make test ``` Target a specific project folder and pass environment variables: ```sh devsy ci ./service -- npm test -devsy ci --remote-env CI=true --remote-env NODE_ENV=test -- npm test +devsy ci --remote-env CI=true --remote-env NODE_ENV=test . -- npm test ``` Select a named config, such as a `.devcontainer/` profile: ```sh -devsy ci --devcontainer id:ci -- make test +devsy ci --devcontainer id:ci . -- make test ``` Keep the workspace after the run, for debugging: ```sh -devsy ci --keep -- ./run-integration-tests.sh +devsy ci --keep . -- ./run-integration-tests.sh ``` ### Common flags @@ -87,7 +91,7 @@ structured result. ## Setup history after cleanup -`devsy ci` deletes the workspace, but Devsy keeps the build and lifecycle hook history in the local store. Read it by run ID after the job ends, or from an artifact step on the same machine: +Devsy keeps the build and lifecycle hook history in the local store after workspace cleanup. Read it by run ID after the job ends, or from an artifact step on the same machine: ```sh devsy workspace logs --source setup --list @@ -104,7 +108,7 @@ Desktop launches, `--detach`, JSON output, and management or platform tasks also Pass values to the workspace in one of these ways: -- Environment variables: `devsy ci --workspace-env NAME=value -- make test`. Use `--workspace-env` for values that hooks need. The `--remote-env` flag applies only to the command that CI runs. +- Environment variables: `devsy ci --workspace-env NAME=value . -- make test`. Use `--workspace-env` for values that hooks need. The `--remote-env` flag applies only to the command that CI runs. - Secrets: `--secret` injects a stored Devsy secret. See [Secrets](./secrets.mdx). - Files: write the value to a file that the hook reads. - Arguments: put a value that is not secret in the hook command, such as `"postStartCommand": ["./start.sh", "example-name"]`. @@ -144,5 +148,5 @@ jobs: - name: Run CI in devcontainer run: | devsy provider add docker && devsy provider use docker - devsy ci -- make test + devsy ci . -- make test ``` diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/create-a-workspace.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/create-a-workspace.mdx index cc7e834a8..772248866 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/create-a-workspace.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/create-a-workspace.mdx @@ -176,17 +176,21 @@ This prints the configuration and live state. Add `--result-format json` for scr Recreating applies changes to `devcontainer.json` or its Dockerfile. If a prebuild repository is configured, Devsy looks there for the new image first. -```sh -devsy workspace up my-workspace --recreate -``` - Recreating keeps only the project folder and mounted volumes. Anything else in the container is lost. +```sh +devsy workspace up my-workspace --recreate +``` + ## Reset a workspace -A reset pulls the latest Git changes, or uploads your local folder again. For local-folder workspaces, Devsy removes and re-seeds its managed named volumes. Bind mounts and unmanaged volumes stay. +A reset recreates the container and prepares the source again. For a Git workspace, Devsy removes the existing project folder and clones the configured ref again. For a local-folder workspace, Devsy re-seeds its managed named volumes from the local folder. Bind mounts and unmanaged volumes stay. + + +Back up changes in the workspace before resetting. Removing a Git workspace's project folder deletes uncommitted work and other files in that folder. Resetting managed named volumes deletes their existing contents. + ```sh devsy workspace up my-workspace --reset diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/devcontainer-json.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/devcontainer-json.mdx index a23ca7ef8..608e2bc5b 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/devcontainer-json.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/devcontainer-json.mdx @@ -94,16 +94,16 @@ To send HTTP headers when Devsy downloads a feature archive, set them under `cus After you edit the configuration, apply it without deleting the workspace: + +Anything outside volumes is lost. The project folder and other mounted paths stay. + + ```sh devsy workspace up my-workspace --recreate ``` Devsy builds and validates the new image before stopping or replacing the existing container. If the build fails, the existing workspace stays in its previous state, whether running or stopped. A later failure can leave the old container stopped or removed, depending on the provider. Pass `--recovery` to start a recovery container with features and lifecycle commands disabled if the build fails. - -Anything outside volumes is lost. The project folder and other mounted paths stay. - - ## postStartCommand and waitFor `waitFor` names the lifecycle hook that `devsy workspace up` waits for before it returns. The default is `updateContentCommand`, so `postStartCommand` can finish after `up` returns. diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/inactivity-timeout.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/inactivity-timeout.mdx index 5681cada6..ca6eaec0f 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/inactivity-timeout.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/inactivity-timeout.mdx @@ -20,6 +20,10 @@ Defaults when the option is unset: **Docker, Podman, Apple, and Microsandbox:** A daemon in the container watches for activity. For Microsandbox, Devsy also passes the timeout to the microsandbox CLI as `--idle-timeout`. + +The detached container daemon exits when its timeout expires, but that exit does not stop a Docker or Podman container. Do not rely on `INACTIVITY_TIMEOUT` to stop these containers. Stop them explicitly with `devsy workspace stop`. + + The Apple provider option describes the timeout as deleting the container instead of stopping it. Deleting a container loses files outside mounted volumes. @@ -35,9 +39,9 @@ A workspace is active while either of these holds: - A tracked `devsy workspace ssh` session is connected. Devsy records activity when the session connects, periodically while it stays open, and when it ends. The idle period starts at disconnect. - Setup is running: the synchronous `devsy workspace up` setup, deferred lifecycle hooks, and `postAttachCommand`. -CPU use and processes you start yourself do not count. For example, `nohup make &` in a closed session does not keep the workspace running. +CPU use and processes you start yourself do not count as activity. For example, `nohup make &` in a closed session does not reset the idle timer. -The daemon checks idle time about once a second, so a workspace stops a few seconds after the timeout passes. +The daemon checks idle time about once a second. A managed Kubernetes pod ends a few seconds after the timeout passes. On Kubernetes, SSH sessions and hooks register with the daemon before they do work and stay active while their connection lasts. If the daemon connection is lost, Devsy cancels the protected work. Failed activity-file writes or a full disk cannot hide live work. diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/workspace-snapshots.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/workspace-snapshots.mdx index c11e05e09..7c1711d05 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/workspace-snapshots.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/workspace-snapshots.mdx @@ -3,7 +3,7 @@ title: Workspace Snapshots sidebar_label: Workspace Snapshots --- -A snapshot saves a workspace at one point in time: the container filesystem (installed packages, config changes) and the contents of the bind-mounted volume, including uncommitted code. Devsy stores snapshots as OCI artifacts in a registry you control. Restore a snapshot later or use it to move a workspace to another provider. +A snapshot saves the container filesystem (installed packages and config changes) and the contents of a host bind-mounted workspace, including uncommitted code. Devsy stores snapshots as OCI artifacts in a registry you control. Restore a snapshot later or use it to move a workspace to another provider. Devsy pushes snapshots to an OCI registry and pulls them from it when needed. Creating a snapshot also leaves the committed container image locally after the push, but the registry is still required for the snapshot manifest and volume. You need push and pull access. @@ -11,13 +11,17 @@ Devsy pushes snapshots to an OCI registry and pulls them from it when needed. Cr ## Limitations -- The workspace mount must be the only bind mount. Snapshot creation fails if `devcontainer.json` adds more bind mounts. +- The workspace must use a host bind mount, and it must be the only bind mount. Snapshot creation fails if `devcontainer.json` adds more bind mounts. +- Named workspace volumes are not reliably captured. Snapshot creation can fail or capture an unrelated host directory instead. Do not rely on a snapshot to back up a named workspace volume. +- Other named volumes are not included, even when the workspace bind mount is the only bind mount. Back up and restore their contents separately. - Only local providers, such as Docker and Podman, can create snapshots. Machine-provider workspaces cannot. ## Create a snapshot The workspace must exist and be running. +Stop applications that write to the container filesystem or workspace mount before creating the snapshot. Devsy captures them separately while the workspace is running, so changes made during capture can leave the snapshot inconsistent. + ```sh devsy snapshot create my-workspace --registry ghcr.io/my-org/snapshots ``` @@ -44,7 +48,7 @@ The output lists every snapshot of the workspace, newest first. devsy snapshot restore ``` -Restore creates a workspace from the saved filesystem and volume. It skips the devcontainer build and reuses the original workspace ID. Pass `--workspace-id` to use another ID or `--target-provider` to restore onto another provider. +Restore creates a workspace from the saved container filesystem and workspace mount. It skips the devcontainer build and reuses the original workspace ID. Pass `--workspace-id` to use another ID or `--target-provider` to restore onto another provider. `devsy workspace up` can also restore a snapshot. Do not combine it with a source argument or `--source`. @@ -62,7 +66,7 @@ devsy snapshot delete ## Export and import -`devsy workspace export` and `devsy workspace import` keep the snapshot reference of a restored workspace. The import restores the filesystem and volume only when the manifest still exists and the importing machine can pull from the registry. Otherwise it restores only the workspace metadata. +`devsy workspace export` and `devsy workspace import` keep the snapshot reference of a restored workspace. The import restores the container filesystem and workspace mount only when the manifest still exists and the importing machine can pull from the registry. Otherwise it restores only the workspace metadata. ## What the snapshot includes diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/agent.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/agent.mdx index 26976cbb1..b0d78ae4f 100644 --- a/sites/docs-devsy-sh/content/docs/developing-providers/agent.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-providers/agent.mdx @@ -3,40 +3,26 @@ title: Provider Agent sidebar_label: Provider Agent --- -Devsy injects itself into an environment when it connects through a provider. That copy is the Devsy agent. It is the same binary, run as `devsy agent`. The agent deploys the container, forwards credentials, runs the SSH server, and stops idle environments. +Devsy runs a copy of its CLI as an agent in the provider environment. For a remote provider, it places the binary on the remote machine. A local provider uses the host's binary. The agent deploys the workspace, forwards credentials, runs the SSH server, and manages inactivity shutdown. -The `agent` section of `provider.yaml` configures the agent. +Configure it in the `agent` section of `provider.yaml`. This example uses a local Docker daemon: ```yaml agent: - path: ${DEVSY} local: true driver: docker - inactivityTimeout: 10m - containerInactivityTimeout: 10m - injectGitCredentials: ${INJECT_GIT_CREDENTIALS} - injectDockerCredentials: ${INJECT_DOCKER_CREDENTIALS} - binaries: - MY_BINARY: - - os: linux - arch: amd64 - path: https://example.com/my-binary - checksum: - exec: - shutdown: |- - ${MY_BINARY} stop ``` This section can use option values. -- **path**: where the agent is placed on the remote machine. -- **local**: set to `true` when Devsy runs on the same machine instead of a remote one. The built-in providers set it. +- **path**: path to the agent binary in the provider environment. If omitted, a local agent uses the current executable; a remote agent uses Devsy's default install path. +- **local**: set to `true` when the agent runs on the user's machine. Leave it unset or `false` for a remote machine. - **driver**: how the container is deployed. One of `docker` (default), `kubernetes`, `apple`, `microsandbox`, `custom` or `external`. See [Drivers](./driver.mdx). - **inactivityTimeout**: how long an idle machine runs before Devsy stops it. Machine providers only. -- **containerInactivityTimeout**: how long the container may stay idle before it stops. A Go duration such as `10m`. Empty or `0` disables it. Non-machine providers only. -- **injectGitCredentials**, **injectDockerCredentials**: whether to copy those credentials into the environment. +- **containerInactivityTimeout**: idle period monitored by the container daemon, as a Go duration such as `10m`. For Kubernetes, an empty value falls back to the deprecated `agent.kubernetes.inactivityTimeout`. If both fields are set, their durations must match. Clear both fields or set both to `0` to disable the timeout. For Kubernetes, expiry ends the pod. A detached Docker or Podman daemon does not stop its container when the timer expires. +- **injectGitCredentials**, **injectDockerCredentials**: whether to forward those credentials into the environment. The context's credential-forwarding settings override these provider values. See [Credentials](../developing-in-workspaces/credentials.mdx). - **exec.shutdown**: the command that stops the machine once it is idle. Option values are available in it. -- **binaries**: helper binaries for `exec.shutdown`. Same format as [provider binaries](./binaries.mdx). +- **binaries**: helper binaries for `exec.shutdown`. Declare them under `agent.binaries`, using the format in [Provider binaries](./binaries.mdx). ## Docker management policy @@ -58,7 +44,7 @@ Set `configureDaemon: false` when the provider owns the Docker daemon, including ## Stopping idle environments -Devsy tracks connections and stops the environment after the timeout. It starts the environment again when the user returns. State survives only if the provider keeps the storage. A shutdown command that deletes the machine must keep workspace data elsewhere, for example on a persistent volume. +Inactivity shutdown depends on the provider and driver. Start a stopped workspace with `devsy workspace up`. State survives only if the provider keeps the storage. A shutdown command that deletes the machine must keep workspace data elsewhere, for example on a persistent volume. ### Non-machine providers @@ -70,4 +56,4 @@ Any UID in the same container can block inactivity through a live activity conne ### Machine providers -Stopping only the container leaves the VM running and billed. Define `agent.exec.shutdown` with a command that stops or deletes the machine on the cloud side. Set the timeout with `inactivityTimeout`. Each official cloud provider does this differently. One calls a cloud API with a token saved in an option. +Stopping only the container leaves the VM running and billed. Define `agent.exec.shutdown` with a command that stops or deletes the machine on the cloud side, and set `inactivityTimeout`. If the command needs a helper binary, declare it under `agent.binaries`. Check the provider's API and storage policy before choosing between stopping and deleting the machine. diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx index 61fd146c9..082098ba0 100644 --- a/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx @@ -12,9 +12,9 @@ binaries: MY_BINARY: - os: linux arch: amd64 - path: https://example.com/my-binary-linux-amd64 # URL or local path + path: https://example.com/my-binary-linux-amd64 checksum: - name: my-binary # optional, defaults to the file name + name: my-binary - os: darwin arch: arm64 path: https://example.com/my-binary-darwin-arm64 @@ -23,6 +23,8 @@ binaries: Supported archives are `.tgz`, `.tar`, `.tar.gz` and `.zip`. When a user adds the provider, Devsy downloads the item that matches their OS and architecture and verifies `checksum` if set. +`path` can also point to a local executable. `name` sets the installed file name for a direct download and defaults to the file name in `path`. + See the official providers, such as [devsy-provider-aws](https://github.com/devsy-org/devsy-provider-aws), for complete examples. @@ -39,7 +41,7 @@ binaries: - os: linux arch: amd64 path: https://example.com/my-binary-linux-amd64.tar.gz - archivePath: bin/my-binary # executable inside the archive + archivePath: bin/my-binary checksum: ``` @@ -49,7 +51,7 @@ Devsy extracts the whole archive into a folder for the binary and keeps its layo `checksum` is optional, except for the `agent.binaries` entry selected by `agent.external.binary`, which needs one for every platform. See [External Driver](./driver.mdx#external-driver). -When set, Devsy computes the SHA256 of the file it runs and compares it case-insensitively. For an HTTP(S) archive, that file is the one extracted at `archivePath`, never the archive. A mismatch deletes the file and fails the download without retrying. +When set, Devsy computes the SHA-256 of the executable and compares it case-insensitively. For an HTTP(S) archive, it checks the extracted file at `archivePath`, not the archive. A downloaded file with a checksum mismatch is removed, and the download fails without retrying. A local source file with a mismatch is left in place. Verify the binary against a trusted source before changing its checksum. Update the manifest checksum only for an intentional, verified binary change; otherwise, restore the expected file before trying again. ## Use a binary diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/driver.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/driver.mdx index 72344909f..52b383fd7 100644 --- a/sites/docs-devsy-sh/content/docs/developing-providers/driver.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-providers/driver.mdx @@ -49,7 +49,7 @@ Options for the Kubernetes driver: - **serviceAccount**: if set, the dev container uses this service account. - **architecture**: CPU architecture of the workspace pod, e.g. `amd64` or `arm64`. If empty, Devsy detects it from the cluster nodes. It fails if the cluster mixes architectures. - **imageConfigFile**: path to a versioned JSON file with the digest-pinned image reference, platform, and OCI config for the devcontainer.json `image`. When set, Devsy reads the user, env, entrypoint, cmd, and `devcontainer.metadata` label from the file instead of the registry. See [Starting workspaces without registry access](#starting-workspaces-without-registry-access). -- **inactivityTimeout**: idle time before Devsy stops the pod +- **inactivityTimeout**: deprecated fallback for `agent.containerInactivityTimeout`. Set `agent.containerInactivityTimeout` for new providers. - **storageClass**: storage class for the persistent volume claim - **diskSize**: default persistent volume size, e.g. `10Gi` - **pvcAccessMode**: access mode for the persistent volume claim, e.g. `RWO`, `ROX`, `RWX` or `RWOP` @@ -86,19 +86,15 @@ Example provider that runs a workspace in the current kube context: name: simple-kubernetes version: v0.0.1 agent: - containerInactivityTimeout: 10m # Pod stops itself after being idle for the timeout - path: ${DEVSY} + containerInactivityTimeout: 10m + local: true driver: kubernetes kubernetes: - # kubernetesContext: default - # kubernetesNamespace: my-namespace-for-devsy - # clusterRole: "" - # serviceAccount: "" diskSize: 20Gi createNamespace: true exec: command: |- - ${DEVSY} helper sh -c "${COMMAND}" + "${DEVSY}" internal sh -c "${COMMAND}" ``` Add the provider with `devsy provider add ./simple-kubernetes.yaml`. diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/options.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/options.mdx index e4f6475b5..92fa0990d 100644 --- a/sites/docs-devsy-sh/content/docs/developing-providers/options.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-providers/options.mdx @@ -7,14 +7,13 @@ Options are settings the user configures for a provider, such as an account, reg ```yaml options: - MY_OPTION: - description: "this is my option" - default: "default_value" - required: false + API_TOKEN: + description: API token for the provider service + required: true password: true ``` -Devsy validates options when the provider is added. It passes them to every command as environment variables. Options can also appear in the `agent` section and in `agent.exec`. The provider reads and validates its own variables. Put that check in the `init` command, which Devsy runs when options change. +Devsy validates the option definitions when the provider is added. It resolves their values and passes them to provider commands as environment variables. The `agent` section can also reference these values. Use `init` for checks that need to contact the service, such as verifying a token. Devsy runs `init` when options change. ## Attributes @@ -23,7 +22,7 @@ Devsy validates options when the provider is added. It passes them to every comm - `default`: default value, as a string. It can reference other options, for example `${OTHER}-suffix`. Devsy resolves them in order. Cannot be combined with `command`. - `required`: the value must be non-empty. The CLI prompts for it, and the Desktop app asks for it. - `password`: treat the value as a secret. `devsy provider get` hides it, and the Desktop app shows a password field. -- `type`: `string` (default), `multiline`, `duration`, `number` or `boolean`. Devsy validates the value against it. +- `type`: `string` (default), `multiline`, `duration`, `number` or `boolean`. Devsy validates the value against it. `number` accepts integers, not decimals; `duration` accepts Go durations such as `30s` or `10m`. - `enum`: the only allowed values. Devsy rejects anything else. - `suggestions`: values offered as autocomplete in the Desktop app. Not enforced, and not shown in the CLI. - `validationPattern`: regex the value must match. @@ -41,22 +40,26 @@ Devsy validates options when the provider is added. It passes them to every comm Pass a variable from the user's machine: ```yaml -AWS_ACCESS_KEY_ID: - description: The AWS access key ID - command: printf "%s" "${AWS_ACCESS_KEY_ID:-}" +options: + AWS_ACCESS_KEY_ID: + description: The AWS access key ID + command: printf "%s" "${AWS_ACCESS_KEY_ID:-}" ``` Run a helper binary and cache the result: ```yaml -AWS_TOKEN: - local: true - hidden: true - cache: 5m - description: The AWS auth token to use - command: ${AWS_PROVIDER} token +options: + AWS_TOKEN: + local: true + hidden: true + cache: 5m + description: The AWS auth token to use + command: ${AWS_PROVIDER} token ``` +The second example assumes the provider declares a helper binary named `AWS_PROVIDER` with a `token` command. + ## Built-in options Use these in `default` and `command`. Some work only in `local` options, because the machine or workspace does not exist yet when other options resolve. diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/quickstart.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/quickstart.mdx index cd0ae69ec..618451452 100644 --- a/sites/docs-devsy-sh/content/docs/developing-providers/quickstart.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-providers/quickstart.mdx @@ -1,39 +1,41 @@ --- -title: Quickstart Guide +title: Build a provider sidebar_label: Quickstart --- A provider is a program described by a `provider.yaml` file. Devsy reads the manifest and calls the commands it defines to create and reach an environment. -Read [What are providers](../managing-providers/what-are-providers.mdx) and [Add a Devsy Provider](../managing-providers/manage-providers.mdx) first. +Read [What are providers](../managing-providers/what-are-providers.mdx) and [Manage providers](../managing-providers/manage-providers.mdx) first. ## A minimal provider -This provider runs workspaces on the local machine: +This provider runs workspaces through Docker on your machine. Install Docker and start its daemon before trying it. ```yaml -name: my-first-provider # required -version: v0.0.1 # required +name: my-first-provider +version: v0.0.1 agent: - path: ${DEVSY} # path to the current Devsy binary + local: true + driver: docker exec: - # How to run a command in the environment. Here: a local shell. command: |- - sh -c "${COMMAND}" + "${DEVSY}" internal sh -c "${COMMAND}" ``` -Save it as `provider.yaml`, add it, and start a workspace: +Save it as `provider.yaml`. Run these commands in your host terminal: -``` +```sh devsy provider add ./provider.yaml devsy workspace up github.com/microsoft/vscode-remote-try-go ``` +Adding the provider makes it the default for new workspaces. The second command clones the sample repository and starts its devcontainer. Existing workspaces keep their provider. + ## Sections of provider.yaml -- `name`, `version`: required. `description` is optional and shown in the Desktop app. +- `name`: required, at most 32 lowercase letters, numbers, or hyphens. `version` is optional; when set, use a semantic version such as `v0.0.1`. `description` is optional and shown in the Desktop app. - [`exec`](#exec): the commands Devsy runs to reach and manage the environment. - [`options`](./options.mdx): settings the user can configure. Devsy passes them to commands as environment variables. - [`binaries`](./binaries.mdx): helper binaries Devsy downloads for the provider. @@ -48,21 +50,37 @@ An array with one element is parsed as a shell script, not as an executable path - **command**: runs a command in the environment. Devsy uses it to inject itself, and sends all traffic through its standard input and output. Devsy fills in the `${COMMAND}` placeholder. - **init**: checks that the options are valid and the provider is ready. Devsy runs it when options change. -- **create**, **delete**: create and delete a machine. Defining `create` makes the provider a machine provider, so `delete` is expected too. -- **start**, **stop**: start and stop a machine. Machine providers only. +- **create**, **delete**: create and delete a machine. Define both or neither. Defining `create` makes this a machine provider. +- **start**, **stop**: start and stop a machine. Define both or neither. These require `create` and `status`. - **status**: prints one of `Running`, `Busy` (wait and check again), `Stopped` or `NotFound`. - **describe**: prints a text description of the machine. -- **cancellation**: omit it for existing process cancellation behavior, or set `file` to give provider commands a cooperative cleanup window. +- **cancellation**: omit it to use the default cancellation behavior, or set `file` to give provider commands a cooperative cleanup window. A standard provider without `create` is a non-machine provider and uses only `command` and `init`. The cancellation policy applies to both machine and non-machine providers. -With `exec.cancellation: file`, Devsy sets the reserved `DEVSY_PROVIDER_CANCEL_FILE` environment variable to a private, initially nonexistent marker path for each invocation. The provider must watch for the marker, stop admitting work, cancel its owned processes, finish cleanup, and exit. On caller cancellation, Devsy creates the marker and allows up to 10 seconds for cleanup. For single-string shell commands that remain blocked, Devsy then asks its supervised shell to stop and reap its direct children before terminating the shell; it waits up to another 5 seconds for an authenticated acknowledgement before killing an unresponsive helper. A provider-writable acknowledgement file does not establish that cleanup finished: a missing or forged acknowledgement, including when the helper exits abruptly during the cleanup window, is reported as an unclean shutdown alongside the caller's cancellation error. Devsy never kills the provider's process group or unrelated daemon processes. It waits for the invocation to finish and still returns the caller's cancellation error even if cleanup exits successfully. A provider must not set or override the reserved variable. +### Handle cancellation + +With `exec.cancellation: file`, Devsy sets `DEVSY_PROVIDER_CANCEL_FILE` to a private marker path that does not exist yet. Do not set or override this reserved variable. + +When the caller cancels, Devsy creates the marker. Your command has up to 10 seconds to stop accepting work, cancel its owned processes, clean up, and exit. + +If a single-string shell command is still blocked, Devsy asks its shell supervisor to stop and reap direct children. It allows up to another 5 seconds for an authenticated acknowledgement, then kills an unresponsive helper. A missing or forged acknowledgement, including after an abrupt helper exit, is reported as an unclean shutdown. A provider-written acknowledgement file does not prove cleanup finished. + +Devsy waits for the invocation to finish and returns the caller's cancellation error even if cleanup succeeds. It does not kill the provider's process group or unrelated daemons. + +The supervisor also stops and reaps direct children when the script finishes normally. A job started with `&` cannot outlive that invocation. A detached descendant can, so your provider must manage it. Use the backend's detached operation for durable services. + +### Handle command streams + +Cancellation cannot interrupt an arbitrary blocked reader or writer. File cancellation mode works with finite or nonblocking streams, direct file input handles, or blocking streams that their owner unblocks when the original calling context is cancelled. -For shell commands, the supervisor also stops and reaps direct children still running when the script completes normally. A direct background child started with `&` cannot outlive its invocation. A detached descendant can outlive it, so the provider must manage those processes explicitly. Start durable services through the backend's explicit detached operation, not a shell background job. +- Drain or unblock stdout and stderr on cancellation, including file-backed pipes. Devsy may wrap a direct `*os.File` output for redaction, so it can still block after the child exits. +- Devsy does not close caller-owned input or global standard input. Machine command transports close their own pipe endpoints when the original context is cancelled. +- Keep draining output after standard input reaches EOF. Input and output can close independently. -File mode accepts finite or nonblocking standard streams, direct file input handles, and blocking streams whose owner unblocks them when the original calling context is cancelled. A direct `*os.File` output handle is not exempt: Devsy can wrap it for redaction, and a blocked output write can prevent completion after the child exits. Callers must drain or unblock blocking stdout and stderr, including file-backed pipes, on cancellation. Devsy does not close caller-owned input or global standard input, and process cancellation cannot interrupt an arbitrary blocked reader or writer. Machine command transports close their pipe endpoints on cancellation of the original context. Standard input can close independently of standard output, so providers must continue draining output after input reaches EOF. +### Windows compatibility -On Windows, Devsy runs these scripts in an [emulated shell](https://github.com/mvdan/sh). The emulated shell has no `grep` or `sed`. Move that logic into a helper binary. +On Windows, Devsy runs these scripts in an [emulated shell](https://github.com/mvdan/sh). It does not provide `grep` or `sed`. Put that logic in a helper binary or require the user to install those tools. Example from the [SSH provider](https://github.com/devsy-org/devsy-provider-ssh): diff --git a/sites/docs-devsy-sh/content/docs/fragments/virtualbox-ubuntu-22.04.mdx b/sites/docs-devsy-sh/content/docs/fragments/virtualbox-ubuntu-22.04.mdx index ae52f993c..1f10e6c51 100644 --- a/sites/docs-devsy-sh/content/docs/fragments/virtualbox-ubuntu-22.04.mdx +++ b/sites/docs-devsy-sh/content/docs/fragments/virtualbox-ubuntu-22.04.mdx @@ -75,7 +75,7 @@ Select your keyboard layout, then select 'Continue'. #### Step 5 - Installation type -Select 'Erase disk and install Ubuntu', click 'Install Now' +Select 'Erase disk and install Ubuntu', then click 'Install Now'. This erases the VM's virtual disk, not the host computer's disk. When asked to write the changes to disks, select 'Continue' diff --git a/sites/docs-devsy-sh/content/docs/managing-machines/machine-diagnostics.mdx b/sites/docs-devsy-sh/content/docs/managing-machines/machine-diagnostics.mdx index 984f8dfdf..41ad5d214 100644 --- a/sites/docs-devsy-sh/content/docs/managing-machines/machine-diagnostics.mdx +++ b/sites/docs-devsy-sh/content/docs/managing-machines/machine-diagnostics.mdx @@ -9,7 +9,7 @@ Run diagnostics when a machine did not stop when you expected. They report on th devsy machine diagnostics ``` -The output shows the provider's machine state and the daemon's state separately, then the last patrol and each workspace. Add `--result-format json` for scripts. +The output shows the provider's machine state and the daemon's health separately, then the last patrol and each workspace. Add `--result-format json` for scripts. ## When a machine stops diff --git a/sites/docs-devsy-sh/content/docs/what-is-devsy.mdx b/sites/docs-devsy-sh/content/docs/what-is-devsy.mdx index 01a198e58..4c682ecb1 100644 --- a/sites/docs-devsy-sh/content/docs/what-is-devsy.mdx +++ b/sites/docs-devsy-sh/content/docs/what-is-devsy.mdx @@ -11,12 +11,16 @@ Devsy creates development workspaces from a [devcontainer.json](https://containe
Devsy
-A [provider](./managing-providers/what-are-providers) decides where a workspace runs: your machine, an SSH host, Kubernetes, or a cloud. You can also [write your own](./developing-providers/quickstart). Devsy creates and manages every workspace the same way, whatever the provider. +A [provider](./managing-providers/what-are-providers) decides where a workspace runs: your machine, an SSH host, Kubernetes, or a cloud. You can also [write your own](./developing-providers/quickstart). The provider handles access to that environment; you use Devsy to create, connect to, and stop the workspace. -## Benefits +## What you can do -- **One environment definition.** `devcontainer.json` is an open standard. The same file works on every provider. -- **Your infrastructure.** Run workspaces on machines you already have. Machine providers can stop idle machines with an [inactivity timeout](./developing-in-workspaces/inactivity-timeout). -- **Portable workspaces.** Recreate a workspace on another provider with the same definition. To also move container and volume state, [snapshot](./developing-in-workspaces/workspace-snapshots) a local-provider workspace that has a single bind mount. -- **Your editor.** VS Code, the JetBrains IDEs, and any editor that can connect over SSH. -- **Desktop app and CLI.** Use the desktop app day to day. Use the CLI for automation. +- Define your project's tools and setup commands in `devcontainer.json`, an open standard. Runtime-specific settings, such as host mounts, may need changes when you switch providers. +- Run workspaces on machines you already have. Machine providers can stop idle machines with an [inactivity timeout](./developing-in-workspaces/inactivity-timeout). +- Recreate a workspace on another provider with the same definition. A [snapshot](./developing-in-workspaces/workspace-snapshots) can also move the container filesystem and a host bind-mounted workspace. Move named volume data separately. +- Connect with VS Code, a JetBrains IDE, or any editor that supports SSH. +- Use the desktop app for daily work and the CLI for automation. + +## Start a workspace + +[Install Devsy](./getting-started/install), then follow the [quickstart](./getting-started/quickstart) to start a workspace with Docker. If you already have a workspace, see [Connect to a workspace](./developing-in-workspaces/connect-to-a-workspace).