Deploying to gh-pages from @ dstackai/dstack@056eb71 🚀

Author: peterschmidt85

docs/concepts/fleets/index.html

@@ -4795,9 +4795,7 @@ <h4 id="ssh-placement">Placement<a class="headerlink" href="#ssh-placement" titl
 <p>For more details on optimal inter-node connectivity, read the <a href="../../guides/clusters/">Clusters</a> guide.</p>
 </blockquote>
 <h4 id="ssh-blocks">Blocks<a class="headerlink" href="#ssh-blocks" title="Permanent link">&para;</a></h4>
-<p>By default, a single job occupies the entire instance, so if the instance has 8 GPUs, the job will use all of them.</p>
-<p>To make it more efficient, you can set the blocks property to specify how many blocks you’d like the instance to be
-divided into, allowing multiple jobs to use these blocks concurrently.</p>
+<p>By default, a job uses the entire instance—e.g., all 8 GPUs. To allow multiple jobs on the same instance, set the <code>blocks</code> property to divide the instance. Each job can then use one or more blocks, up to the full instance.</p>
 <div editor-title=".dstack.yml">
 
     <div class="highlight"><pre><span></span><code><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">fleet</span>
@@ -4819,13 +4817,13 @@ <h4 id="ssh-blocks">Blocks<a class="headerlink" href="#ssh-blocks" title="Perman
 
 </div>
 
-<p>For instance, with 8 GPUs, 128 CPUs, and 2TB of memory, setting blocks to 8 would assign 1 GPU, 16 CPUs, and 256 GB of
-memory to each block. These blocks can be used concurrently, and a single job can occupy multiple blocks if needed.</p>
-<blockquote>
-<p>GPUs and CPUs must be divisible by the number of blocks. All resources (GPU, CPU, memory) are split proportionally,
-except disk storage, which is shared.</p>
-</blockquote>
-<p>You can also set <code>blocks</code> to <code>auto</code>, which automatically sets the number of blocks to match the number of GPUs.</p>
+<p>All resources (GPU, CPU, memory) are split evenly across blocks, while disk is shared.</p>
+<p>For example, with 8 GPUs, 128 CPUs, and 2TB RAM, setting <code>blocks</code> to <code>8</code> gives each block 1 GPU, 16 CPUs, and 256 GB RAM.</p>
+<p>Set <code>blocks</code> to <code>auto</code> to match the number of blocks to the number of GPUs.</p>
+<div class="admonition info">
+<p class="admonition-title">Distributed tasks</p>
+<p>Distributed tasks require exclusive access to all host resources and therefore must use all blocks on each node.</p>
+</div>
 <h4 id="environment-variables">Environment variables<a class="headerlink" href="#environment-variables" title="Permanent link">&para;</a></h4>
 <p>If needed, you can specify environment variables that will be used by <code>dstack-shim</code> and passed to containers.</p>
 <p>For example, these variables can be used to configure a proxy:</p>

docs/guides/protips/index.html

@@ -1166,6 +1166,19 @@
     </span>
   </a>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#projects" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <span class="md-typeset">
+          Projects
+        </span>
+      
+    </span>
+  </a>
+  
 </li>
 
         <li class="md-nav__item">
@@ -4112,6 +4125,19 @@
     </span>
   </a>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#projects" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <span class="md-typeset">
+          Projects
+        </span>
+      
+    </span>
+  </a>
+  
 </li>
 
         <li class="md-nav__item">
@@ -4439,6 +4465,20 @@ <h2 id="docker-and-docker-compose">Docker and Docker Compose<a class="headerlink
 </code></pre></div>
 </details>
 <p>See more Docker examples <a href="https://github.com/dstackai/dstack/tree/master/examples/misc/docker-compose">here</a>.</p>
+<h2 id="projects">Projects<a class="headerlink" href="#projects" title="Permanent link">&para;</a></h2>
+<p>If you're using multiple <code>dstack</code> projects (e.g., from different <code>dstack</code> servers),<br />
+you can switch between them using the <a href="../../reference/cli/dstack/project/"><code>dstack project</code></a> command.</p>
+<p>Alternatively, you can install <a href="https://direnv.net/" target="_blank"><code>direnv</code> <span class="twemoji external"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m11.93 5 2.83 2.83L5 17.59 6.42 19l9.76-9.75L19 12.07V5z"/></svg></span></a><br />
+to automatically apply environment variables from the <code>.envrc</code> file in your project directory.</p>
+<div editor-title=".envrc"> 
+
+<div class="highlight"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">DSTACK_PROJECT</span><span class="o">=</span>main
+</code></pre></div>
+
+</div>
+
+<p>Now, <code>dstack</code> will always use this project within this directory.</p>
+<p>Remember to add <code>.envrc</code> to <code>.gitignore</code> to avoid committing it to the repo. </p>
 <h2 id="environment-variables">Environment variables<a class="headerlink" href="#environment-variables" title="Permanent link">&para;</a></h2>
 <p>If a configuration requires an environment variable that you don't want to hardcode in the YAML, you can define it
 without assigning a value:</p>
@@ -4481,8 +4521,8 @@ <h2 id="environment-variables">Environment variables<a class="headerlink" href="
 </code></pre></div>
 </div>
 <p>If you install <a href="https://direnv.net/" target="_blank"><code>direnv</code> <span class="twemoji external"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m11.93 5 2.83 2.83L5 17.59 6.42 19l9.76-9.75L19 12.07V5z"/></svg></span></a>,
-it will automatically pass the environment variables from the <code>.env</code> file to the <code>dstack apply</code> command.</p>
-<p>Remember to add <code>.env</code> to <code>.gitignore</code> to avoid pushing it to the repo.    </p>
+it will automatically apply the environment variables from the <code>.envrc</code> file to the <code>dstack apply</code> command.</p>
+<p>Remember to add <code>.envrc</code> to <code>.gitignore</code> to avoid committing it to the repo.    </p>
 </details>
 <h2 id="attached-mode">Attached mode<a class="headerlink" href="#attached-mode" title="Permanent link">&para;</a></h2>
 <p>By default, <code>dstack apply</code> runs in attached mode.

docs/reference/cli/dstack/project/index.html

@@ -4052,6 +4052,23 @@ <h1 id="dstack-project">dstack project<a class="headerlink" href="#dstack-projec
 <p>The <code>dstack server</code> command automatically creates the default <code>main</code> project and adds its configuration in <code>~/.dstack/config.yml</code>.</p>
 </blockquote>
 <p>The <code>dstack project set-default</code> command can be used to switch between multiple projects.</p>
+<details class="info">
+<summary>Environment variable</summary>
+<p>Alternatively to <code>dstack project set-default</code>, you can set the <code>DSTACK_PROJECT</code> environment variable. It overrides the default project set in <code>~/.dstack/config.yml</code>.</p>
+<div class="termy">
+<div class="highlight"><pre><span></span><code>$<span class="w"> </span><span class="nv">DSTACK_PROJECT</span><span class="o">=</span>main
+$<span class="w"> </span>dstack<span class="w"> </span>apply<span class="w"> </span>-f<span class="w"> </span>examples/.dstack.yml
+</code></pre></div>
+</div>
+<p>Also, you can install <a href="https://direnv.net/" target="_blank"><code>direnv</code> <span class="twemoji external"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m11.93 5 2.83 2.83L5 17.59 6.42 19l9.76-9.75L19 12.07V5z"/></svg></span></a><br />
+to automatically apply environment variables from the <code>.envrc</code> file in your project directory.</p>
+<p><div editor-title=".envrc"> </p>
+<div class="highlight"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">DSTACK_PROJECT</span><span class="o">=</span>main
+</code></pre></div>
+</div>
+<p>Now, <code>dstack</code> will always use this project within this directory.</p>
+<p>Remember to add <code>.envrc</code> to <code>.gitignore</code> to avoid committing it to the repo. </p>
+</details>
 <h2 id="dstack-project-add">dstack project add<a class="headerlink" href="#dstack-project-add" title="Permanent link">&para;</a></h2>
 <p>This command adds a new project configuration.</p>
 <div class="termy">