feat(runtime-templates): add support for runtime templates in bind mounts (#412)

website/docs/3-concepts/6-services/3-runtime-templates.md

@@ -0,0 +1,91 @@
+# Runtime templates
+
+Runtime templates let service configuration use metadata that is only known when Uncloud creates a container. They use
+[Go template](https://pkg.go.dev/text/template) syntax.
+
+Uncloud renders runtime templates on the destination machine before it creates each container. This means that every
+replica can receive a value based on its own container metadata.
+
+## Available metadata
+
+Runtime templates currently expose the following fields:
+
+| Field             | Description                    | Example    |
+|-------------------|--------------------------------|------------|
+| `.Container.Name` | Name assigned to the container | `app-c1zd` |
+
+## Supported template locations
+
+You can currently use runtime templates in these locations of a service definition:
+
+| Location                        | Compose attribute                                                           |
+|---------------------------------|-----------------------------------------------------------------------------|
+| Host path of a bind mount       | `volumes[].source` or `volumes` short-syntax `- /host/path:/container/path` |
+| Mount path inside the container | `volumes[].target` or `volumes` short-syntax `- /host/path:/container/path` |
+
+:::tip Want other locations or metadata fields?
+
+If you want to use runtime templates in other locations, such as environment variable, or use other metadata fields, add
+a 👍 reaction or comment with your use case on the issue [#431](https://github.com/psviderski/uncloud/issues/431).
+
+:::
+
+## Use runtime templates in a Compose file
+
+The following service gets a separate host path for every replica:
+
+```yaml title="compose.yaml"
+services:
+  app:
+    image: app:latest
+    volumes:
+      - "/var/lib/app/{{.Container.Name}}:/data"
+    scale: 2
+```
+
+If Uncloud names the containers `app-c1zd` and `app-f7kx`, their host paths are `/var/lib/app/app-c1zd` and
+`/var/lib/app/app-f7kx`.
+
+You can combine runtime templates with
+[Compose environment interpolation](https://github.com/compose-spec/compose-spec/blob/main/12-interpolation.md):
+
+```yaml
+volumes:
+  - "${DATA_ROOT:-/var/lib/app}/{{.Container.Name}}:/data"
+```
+
+Uncloud expands the `DATA_ROOT` environment variable on the local machine first and renders `.Container.Name` later on
+the destination machine.
+
+## Use runtime templates with `uc run`
+
+Quote the volume argument so your shell passes the template through unchanged:
+
+```shell
+uc run --replicas 2 \
+  --volume "/var/lib/app/{{.Container.Name}}:/data" \
+  app:latest
+```
+
+:::warning Clean up templated host directories
+
+Uncloud does not remove host directories created for bind mounts when it replaces a container or removes a service. If a
+runtime template gives each container a unique host directory, you are responsible for cleaning up directories that are
+no longer needed.
+
+If you only need per-container ephemeral storage, consider a `tmpfs` mount. An anonymous volume declared by the Docker
+image can also provide Docker-managed disk storage for each container. Use a named volume or a stable bind mount path
+for data that must remain available across container replacements.
+
+:::
+
+## Runtime templates and image tag templates
+
+Runtime templates are separate from [image tag templates](../../8-compose-file-reference/3-image-tag-template.md). Image
+tag templates run locally when Uncloud builds an image. Runtime templates run on a cluster machine when Uncloud deploys
+a container. Each template type exposes different metadata.
+
+## See also
+
+- [Compose support matrix](../../8-compose-file-reference/1-support-matrix.md)
+- [`uc run` reference](../../9-cli-reference/uc_run.md)

website/docs/8-compose-file-reference/1-support-matrix.md

@@ -64,7 +64,7 @@ If you rely on a specific Compose feature that is not supported by Uncloud, plea
 | `update_config`                  | ⚠️ Limited         | `order` and `monitor` supported. See [rolling deployments](../4-guides/1-deployments/4-rolling-deployments.md)                             |
 | **Volumes**                      |                    |                                                                                                                                            |
 | Named volumes                    | ✅ Supported        | Docker volumes                                                                                                                             |
-| Bind mounts                      | ✅ Supported        | Host path binding                                                                                                                          |
+| Bind mounts                      | ✅ Supported        | Host path binding with optional [runtime templates](../3-concepts/6-services/3-runtime-templates.md)                                       |
 | Tmpfs mounts                     | ✅ Supported        | In-memory filesystems                                                                                                                      |
 | Volume labels                    | ✅ Supported        | Custom labels                                                                                                                              |
 | External volumes                 | ✅ Supported        | Must exist before deployment                                                                                                               |

website/docs/8-compose-file-reference/3-image-tag-template.md

@@ -143,6 +143,7 @@ image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}   # GITHUB_RUN_ID not set →
 
 ## See also
 
+- [Runtime templates](../3-concepts/6-services/3-runtime-templates.md): Use per-container metadata in service configuration
 - [Deploy an app](../4-guides/1-deployments/1-deploy-app.md): Deploy from source code or pre-built images
 - [Compose Build Specification](https://github.com/compose-spec/compose-spec/blob/main/build.md)
 - [Compose Specification: image](https://github.com/compose-spec/compose-spec/blob/main/spec.md#image)

website/docs/9-cli-reference/uc_run.md

@@ -47,6 +47,7 @@ uc run IMAGE [COMMAND...] [flags]
   -v, --volume strings      Mount a data volume or host path into service containers. Service containers will be scheduled on the machine(s) where
                             the volume is located. Can be specified multiple times.
                             Format: volume_name:/container/path[:ro|volume-nocopy] or /host/path:/container/path[:ro]
+                            Host and container paths support runtime templates such as {{.Container.Name}}.
                             Examples:
                               -v postgres-data:/var/lib/postgresql/data  Mount volume 'postgres-data' to /var/lib/postgresql/data in container
                               -v /data/uploads:/app/uploads         	 Bind mount /data/uploads host directory to /app/uploads in container

website/docs/9-cli-reference/uc_service_run.md

@@ -47,6 +47,7 @@ uc service run IMAGE [COMMAND...] [flags]
   -v, --volume strings      Mount a data volume or host path into service containers. Service containers will be scheduled on the machine(s) where
                             the volume is located. Can be specified multiple times.
                             Format: volume_name:/container/path[:ro|volume-nocopy] or /host/path:/container/path[:ro]
+                            Host and container paths support runtime templates such as {{.Container.Name}}.
                             Examples:
                               -v postgres-data:/var/lib/postgresql/data  Mount volume 'postgres-data' to /var/lib/postgresql/data in container
                               -v /data/uploads:/app/uploads         	 Bind mount /data/uploads host directory to /app/uploads in container