docs: split 'Deploy to specific machines' and 'Deploy a global service' into separate guides

website/docs/4-guides/1-deployments/1-deploy-app.md

@@ -11,12 +11,12 @@ This guide covers both scenarios:
 
 Uncloud uses [Compose Specification](https://compose-spec.io/) for defining the deployment configuration of your app's
 services. It implements the most common Compose features with some Uncloud-specific extensions. See
-[Compose support matrix](../8-compose-file-reference/1-support-matrix.md) for details.
+[Compose support matrix](../../8-compose-file-reference/1-support-matrix.md) for details.
 
 ## Prerequisites
 
-- `uc` CLI [installed](../2-getting-started/1-install-cli.md) on your local machine
+- `uc` CLI [installed](../../2-getting-started/1-install-cli.md) on your local machine
-- An Uncloud cluster with at least one machine (see [Quick start](../2-getting-started/2-deploy-demo-app.md))
+- An Uncloud cluster with at least one machine (see [Quick start](../../2-getting-started/2-deploy-demo-app.md))
 - Basic knowledge of [Compose Specification](https://compose-spec.io/)
 
 ## Deploy from source code
@@ -62,7 +62,7 @@ This command looks for a Compose file in your current working directory and:
 5. **Deploys service containers** using the built images and latest configuration changes with zero-downtime rolling
    updates
 
-See the [uc deploy](../9-cli-reference/uc_deploy.md) reference for all available options.
+See the [uc deploy](../../9-cli-reference/uc_deploy.md) reference for all available options.
 
 Watch `uc deploy` building and deploying a demo app (18 seconds):
 
@@ -140,7 +140,7 @@ This generates tags like:
 `uc deploy` renders the image templates when it loads the Compose file and then uses the resulting names for the build
 and deploy stages.
 
-See the [Image tag format](../8-compose-file-reference/2-image-tag-format.md) reference for all available template
+See the [Image tag format](../../8-compose-file-reference/2-image-tag-format.md) reference for all available template
 variables and functions.
 
 ### Separate build and deploy steps
@@ -251,7 +251,7 @@ machines. For example, images you built locally outside of the Compose workflow
 is unreachable from your cluster machines. This is useful for deploying to air-gapped or restricted environments.
 
 You can push these local images directly to your cluster machines using the
-[`uc image push`](../9-cli-reference/uc_image_push.md) command:
+[`uc image push`](../../9-cli-reference/uc_image_push.md) command:
 
 ```shell
 # Push to *all* cluster machines
@@ -276,7 +276,7 @@ services:
     pull_policy: never
 ```
 
-Run [`uc images`](../9-cli-reference/uc_images.md) to verify that the image is available on the target machines.
+Run [`uc images`](../../9-cli-reference/uc_images.md) to verify that the image is available on the target machines.
 
 Then deploy as usual:
 
@@ -321,86 +321,6 @@ Choose unique names to avoid conflicts with services deployed from other Compose
 
 :::
 
-## Deploy to specific machines
-
-By default, Uncloud randomly chooses available machines to run your services on, spreading multiple replicas of a
-service across all machines for high availability. You can restrict which machines can run your service using the
-[`x-machines`](../8-compose-file-reference/1-support-matrix.md#x-machines) extension in your Compose file.
-
-This is useful when you want to:
-
-- Deploy services to machines in a specific region or data center
-- Run services only on machines with specific hardware (for example, GPUs or ARM processors)
-- Keep certain services isolated to dedicated machines
-- Deploy to a subset of machines for testing before rolling out cluster-wide
-
-Here's a basic example:
-
-```yaml
-services:
-  web:
-    build: .
-    x-ports:
-      - app.example.com:8000/https
-    # Spread 3 replicas across machine-1 and machine-2 only
-    scale: 3
-    x-machines:
-      - machine-1
-      - machine-2
-
-  db:
-    image: postgres:18
-    environment:
-      POSTGRES_PASSWORD: ${DB_PASSWORD}
-    volumes:
-      - db-data:/var/lib/postgresql
-    # Create the db-data volume and run the DB container on machine-db
-    x-machines: machine-db
-
-volumes:
-  db-data:
-```
-
-When you deploy this Compose file with `uc deploy`:
-
-- The `web` service will create and spread its 3 replicas only across `machine-1` and `machine-2`
-- The `db` service will create its `db-data` volume and run only on `machine-db`
-
-:::tip
-
-Use [`uc machine ls`](../9-cli-reference/uc_machine_ls.md) to see available machines in your cluster.
-
-:::
-
-### Push images to specific machines only
-
-When building from source, `uc deploy` and `uc build --push` automatically push images to **all** cluster machines by
-default. This ensures images are available wherever services might be deployed.
-
-If you're using `x-machines` to restrict deployments to specific machines, `uc deploy` and `uc build --push` push images
-only to those machines. This saves time and bandwidth by uploading images only where they're needed.
-
-## Run one replica on each machine
-
-To deploy exactly one service replica on each machine in your cluster, set
-[`mode: global`](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#mode) under the `deploy` section. It's
-useful for cluster-wide services like monitoring agents, log collectors, or reverse proxies.
-
-You can also combine `mode: global` with `x-machines` to run one container on each machine in a specific set.
-
-```yaml
-services:
-  monitoring:
-    image: quay.io/prometheus/node-exporter:latest
-    deploy:
-      # Run one container on each machine in the cluster
-      mode: global
-    # Optionally run one container on each of these specific machines only
-    #x-machines:
-    #  - machine-1
-    #  - machine-2
-```
-
 ## Use a different Compose file location
 
 If your Compose file has a different name or location, use the `-f/--file` flag to specify its path:
@@ -432,3 +352,11 @@ and inspecting the status of containers for a specific service:
 ```shell
 uc inspect web
 ```
+
+# See also
+
+- [Deploy to specific machines](2-deploy-specific-machines.md): Deploy services to specific machines in your cluster
+- [Deploy a global service](3-deploy-global-services.md): Deploy one service replica on each cluster machine
+- [Compose Specification](https://compose-spec.io/): Official specification for the Compose file format
+- [Compose support matrix](../../8-compose-file-reference/1-support-matrix.md): Supported Compose features and Uncloud
+  extensions

website/docs/4-guides/1-deployments/2-deploy-specific-machines.md

@@ -0,0 +1,84 @@
+# Deploy to specific machines
+
+Deploy services to specific machines in your cluster using the
+[`x-machines`](../../8-compose-file-reference/1-support-matrix.md#x-machines) extension in your Compose file.
+
+## When to target specific machines
+
+By default, Uncloud randomly chooses available machines to run your services on, evenly spreading multiple replicas of a
+service across all machines for high availability. You can restrict which machines can run your service using the
+[`x-machines`](../../8-compose-file-reference/1-support-matrix.md#x-machines) extension in your Compose file.
+
+This is useful when you want to:
+
+- Deploy services to machines in a **specific region** or **data center**
+- Run services only on machines with **specific hardware** (for example, GPUs or ARM processors)
+- Specify where to deploy **stateful services** and create their data volumes
+- Keep certain services isolated to **dedicated machines**
+- Deploy to a subset of machines for **testing** before rolling out cluster-wide
+
+## Target machines in a Compose file
+
+Set `x-machines` to a list of machine names or a single machine name to restrict which machines a service can run on.
+
+```yaml title="compose.yaml"
+services:
+  web:
+    build: .
+    x-ports:
+      - app.example.com:8000/https
+    # Spread 3 replicas across machine-1 and machine-2 only
+    x-machines:
+      - machine-1
+      - machine-2
+    scale: 3
+
+  db:
+    image: postgres:18
+    environment:
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - db-data:/var/lib/postgresql
+    # Create the db-data volume and run the DB container on machine-db
+    x-machines: machine-db
+
+volumes:
+  db-data:
+```
+
+When you deploy this Compose file with [`uc deploy`](../../9-cli-reference/uc_deploy.md):
+
+- The `web` service will create and spread its 3 replicas only across `machine-1` and `machine-2`
+- The `db` service will create its `db-data` volume and run only on `machine-db`
+
+:::tip
+
+Use [`uc machine ls`](../../9-cli-reference/uc_machine_ls.md) to see available machines in your cluster.
+
+:::
+
+## Push images to specific machines only
+
+When [building from source](1-deploy-app.md#deploy-from-source-code), `uc deploy` and `uc build --push` automatically
+push built images to **all** cluster machines by default. This ensures images are available wherever services might be
+deployed.
+
+If you're using `x-machines` to restrict deployments to specific machines, `uc deploy` and `uc build --push` push images
+**only to those** machines. This saves time and bandwidth by uploading images only where they're needed.
+
+You can also manually push your local Docker images to specific machines using the [
+`uc image push`](../../9-cli-reference/uc_image_push.md) command:
+
+```shell
+# Push the local Docker image 'myapp:latest' to machine-1 and machine-2
+uc image push myapp:latest -m machine-1,machine-2
+```
+
+See [Push local images to cluster machines](1-deploy-app.md#push-local-images-to-cluster-machines) for more details.
+
+## See also
+
+- [Deploy a global service](3-deploy-global-services.md): Deploy one service replica on each cluster machine
+- [Deploy an app](1-deploy-app.md): Deploy from source code or prebuilt images
+- [Compose support matrix](../../8-compose-file-reference/1-support-matrix.md): Supported Compose features and Uncloud
+  extensions

website/docs/4-guides/1-deployments/3-deploy-global-services.md

@@ -0,0 +1,68 @@
+# Deploy a global service
+
+Deploy exactly one replica of a service on each machine in your cluster.
+
+This is useful for cluster-wide infrastructure services like monitoring or security agents, log collectors, or reverse
+proxies.
+
+## Deploy to all machines
+
+To deploy exactly one replica on each machine in your cluster for a specific service, set
+[`mode: global`](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#mode) under the `deploy` section in
+your Compose file:
+
+```yaml title="compose.yaml"
+services:
+  monitoring:
+    image: quay.io/prometheus/node-exporter:latest
+    deploy:
+      # Run one container on each machine in the cluster
+      mode: global
+```
+
+Then deploy:
+
+```shell
+uc deploy
+```
+
+Before creating replicas on cluster machines, it will show you a deployment plan and ask for confirmation.
+
+If you add more machines to the cluster later, you need to run `uc deploy` again to create replicas on the new machines.
+Uncloud doesn't automatically scale global services to new machines.
+
+## Deploy to a subset of machines
+
+You can combine the `global` mode with [`x-machines`](../../8-compose-file-reference/1-support-matrix.md#x-machines)
+to deploy one container to each specified machine:
+
+```yaml title="compose.yaml"
+services:
+  caddy:
+    image: caddy:2
+    deploy:
+      # Run one container on each of the three specified machines
+      mode: global
+    x-machines:
+      - ingress-1
+      - ingress-2
+      - ingress-3
+```
+
+This is useful when you want a service on a specific group of machines (for example, ingress or GPU machines) but still
+want the one-per-machine guarantee that global mode provides.
+
+## Global vs replicated mode
+
+The default mode is `replicated`, where you specify the number of replicas.
+
+| Mode                   | Replicas                                      | Placement                                                           |
+|------------------------|-----------------------------------------------|---------------------------------------------------------------------|
+| `replicated` (default) | You specify with `scale` or `deploy.replicas` | Uncloud evenly spreads replicas across all machines or `x-machines` |
+| `global`               | Always one per machine                        | One replica on each machine or each `x-machines` machine            |
+
+## See also
+
+- [Deploy to specific machines](2-deploy-specific-machines.md): Deploy services to specific machines in your cluster
+- [Compose Specification: deploy.mode](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#mode):
+  Compose specification for deployment modes

website/docs/4-guides/1-deployments/_category_.yaml

@@ -0,0 +1,4 @@
+label: Deployments
+collapsed: false # keep the category open by default
+link:
+  type: generated-index