Merge branch 'master' into issue_3328_cli_oauth

Author: r4victor

docs/blog/posts/0_20.md

@@ -0,0 +1,127 @@
+---
+title: "dstack 0.20 GA: Fleet-first UX and other important changes"
+date: 2025-12-18
+description: "TBA"  
+slug: "0_20"
+image: https://dstack.ai/static-assets/static-assets/images/dstack-0_20.png
+categories:
+  - Changelog
+links:
+  - Release notes: https://github.com/dstackai/dstack/releases/tag/0.20.0
+  - Migration guide: https://dstack.ai/docs/guides/migration/#0_20
+---
+
+# dstack 0.20 GA: Fleet-first UX and other important changes
+
+We’re releasing `dstack` 0.20.0, a major update that improves how teams orchestrate GPU workloads for development, training, and inference. Most `dstack` updates are incremental and backward compatible, but this version introduces a few major changes to how you work with `dstack`.
+
+In `dstack` 0.20.0, fleets are now a first-class concept, giving you more explicit control over how GPU capacity is provisioned and managed. We’ve also added *Events*, which record important system activity—such as scheduling decisions, run status changes, and resource lifecycle updates—so it’s easier to understand what’s happening without digging through server logs.
+
+<img src="https://dstack.ai/static-assets/static-assets/images/dstack-0_20.png" width="630" />
+
+This post goes through the changes in detail and explains how to upgrade and migrate your existing setup.
+
+<!-- more -->
+
+## Fleets
+
+In earlier versions, submitting a run that didn’t match any existing fleet would cause `dstack` to automatically create one. While this reduced setup overhead, it also made capacity provisioning implicit and less predictable.
+
+With `dstack` 0.20.0, fleets must be created explicitly and treated as first-class resources. This shift makes capacity provisioning declarative, improving control over resource limits, instance lifecycles, and overall fleet behavior.
+
+For users who previously relied on auto-created fleets, similar behavior can be achieved by defining an elastic fleet, for example:
+
+<div editor-title="fleet.dstack.yml">
+    
+    ```yaml
+    type: fleet
+    # The name is optional, if not specified, generated randomly
+    name: default
+    
+    # Can be a range or a fixed number
+    # Allow to provision up to 2 instances
+    nodes: 0..2
+
+    # Uncomment to ensure instances are inter-connected
+    #placement: cluster
+
+    # Deprovision instances above the minimum if they remain idle
+    idle_duration: 1h
+    
+    resources:
+      # Allow to provision up to 8 GPUs
+      gpu: 0..8
+    ```
+    
+</div>
+
+If the `nodes` range starts above `0`, `dstack` provisions the initial capacity upfront and scales additional instances on demand, enabling more predictable capacity planning.
+
+When a run does not explicitly reference a fleet (via the [`fleets`](../../docs/reference/dstack.yml/dev-environment.md#fleets) property), `dstack` automatically selects one that satisfies the run’s requirements.
+
+## Events
+
+Previously, when `dstack` changed the state of a run or other resource, that information was written only to the server logs. This worked for admins, but it made it hard for users to understand what happened or why.
+
+Starting with version `0.20.0`, `dstack` exposes these events directly to users.
+
+Each resource now includes an `Events` tab in the UI, showing related events in real time:
+
+<img src="https://dstack.ai/static-assets/static-assets/images/dstack-event-ui-run.png" width="750" />
+
+There is also a dedicated `Events` page that aggregates events across resources. You can filter by project, user, run, or job to quickly narrow down what you’re looking for:
+
+<img src="https://dstack.ai/static-assets/static-assets/images/dstack-event-ui-all.png" width="750" />
+
+The same information is available through the CLI:
+
+<img src="https://dstack.ai/static-assets/static-assets/images/dstack-event-cli.png" width="750" />
+
+This makes it easier to track state changes, debug issues, and review past actions without needing access to server logs.
+
+## Runs
+
+This release updates several defaults related to run configuration. The goal is to reduce implicit assumptions and make it more convenient.
+
+### Working directory
+
+Previously, the `working_dir` property defaulted to `/workflow`. Now, the default working directory is always taken from the Docker image.
+
+The working directory in the default Docker images (if you don't specify `image`) is now set to `/dstack/run`.
+
+### Repo directory
+
+Previously, if you didn't specify a repo path, the repo was cloned to `/workflow`. Now, in that case the repo will be cloned to the working directory.
+
+<div editor-title="examples/.dstack.yml"> 
+
+```yaml
+type: dev-environment
+name: vscode    
+
+repos:
+  # Clones the repo from the parent directory (`examples/..`) to `<working dir>`
+  - ..
+
+ide: vscode
+```
+
+</div>
+
+Also, now if the repo directory is not empty, the run will fail with an error.
+
+## Backward compatibility
+
+While the update introduces breaking changes, 0.19.* CLIs remain compatible with 0.20.* servers.
+
+> Note, the 0.20.* CLI only works with a 0.20.* server.
+
+!!! warning "Breaking changes"
+    This release introduces breaking changes that may affect existing setups. Before upgrading either the CLI or the server, review the [migration guide](https://dstack.ai/docs/guides/migration/#0_20).
+
+## What's next
+
+1. Follow the [Installation](../../docs/installation/index.md) guide
+2. Try the [Quickstart](../../docs/quickstart.md)
+3. Report issues on [GitHub](https://github.com/dstackai/dstack/issues)
+4. Ask questions on [Discord](https://discord.gg/u8SmfwPpMd)

docs/docs/concepts/dev-environments.md

@@ -301,11 +301,11 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above),
 
 ### Working directory
 
-If `working_dir` is not specified, it defaults to `/workflow`.
+If `working_dir` is not specified, it defaults to the working directory set in the Docker image. For example, the [default image](#default-image) uses `/dstack/run` as its working directory.
 
-The `working_dir` must be an absolute path. The tilde (`~`) is supported (e.g., `~/my-working-dir`).
+If the Docker image does not have a working directory set, `dstack` uses `/` as the `working_dir`.
 
-<!-- TODO: In a future version, the default working directory will be taken from `image`. -->
+The `working_dir` must be an absolute path. The tilde (`~`) is supported (e.g., `~/my-working-dir`).
 
 <!-- TODO: Elaborate on `entrypoint` -->
 
@@ -320,7 +320,7 @@ type: dev-environment
 name: vscode    
 
 files:
-  - .:examples  # Maps the directory where `.dstack.yml` to `/workflow/examples`
+  - .:examples  # Maps the directory with `.dstack.yml` to `<working dir>/examples`
   - ~/.ssh/id_rsa:/root/.ssh/id_rsa  # Maps `~/.ssh/id_rsa` to `/root/.ssh/id_rsa`
 
 ide: vscode
@@ -329,7 +329,7 @@ ide: vscode
 </div>
 
 If the local path is relative, it’s resolved relative to the configuration file.
-If the container path is relative, it’s resolved relative to `/workflow`.
+If the container path is relative, it’s resolved relative to the [working directory](#working-directory).
 
 The container path is optional. If not specified, it will be automatically calculated:
 
@@ -340,7 +340,7 @@ type: dev-environment
 name: vscode    
 
 files:
-  - ../examples  # Maps `examples` (the parent directory of `.dstack.yml`) to `/workflow/examples`
+  - ../examples  # Maps the parent directory of `.dstack.yml` to `<working dir>/../examples`
   - ~/.ssh/id_rsa  # Maps `~/.ssh/id_rsa` to `/root/.ssh/id_rsa`
 
 ide: vscode
@@ -355,9 +355,9 @@ ide: vscode
 
 ### Repos
 
-Sometimes, you may want to mount an entire Git repo inside the container.
+Sometimes, you may want to clone an entire Git repo inside the container.
 
-Imagine you have a cloned Git repo containing an `examples` subdirectory with a `.dstack.yml` file:
+Imagine you have a Git repo (clonned locally) containing an `examples` subdirectory with a `.dstack.yml` file:
 
 <div editor-title="examples/.dstack.yml"> 
 
@@ -366,24 +366,21 @@ type: dev-environment
 name: vscode    
 
 repos:
-  # Mounts the parent directory of `examples` (must be a Git repo)
-  #   to `/workflow` (the default working directory)
+  # Clones the repo from the parent directory (`examples/..`) to `<working dir>`
   - ..
 
 ide: vscode
 ```
 
 </div>
 
-When you run it, `dstack` fetches the repo on the instance, applies your local changes, and mounts it—so the container matches your local repo.
+When you run it, `dstack` clones the repo on the instance, applies your local changes, and mounts it—so the container matches your local repo.
 
 The local path can be either relative to the configuration file or absolute.
 
 ??? info "Repo directory"
-    By default, `dstack` mounts the repo to `/workflow` (the default working directory).
+    By default, `dstack` clones the repo to the [working directory](#working-directory).
 
-    <!-- TODO: In a future version, the default working directory will come from the image, so this should be revisited. -->
-    
     You can override the repo directory using either a relative or an absolute path:
 
     <div editor-title="examples/.dstack.yml"> 
@@ -393,16 +390,30 @@ The local path can be either relative to the configuration file or absolute.
     name: vscode    
 
     repos:
-      # Mounts the parent directory of `examples` (must be a Git repo)
-      #   to `/my-repo`
+      # Clones the repo in the parent directory (`examples/..`) to `/my-repo`
       - ..:/my-repo
 
     ide: vscode
     ```
     
     </div>
 
-    If the path is relative, it is resolved against [working directory](#working-directory).
+    > If the repo directory is relative, it is resolved against [working directory](#working-directory).
+
+    If the repo directory is not empty, the run will fail with a runner error.  
+    To override this behavior, you can set `if_exists` to `skip`:
+  
+    ```yaml
+    type: dev-environment
+    name: vscode    
+  
+    repos:
+      - local_path: ..
+        path: /my-repo
+        if_exists: skip
+  
+    ide: vscode
+    ```
 
 
 ??? info "Repo size"
@@ -411,7 +422,7 @@ The local path can be either relative to the configuration file or absolute.
     You can increase the 2MB limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.
 
 ??? info "Repo URL"
-    Sometimes you may want to mount a Git repo without cloning it locally. In this case, simply provide a URL in `repos`:
+    Sometimes you may want to clone a Git repo within the container without cloning it locally. In this case, simply provide a URL in `repos`:
 
     <div editor-title="examples/.dstack.yml"> 
 
@@ -420,7 +431,7 @@ The local path can be either relative to the configuration file or absolute.
     name: vscode    
 
     repos:
-      # Clone the specified repo to `/workflow` (the default working directory)
+      # Clone the repo to `<working dir>`
       - https://github.com/dstackai/dstack
 
     ide: vscode
@@ -432,9 +443,9 @@ The local path can be either relative to the configuration file or absolute.
     If a Git repo is private, `dstack` will automatically try to use your default Git credentials (from
     `~/.ssh/config` or `~/.config/gh/hosts.yml`).
 
-    If you want to use custom credentials, you can provide them with [`dstack init`](../reference/cli/dstack/init.md).
+    > If you want to use custom credentials, ensure to pass them via [`dstack init`](../reference/cli/dstack/init.md) before submitting a run.
 
-> Currently, you can configure up to one repo per run configuration.
+Currently, you can configure up to one repo per run configuration.
 
 ### Retry policy