Deploying to gh-pages from @ dstackai/dstack@fc9afa9 🚀

Author: r4victor

docs/guides/server-deployment.md

@@ -135,6 +135,11 @@ To store the server state in Postgres, set the `DSTACK_DATABASE_URL` environment
 $ DSTACK_DATABASE_URL=postgresql+asyncpg://user:password@db-host:5432/dstack dstack server
 ```
 
+The minimum requirements for the DB instance are 2 CPU, 2GB of RAM, and at least 50 `max_connections` per server replica
+or a configured connection pooler to handle that many connections.
+If you're using a smaller DB instance, you may need to set lower `DSTACK_DB_POOL_SIZE` and `DSTACK_DB_MAX_OVERFLOW`, e.g.
+`DSTACK_DB_POOL_SIZE=10` and `DSTACK_DB_MAX_OVERFLOW=0`.
+
 ??? info "Migrate from SQLite to PostgreSQL"
     You can migrate the existing state from SQLite to PostgreSQL using `pgloader`:
 
@@ -349,6 +354,22 @@ The bucket must be created beforehand. `dstack` won't try to create it.
     storage.objects.update
     ```
 
+## SSH proxy
+
+[`dstack-sshproxy`](https://github.com/dstackai/sshproxy) is an optional component that provides direct SSH access to workloads.
+
+Without SSH proxy, in order to connect to a job via SSH or use an IDE URL, the `dstack attach` CLI command must be used, which configures user's SSH client in a backend-specific way for each job.
+
+When SSH proxy is deployed, there is one well-known entry point – a proxy address – for all `dstack` jobs, which can be used for SSH access without any additional steps on the user's side (such as installing `dstack` and executing `dstack attach` each time). All the user has to do is to upload their public key to the `dstack` server once – there is a dedicated “SSH keys” tab on the user's page of the control plane UI.
+
+
+To deploy SSH proxy, see `dstack-sshproxy` [Deployment guide](https://github.com/dstackai/sshproxy/blob/main/DEPLOYMENT.md).
+
+To enable SSH proxy integration on the `dstack` server side, set the following environment variables:
+
+* `DSTACK_SSHPROXY_API_TOKEN` – a token used to authenticate SSH proxy API requests, must be the same value as when deploying `dstack-sshproxy`.
+* `DSTACK_SERVER_SSHPROXY_ADDRESS` – an address where SSH proxy is available to `dstack` users, in the `HOSTNAME[:PORT]` form, where `HOSTNAME` is a domain name or an IP address, and `PORT`, if not specified, defaults to 22.
+
 ## Encryption
 
 By default, `dstack` stores data in plaintext. To enforce encryption, you 
@@ -456,26 +477,14 @@ Backward compatibility is maintained based on these principles:
 
 ## Server limits
 
-A single `dstack` server replica can support:
-
-* Up to 150 active runs.
-* Up to 150 active jobs.
-* Up to 150 active instances.
+A single `dstack` server replica can support at least
 
-Having more active resources will work but can affect server performance.
-If you hit these limits, consider using Postgres with multiple server replicas.
-You can also increase processing rates of a replica by setting the `DSTACK_SERVER_BACKGROUND_PROCESSING_FACTOR` environment variable.
-You should also increase `DSTACK_DB_POOL_SIZE` and `DSTACK_DB_MAX_OVERFLOW` proportionally.
-For example, to increase processing rates 4 times, set:
-
-```
-export DSTACK_SERVER_BACKGROUND_PROCESSING_FACTOR=4
-export DSTACK_DB_POOL_SIZE=80
-export DSTACK_DB_MAX_OVERFLOW=80
-```
+* 1000 active instances
+* 1000 active runs
+* 1000 active jobs.
 
-You have to ensure your Postgres installation supports that many connections by
-configuring [`max_connections`](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-MAX-CONNECTIONS) and/or using connection pooler.
+If you hit server performance limits, try scale up server instances and/or configure Postgres with multiple server replicas.
+Also, please [submit a GitHub issue](https://github.com/dstackai/dstack/issues) describing your setup – we strive to improve `dstack` scalability and efficiency.
 
 ## Server upgrades
 

docs/guides/server-deployment/index.html

@@ -1460,6 +1460,19 @@
       </ul>
     </nav>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#ssh-proxy" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <span class="md-typeset">
+          SSH proxy
+        </span>
+      
+    </span>
+  </a>
+  
 </li>
 
         <li class="md-nav__item">
@@ -4577,6 +4590,19 @@
       </ul>
     </nav>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#ssh-proxy" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        <span class="md-typeset">
+          SSH proxy
+        </span>
+      
+    </span>
+  </a>
+  
 </li>
 
         <li class="md-nav__item">
@@ -4899,6 +4925,10 @@ <h3 id="postgresql">PostgreSQL<a class="headerlink" href="#postgresql" title="Pe
 <p>To store the server state in Postgres, set the <code>DSTACK_DATABASE_URL</code> environment variable:</p>
 <div class="highlight"><pre><span></span><code>$<span class="w"> </span><span class="nv">DSTACK_DATABASE_URL</span><span class="o">=</span>postgresql+asyncpg://user:password@db-host:5432/dstack<span class="w"> </span>dstack<span class="w"> </span>server
 </code></pre></div>
+<p>The minimum requirements for the DB instance are 2 CPU, 2GB of RAM, and at least 50 <code>max_connections</code> per server replica
+or a configured connection pooler to handle that many connections.
+If you're using a smaller DB instance, you may need to set lower <code>DSTACK_DB_POOL_SIZE</code> and <code>DSTACK_DB_MAX_OVERFLOW</code>, e.g.
+<code>DSTACK_DB_POOL_SIZE=10</code> and <code>DSTACK_DB_MAX_OVERFLOW=0</code>.</p>
 <details class="info">
 <summary>Migrate from SQLite to PostgreSQL</summary>
 <p>You can migrate the existing state from SQLite to PostgreSQL using <code>pgloader</code>:</p>
@@ -5088,6 +5118,16 @@ <h3 id="gcs">GCS<a class="headerlink" href="#gcs" title="Permanent link">&para;<
 storage.objects.update
 </code></pre></div>
 </details>
+<h2 id="ssh-proxy">SSH proxy<a class="headerlink" href="#ssh-proxy" title="Permanent link">&para;</a></h2>
+<p><a href="https://github.com/dstackai/sshproxy"><code>dstack-sshproxy</code></a> is an optional component that provides direct SSH access to workloads.</p>
+<p>Without SSH proxy, in order to connect to a job via SSH or use an IDE URL, the <code>dstack attach</code> CLI command must be used, which configures user's SSH client in a backend-specific way for each job.</p>
+<p>When SSH proxy is deployed, there is one well-known entry point – a proxy address – for all <code>dstack</code> jobs, which can be used for SSH access without any additional steps on the user's side (such as installing <code>dstack</code> and executing <code>dstack attach</code> each time). All the user has to do is to upload their public key to the <code>dstack</code> server once – there is a dedicated “SSH keys” tab on the user's page of the control plane UI.</p>
+<p>To deploy SSH proxy, see <code>dstack-sshproxy</code> <a href="https://github.com/dstackai/sshproxy/blob/main/DEPLOYMENT.md">Deployment guide</a>.</p>
+<p>To enable SSH proxy integration on the <code>dstack</code> server side, set the following environment variables:</p>
+<ul>
+<li><code>DSTACK_SSHPROXY_API_TOKEN</code> – a token used to authenticate SSH proxy API requests, must be the same value as when deploying <code>dstack-sshproxy</code>.</li>
+<li><code>DSTACK_SERVER_SSHPROXY_ADDRESS</code> – an address where SSH proxy is available to <code>dstack</code> users, in the <code>HOSTNAME[:PORT]</code> form, where <code>HOSTNAME</code> is a domain name or an IP address, and <code>PORT</code>, if not specified, defaults to 22.</li>
+</ul>
 <h2 id="encryption">Encryption<a class="headerlink" href="#encryption" title="Permanent link">&para;</a></h2>
 <p>By default, <code>dstack</code> stores data in plaintext. To enforce encryption, you 
 specify one or more encryption keys.</p>
@@ -5175,23 +5215,14 @@ <h2 id="backward-compatibility">Backward compatibility<a class="headerlink" href
 <li>The client backward compatibility is maintained across patch releases. A new minor release indicates that the release breaks client backward compatibility. This means you don't need to update the server when you update the client to a new patch release. Still, upgrading a client to a new minor version requires upgrading the server too.</li>
 </ul>
 <h2 id="server-limits">Server limits<a class="headerlink" href="#server-limits" title="Permanent link">&para;</a></h2>
-<p>A single <code>dstack</code> server replica can support:</p>
+<p>A single <code>dstack</code> server replica can support at least</p>
 <ul>
-<li>Up to 150 active runs.</li>
-<li>Up to 150 active jobs.</li>
-<li>Up to 150 active instances.</li>
+<li>1000 active instances</li>
+<li>1000 active runs</li>
+<li>1000 active jobs.</li>
 </ul>
-<p>Having more active resources will work but can affect server performance.
-If you hit these limits, consider using Postgres with multiple server replicas.
-You can also increase processing rates of a replica by setting the <code>DSTACK_SERVER_BACKGROUND_PROCESSING_FACTOR</code> environment variable.
-You should also increase <code>DSTACK_DB_POOL_SIZE</code> and <code>DSTACK_DB_MAX_OVERFLOW</code> proportionally.
-For example, to increase processing rates 4 times, set:</p>
-<div class="highlight"><pre><span></span><code>export DSTACK_SERVER_BACKGROUND_PROCESSING_FACTOR=4
-export DSTACK_DB_POOL_SIZE=80
-export DSTACK_DB_MAX_OVERFLOW=80
-</code></pre></div>
-<p>You have to ensure your Postgres installation supports that many connections by
-configuring <a href="https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-MAX-CONNECTIONS"><code>max_connections</code></a> and/or using connection pooler.</p>
+<p>If you hit server performance limits, try scale up server instances and/or configure Postgres with multiple server replicas.
+Also, please <a href="https://github.com/dstackai/dstack/issues">submit a GitHub issue</a> describing your setup – we strive to improve <code>dstack</code> scalability and efficiency.</p>
 <h2 id="server-upgrades">Server upgrades<a class="headerlink" href="#server-upgrades" title="Permanent link">&para;</a></h2>
 <p>When upgrading the <code>dstack</code> server, follow these guidelines to ensure a smooth transition and minimize downtime.</p>
 <h3 id="before-upgrading">Before upgrading<a class="headerlink" href="#before-upgrading" title="Permanent link">&para;</a></h3>

docs/reference/api/rest/openapi.json

@@ -4253,7 +4253,16 @@ <h1>REST API</h1>
 </style>
 
 <p><br></br></p>
-<p>!! SWAGGER ERROR: File rest_plugin_openapi.json not found. !!</p>
+<p><link type="text/css" rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css"></p>
+<div id="swagger-ui-2">
+</div>
+<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js" charset="UTF-8"></script>
+<script>
+    SwaggerUIBundle({
+      url: 'rest_plugin_openapi.json',
+      dom_id: '#swagger-ui-2',
+    })
+</script>
 
 
 

docs/reference/plugins/rest/index.html

@@ -6342,6 +6342,11 @@ To store the server state in Postgres, set the `DSTACK_DATABASE_URL` environment
 $ DSTACK_DATABASE_URL=postgresql+asyncpg://user:password@db-host:5432/dstack dstack server
 ```
 
+The minimum requirements for the DB instance are 2 CPU, 2GB of RAM, and at least 50 `max_connections` per server replica
+or a configured connection pooler to handle that many connections.
+If you're using a smaller DB instance, you may need to set lower `DSTACK_DB_POOL_SIZE` and `DSTACK_DB_MAX_OVERFLOW`, e.g.
+`DSTACK_DB_POOL_SIZE=10` and `DSTACK_DB_MAX_OVERFLOW=0`.
+
 ??? info "Migrate from SQLite to PostgreSQL"
     You can migrate the existing state from SQLite to PostgreSQL using `pgloader`:
 
@@ -6556,6 +6561,22 @@ The bucket must be created beforehand. `dstack` won't try to create it.
     storage.objects.update
     ```
 
+## SSH proxy
+
+[`dstack-sshproxy`](https://github.com/dstackai/sshproxy) is an optional component that provides direct SSH access to workloads.
+
+Without SSH proxy, in order to connect to a job via SSH or use an IDE URL, the `dstack attach` CLI command must be used, which configures user's SSH client in a backend-specific way for each job.
+
+When SSH proxy is deployed, there is one well-known entry point – a proxy address – for all `dstack` jobs, which can be used for SSH access without any additional steps on the user's side (such as installing `dstack` and executing `dstack attach` each time). All the user has to do is to upload their public key to the `dstack` server once – there is a dedicated “SSH keys” tab on the user's page of the control plane UI.
+
+
+To deploy SSH proxy, see `dstack-sshproxy` [Deployment guide](https://github.com/dstackai/sshproxy/blob/main/DEPLOYMENT.md).
+
+To enable SSH proxy integration on the `dstack` server side, set the following environment variables:
+
+* `DSTACK_SSHPROXY_API_TOKEN` – a token used to authenticate SSH proxy API requests, must be the same value as when deploying `dstack-sshproxy`.
+* `DSTACK_SERVER_SSHPROXY_ADDRESS` – an address where SSH proxy is available to `dstack` users, in the `HOSTNAME[:PORT]` form, where `HOSTNAME` is a domain name or an IP address, and `PORT`, if not specified, defaults to 22.
+
 ## Encryption
 
 By default, `dstack` stores data in plaintext. To enforce encryption, you 
@@ -6663,26 +6684,14 @@ Backward compatibility is maintained based on these principles:
 
 ## Server limits
 
-A single `dstack` server replica can support:
-
-* Up to 150 active runs.
-* Up to 150 active jobs.
-* Up to 150 active instances.
+A single `dstack` server replica can support at least
 
-Having more active resources will work but can affect server performance.
-If you hit these limits, consider using Postgres with multiple server replicas.
-You can also increase processing rates of a replica by setting the `DSTACK_SERVER_BACKGROUND_PROCESSING_FACTOR` environment variable.
-You should also increase `DSTACK_DB_POOL_SIZE` and `DSTACK_DB_MAX_OVERFLOW` proportionally.
-For example, to increase processing rates 4 times, set:
-
-```
-export DSTACK_SERVER_BACKGROUND_PROCESSING_FACTOR=4
-export DSTACK_DB_POOL_SIZE=80
-export DSTACK_DB_MAX_OVERFLOW=80
-```
+* 1000 active instances
+* 1000 active runs
+* 1000 active jobs.
 
-You have to ensure your Postgres installation supports that many connections by
-configuring [`max_connections`](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-MAX-CONNECTIONS) and/or using connection pooler.
+If you hit server performance limits, try scale up server instances and/or configure Postgres with multiple server replicas.
+Also, please [submit a GitHub issue](https://github.com/dstackai/dstack/issues) describing your setup – we strive to improve `dstack` scalability and efficiency.
 
 ## Server upgrades