- [Docs]: Minor updates under Concepts

- [Landing]: Minor styling changes; added `Pools`
dstackai · Mar 4, 2024 · bc5dc6b · bc5dc6b
1 parent 5b34e3d
commit bc5dc6b
Show file tree

Hide file tree

Showing 16 changed files with 330 additions and 131 deletions.
diff --git a/README.md b/README.md
@@ -81,23 +81,39 @@ Below is a live demo of how it works with the CLI.
 
 ### Dev environments
 
-Dev environments allow you to quickly provision a machine with a pre-configured environment, resources, IDE, code, etc.
+You specify the required environment and resources, then run it. dstack provisions the dev
+environment in the cloud and enables access via your desktop IDE.
 
 <img src="https://raw.githubusercontent.com/dstackai/static-assets/main/static-assets/images/dstack-dev-environment.gif" width="650"/>
 
 ### Tasks
 
-Tasks are perfect for scheduling all kinds of jobs (e.g., training, fine-tuning, processing data, batch inference, etc.)
-as well as running web applications.
+Tasks allow for convenient scheduling of any kind of batch jobs, such as training, fine-tuning,
+or data processing, as well as running web applications.
+
+Specify the environment and resources, then run it. dstack executes the task in the
+cloud, enabling port forwarding to your local machine for convenient access.
 
 <img src="https://raw.githubusercontent.com/dstackai/static-assets/main/static-assets/images/dstack-task.gif" width="650"/>
 
 ### Services
 
-Services make it very easy to deploy any model or web application as a public endpoint.
+Services make it very easy to deploy any kind of model or web application as public endpoints.
+
+Use any serving frameworks and specify required resources. dstack deploys it in the configured
+backend, handles authentication, and provides an OpenAI-compatible interface if needed.
 
 <img src="https://raw.githubusercontent.com/dstackai/static-assets/main/static-assets/images/dstack-service-openai.gif" width="650"/>
 
+### Pools
+
+Pools simplify managing the lifecycle of cloud instances and enable their efficient reuse across runs.
+
+You can have instances provisioned in the cloud automatically, or add them manually, configuring the required resources,
+idle duration, etc.
+
+<img src="https://raw.githubusercontent.com/dstackai/static-assets/main/static-assets/images/dstack-pool.gif" width="650"/>
+
 ## Examples
 
 Here are some featured examples:

diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css
@@ -43,9 +43,28 @@
 .md-footer {
     /*border-top: 1px solid #E4E4E7;*/
 }
-.md-footer__link {
-    margin: 1rem 0 0.4rem;
+.md-typeset a.md-footer__link {
+    margin: 0.5rem 0 0.4rem;
+    border: 0.5px solid black;
+    color: black;
+    border-radius: 5px;
+    flex: 1;
+}
+
+.md-typeset a.md-footer__link:hover {
+    color: var(--md-typeset-a-color);
+    opacity: 1;
+}
+
+.md-footer__link--prev .md-footer__title {
+    display: block;
+}
+
+.md-footer__title {
+    margin-top: 0.2rem;
+    margin-bottom: 0.5rem;
 }
+
 .md-header[data-md-state=shadow] {
     box-shadow: none;
 }
@@ -493,6 +512,11 @@ code .md-code__nav:hover .md-code__button {
 
 .footer__inner {
     background-color: var(--md-footer-bg-color--dark);
+    margin-top: 0.7rem;
+}
+
+.md-footer__inner:not([hidden]) {
+    gap: 20px !important;
 }
 
 .md-footer__link .md-footer__link--next {
@@ -1070,6 +1094,14 @@ html .md-footer-meta.md-typeset a:is(:focus,:hover) {
         padding-left: 3px;
     }*/
 
+    .tx-footer__section-link.external:after {
+        content: url('data:image/svg+xml,<svg width="16" height="16" viewBox="1 1 27 27" xmlns="http://www.w3.org/2000/svg" fill="rgba(0,0,0,0.87)" stroke="rgba(0,0,0,0.87)" stroke-width="0.75" stroke-linecap="round" stroke-linejoin="round"><path d="M23.5 23.5h-15v-15h4.791V6H6v20h20v-7.969h-2.5z"/><path d="M17.979 6l3.016 3.018-6.829 6.829 1.988 1.987 6.83-6.828L26 14.02V6z"/></svg>');
+        line-height: 14px;
+        padding-left: 3px;
+        position: relative;
+        top: 1px;
+    }
+
     .md-tabs__item:nth-child(5) .md-tabs__link:before {
         content: url('data:image/svg+xml,<svg width="37" height="35" viewBox="0 0 256 200" version="1.1" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><g><path d="M216.856339,16.5966031 C200.285002,8.84328665 182.566144,3.2084988 164.041564,0 C161.766523,4.11318106 159.108624,9.64549908 157.276099,14.0464379 C137.583995,11.0849896 118.072967,11.0849896 98.7430163,14.0464379 C96.9108417,9.64549908 94.1925838,4.11318106 91.8971895,0 C73.3526068,3.2084988 55.6133949,8.86399117 39.0420583,16.6376612 C5.61752293,67.146514 -3.4433191,116.400813 1.08711069,164.955721 C23.2560196,181.510915 44.7403634,191.567697 65.8621325,198.148576 C71.0772151,190.971126 75.7283628,183.341335 79.7352139,175.300261 C72.104019,172.400575 64.7949724,168.822202 57.8887866,164.667963 C59.7209612,163.310589 61.5131304,161.891452 63.2445898,160.431257 C105.36741,180.133187 151.134928,180.133187 192.754523,160.431257 C194.506336,161.891452 196.298154,163.310589 198.110326,164.667963 C191.183787,168.842556 183.854737,172.420929 176.223542,175.320965 C180.230393,183.341335 184.861538,190.991831 190.096624,198.16893 C211.238746,191.588051 232.743023,181.531619 254.911949,164.955721 C260.227747,108.668201 245.831087,59.8662432 216.856339,16.5966031 Z M85.4738752,135.09489 C72.8290281,135.09489 62.4592217,123.290155 62.4592217,108.914901 C62.4592217,94.5396472 72.607595,82.7145587 85.4738752,82.7145587 C98.3405064,82.7145587 108.709962,94.5189427 108.488529,108.914901 C108.508531,123.290155 98.3405064,135.09489 85.4738752,135.09489 Z M170.525237,135.09489 C157.88039,135.09489 147.510584,123.290155 147.510584,108.914901 C147.510584,94.5396472 157.658606,82.7145587 170.525237,82.7145587 C183.391518,82.7145587 193.761324,94.5189427 193.539891,108.914901 C193.539891,123.290155 183.391518,135.09489 170.525237,135.09489 Z" fill="currentColor" fill-rule="nonzero"></path></g></svg>');
     }

diff --git a/docs/assets/stylesheets/landing.css b/docs/assets/stylesheets/landing.css
@@ -203,7 +203,7 @@
 
 .tx-container .md-button.small {
     min-width: 175px;
-    padding: 0.4em 1.7em;
+    padding: 0.6em 2em;
     font-size: 20px;
 }
 
@@ -229,9 +229,11 @@
     transform: translateX(3px)
 }
 
-.md-header__buttons .md-button--primary,
-.tx-container .md-button--primary {
-    background: -webkit-linear-gradient(45deg, #002aff, #002aff, #e165fe);
+.md-header__buttons .md-button--primary, .md-header__buttons .md-button--primary:hover,
+.tx-container .md-button--primary, .tx-container .md-button--primary:hover {
+    background: rgba(0, 0, 0, 0.87);
+    border: 1.5px solid black;
+    border-radius: 3px;
 }
 
 .md-header__buttons .md-button--primary,
@@ -241,7 +243,9 @@
 }
 
 .md-header__buttons .md-button-secondary,
-.tx-container .md-button-secondary {
+.tx-container .md-button-secondary,
+.md-header__buttons .md-button-secondary:hover,
+.tx-container .md-button-secondary:hover {
     border-image: linear-gradient(45deg, #0048ff, #ce00ff) 10;
     border-width: 1.5px;
     border-style: solid;
@@ -260,13 +264,6 @@
     font-size: 0.85rem;
 }
 
-.md-header__buttons .md-button-secondary:hover,
-.tx-container .md-button-secondary:hover {
-    background: -webkit-linear-gradient(45deg, #0048ff, #ce00ff);
-    -webkit-background-clip: text;
-    -webkit-text-fill-color: transparent;
-}
-
 @media screen and (max-width: 76.1875em) {
     /*.md-header .md-header__buttons {
         display: none;
@@ -308,8 +305,8 @@
 }
 
 .tx-landing__highlights_grid .feature-cell {
-    padding: 35px 40px 40px;
-    border-radius: 5px;
+    padding: 40px 35px 40px 40px;
+    border-radius: 0;
     border-image: linear-gradient(45deg, #0048ff, #ce00ff) 10;
     border-width: 0.75px;
     border-style: solid;
@@ -344,7 +341,8 @@
     line-height: 1.44;
     color: black;
     margin-top: 10px;
-    background: -webkit-linear-gradient(45deg, rgba(0, 42, 255, 0.05), rgba(0, 42, 255, 0.05), rgba(225, 101, 254, 0.05));
+    border: 0.5px solid black;
+    margin-right: 10px;
 }
 
 .tx-landing__highlights_grid > a, .tx-landing__highlights_grid > a:hover {
@@ -408,14 +406,17 @@
 }
 
 .tx-landing__highlights_grid h3 {
-    font-size: 1.3em;
+    font-size: 1.2em;
     font-weight: 800;
     border-bottom: none;
     padding-bottom: 0.1em;
     margin-top: 0;
-    background: -webkit-linear-gradient(45deg, #6e14ed, #bf04e9, #bf04e9);
-    -webkit-background-clip: text;
-    -webkit-text-fill-color: transparent;
+}
+
+.tx-landing__highlights_grid p {
+    font-size: 17px;
+    margin-top: 20px;
+    margin-bottom: 20px;
 }
 
 .tx-landing__features {
@@ -471,7 +472,7 @@
     max-width: 500px;
     margin-top: 0.75em;
     margin-bottom: 0.75em;
-    background: -webkit-linear-gradient(45deg, #ff00ff, #8500ff);
+    background: var(--md-typeset-a-color);
     -webkit-background-clip: text;
     -webkit-text-fill-color: transparent;
     letter-spacing: -1.5px;
@@ -519,8 +520,15 @@
     margin-bottom: 2rem;
 }
 
-.tx-footer .md-main__inner {
+.tx-footer {
     padding-top: 2.5rem;
+}
+
+.md-footer__inner {
+    padding: 0;
+}
+
+.tx-footer .md-main__inner {
     border-width: 0;
     /*border-top-width: 0.6px;*/
     border-image: linear-gradient(45deg, #0048ff, #ce00ff) 10;
@@ -608,33 +616,33 @@
     text-align: center;
 }
 
-.tx-landing__plans_text h2 .gradient {
-    background: linear-gradient(90deg, #4631C8 -1.29%, #CD4AE2 88.05%, #FFD43C 111.26%);
-    -webkit-background-clip: text;
-    -webkit-text-fill-color: transparent;
-    padding-right: 4px;
-    margin-right: -4px;
-}
-
 .tx-landing__plans_cards {
     display: grid;
     flex-wrap: wrap;
     gap: 2rem;
     grid-template-columns: repeat(auto-fill, minmax(15rem, 1fr));
 }
 
+.md-header__buttons .md-button--primary.sky, .md-header__buttons .md-button--primary.sky:hover,
+.tx-container .md-button--primary.sky, .tx-container .md-button--primary.sky:hover {
+    background: -webkit-linear-gradient(45deg, #002aff, #002aff, #e165fe);
+    border-radius: 3px;
+    border: 1px solid transparent;
+}
+
 .plans_card.dstack_sky {
-    background: -webkit-linear-gradient(45deg, rgba(0, 42, 255, 0.025), rgba(225, 101, 254, 0.025));
-    border-image: -webkit-linear-gradient(45deg, rgba(0, 42, 255, 0.75), rgba(225, 101, 254, 0.75)) 10;
+    background: -webkit-linear-gradient(45deg, rgba(0, 42, 255, 0.015), rgba(0, 42, 255, 0.015), rgba(225, 101, 254, 0.025));
+    border-color: #0048ff;
+    border-image: none;
 }
 
 .plans_card {
     display: flex;
     flex-direction: column;
-    max-width: 445px;
+    /*min-width: 445px;*/
     width: 100%;
-    border-radius: 5px;
-    border-image: linear-gradient(45deg, #0048ff, #ce00ff) 10;
+    border-color: black;
+    border-radius: 0;
     border-width: 0.5px;
     border-style: solid;
     padding: 38px 20px 38px 46px

diff --git a/docs/docs/concepts/dev-environments.md b/docs/docs/concepts/dev-environments.md
@@ -3,8 +3,8 @@
 Before submitting a task or deploying a model, you may want to run code interactively.
 Dev environments allow you to do exactly that. 
 
-You just specify the required environment, resources, and run it. `dstack` provisions the dev environment
-in a configured backend.
+You specify the required environment and resources, then run it. `dstack` provisions the dev
+environment in the configured backend and enables access via your desktop IDE.
 
 ## Define a configuration
 

diff --git a/docs/docs/concepts/pools.md b/docs/docs/concepts/pools.md
@@ -1,41 +1,33 @@
 # Pools
 
-Pools enable efficient lifecycle management of cloud instances and their reuse across runs.
+Pools simplify managing the lifecycle of cloud instances and enable their efficient reuse across runs.
 
-- When an instance is provisioned in a configured backend, it is added to a pool.
-- The instance is marked as busy while it runs the workload.
-- Once the workload is finished, the instance is marked as ready (to run other workloads).
-- If the instance remains idle for the configured duration, `dstack` tears it down.
+You can have instances provisioned in the configured backend automatically when you run a workload, or add them
+manually, configuring the required resources, idle duration, etc.
 
-## `dstack run`
+## Adding instances
 
-By default, when you use the `dstack run` command, it attempts to reuse an instance from a pool. If there is no ready
-instance that meets the requirements, `dstack` automatically provisions a new instance.
+### `dstack run`
 
-To solely use existing instances, pass the `--reuse` argument. In this scenario, the run will be assigned to an instance
-once it's ready.
+By default, when using the `dstack run` command, it tries to reuse an instance from a pool. If no idle instance meets the
+requirements, `dstack` automatically provisions a new one and adds it to the pool.
 
-!!! info "Idle duration"
-    By default, if `dstack run` provisions a new instance, its idle duration is set to `5m`. This means the instance waits for a
-    new workload for only five minutes before getting torn down.
-    To override it, use the `--idle-duration DURATION` argument.
-
-## `dstack pool`
-
-The `dstack pool` command allows for managing instances within pools as well as managing the pools themselves.
+To avoid provisioning new instances with `dstack run`, use `--reuse`. Your run will be assigned to an idle instance in 
+the pool.
 
-#### List instances 
-
-The [`dstack pool ps`](../reference/cli/index.md#dstack-pool-ps) command lists all active instances and their status.
+!!! info "Idle duration"
+    By default, `dstack run` sets the idle duration of a newly provisioned instance to `5m`.
+    This means that if the run is finished and the instance remains idle for longer than five minutes, it is automatically
+    removed from the pool. To override the default idle duration, use  `--idle-duration DURATION` with `dstack run`.
 
-#### Add instances 
+### `dstack pool add` 
 
 To manually add an instance to a pool, use [`dstack pool add`](../reference/cli/index.md#dstack-pool-add):
 
 <div class="termy">
 
 ```shell
-$ dstack pool add --gpu 80GB --idle-duration 1d
+$ dstack pool add --gpu 80GB
 
  BACKEND     REGION         RESOURCES                     SPOT  PRICE
  tensordock  unitedkingdom  10xCPU, 80GB, 1xA100 (80GB)   no    $1.595
@@ -50,18 +42,24 @@ Continue? [y/n]: y
 The `dstack pool add` command allows specifying resource requirements, along with the spot policy, idle duration, max
 price, retry policy, and other policies.
 
+The default idle duration if you're using `dstack pool add` is `72h`. To override it, use the `--idle-duration DURATION` argument.
+
 [//]: # (TODO: Mention the retry policy)
 
-Alternatively, you can specify these policies via [`.dstack/profiles.yml`](../reference/profiles.yml.md) instead of passing them as arguments.
+You can also specify the policies via [`.dstack/profiles.yml`](../reference/profiles.yml.md) instead of passing them as arguments.
 For more details on policies and their defaults, refer to [`.dstack/profiles.yml`](../reference/profiles.yml.md).
 
 ??? info "Limitations"
-    The `dstack pool add` command is not yet supported for Lambda, Azure, TensorDock, Kubernetes, and VastAI backends. Support
-    for them is coming in version `0.16.1`.
+    The `dstack pool add` command is not supported for Kubernetes, and VastAI backends yet.
 
-#### Remove instances
+## Removing instances
 
-To remove an instance from a pool, use the `dstack pool remove` command. 
+!!! info "Idle duration"
+    If the instance remains idle for the configured duration, `dstack` removes it and deletes all cloud resources.
+
+### `dstack pool remove`
+
+To remove an instance from the pool manually, use the `dstack pool remove` command. 
 
 <div class="termy">
 
@@ -71,8 +69,10 @@ $ dstack pool remove &lt;instance name&gt;
 
 </div>
 
-!!! info "Idle time"
-    If the instance remains idle for the configured duration, `dstack` removes it and deletes all cloud resources.
+## Listing instances 
+
+The [`dstack pool ps`](../reference/cli/index.md#dstack-pool-ps) command lists active instances and their status (`busy`
+or `idle`).
 
 [//]: # (#### Manage pools)
 

diff --git a/docs/docs/concepts/services.md b/docs/docs/concepts/services.md
@@ -1,9 +1,9 @@
 # Services
 
-Services make it very easy to deploy any model or web application as a public endpoint.
+Services make it very easy to deploy any kind of model or web application as public endpoints.
 
-Regardless of which model you deploy or which serving framework you use,
-it's possible to offer the model via the OpenAI-compatible interface.
+Use any serving frameworks and specify required resources. `dstack` deploys it in the configured backend, handles
+authentication, and provides an OpenAI-compatible interface if needed.
 
 [//]: # (TODO: Support auto-scaling)