diff --git a/website/docs/4-guides/1-deployments/1-deploy-app.md b/website/docs/4-guides/1-deployments/1-deploy-app.md index 225c9739..34c5cf90 100644 --- a/website/docs/4-guides/1-deployments/1-deploy-app.md +++ b/website/docs/4-guides/1-deployments/1-deploy-app.md @@ -141,7 +141,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 template](../../8-compose-file-reference/2-image-tag-template.md) reference for all available +See the [Image tag template](../../8-compose-file-reference/3-image-tag-template.md) reference for all available template variables and functions. ### Separate build and deploy steps @@ -338,7 +338,7 @@ services: With this configuration, `uc deploy` and other commands using the Compose file will always target the `prod` context, regardless of your currently active context. You can still override it with the `--context` flag if needed. -See [`x-context`](../../8-compose-file-reference/1-support-matrix.md#x-context) for more details. +See [`x-context`](../../8-compose-file-reference/2-extensions.md#x-context) for more details. ## Use a different Compose file location diff --git a/website/docs/4-guides/1-deployments/2-deploy-specific-machines.md b/website/docs/4-guides/1-deployments/2-deploy-specific-machines.md index 04a56a7c..9c1d757e 100644 --- a/website/docs/4-guides/1-deployments/2-deploy-specific-machines.md +++ b/website/docs/4-guides/1-deployments/2-deploy-specific-machines.md @@ -1,13 +1,13 @@ # 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. +[`x-machines`](../../8-compose-file-reference/2-extensions.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. +[`x-machines`](../../8-compose-file-reference/2-extensions.md#x-machines) extension in your Compose file. This is useful when you want to: diff --git a/website/docs/4-guides/1-deployments/3-deploy-global-services.md b/website/docs/4-guides/1-deployments/3-deploy-global-services.md index 68e7e2ee..3f6b6767 100644 --- a/website/docs/4-guides/1-deployments/3-deploy-global-services.md +++ b/website/docs/4-guides/1-deployments/3-deploy-global-services.md @@ -33,7 +33,7 @@ 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) +You can combine the `global` mode with [`x-machines`](../../8-compose-file-reference/2-extensions.md#x-machines) to deploy one container to each specified machine: ```yaml title="compose.yaml" diff --git a/website/docs/4-guides/1-deployments/5-pre-deploy-hooks.md b/website/docs/4-guides/1-deployments/5-pre-deploy-hooks.md index d9727d04..41a47f0e 100644 --- a/website/docs/4-guides/1-deployments/5-pre-deploy-hooks.md +++ b/website/docs/4-guides/1-deployments/5-pre-deploy-hooks.md @@ -29,7 +29,7 @@ changes do not persist after the hook finishes, except for changes written to sh ## Usage -Add the [`x-pre_deploy`](../../8-compose-file-reference/1-support-matrix.md#x-pre_deploy) extension to a service in your +Add the [`x-pre_deploy`](../../8-compose-file-reference/2-extensions.md#x-pre_deploy) extension to a service in your Compose file. The only required attribute is `command`, which can be a string or a list of strings, just like the service's [`command`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#command). @@ -54,7 +54,7 @@ hook and regular service containers. Since your command runs in the same image as the service, any tools or dependencies it needs must be installed in that image. -See [`x-pre_deploy`](../../8-compose-file-reference/1-support-matrix.md#x-pre_deploy) for all available attributes and +See [`x-pre_deploy`](../../8-compose-file-reference/2-extensions.md#x-pre_deploy) for all available attributes and their defaults. ### Database migrations @@ -203,7 +203,7 @@ Most database migration tools handle this naturally since they track which migra ## See also -- [`x-pre_deploy` reference](../../8-compose-file-reference/1-support-matrix.md#x-pre_deploy): All available attributes +- [`x-pre_deploy` reference](../../8-compose-file-reference/2-extensions.md#x-pre_deploy): All available attributes and their defaults - [Rolling deployments](4-rolling-deployments.md): How Uncloud updates containers with zero downtime - [Deploy an app](1-deploy-app.md): Build and deploy from source code or pre-built images diff --git a/website/docs/8-compose-file-reference/1-support-matrix.md b/website/docs/8-compose-file-reference/1-support-matrix.md index bea34114..9f529228 100644 --- a/website/docs/8-compose-file-reference/1-support-matrix.md +++ b/website/docs/8-compose-file-reference/1-support-matrix.md @@ -1,7 +1,7 @@ # Compose support matrix -Uncloud supports a subset of the [Compose specification](https://compose-spec.io/) with some extensions and limitations. -The following table shows the support status for main Compose features. +Uncloud supports a subset of the [Compose specification](https://compose-spec.io/) with some +[extensions](2-extensions.md) and limitations. The following table shows the support status for main Compose features. :::info @@ -39,7 +39,7 @@ If you rely on a specific Compose feature that is not supported by Uncloud, plea | `memswap_limit` | ❌ Not supported | | | `networks` | ❌ Not supported | All containers share cluster network | | `pid` | ✅ Supported | Set the PID namespace mode, `pid: host` only | -| `ports` | ⚠️ Limited | `mode: host` only, use [`x-ports`](#x-ports) for HTTP/HTTPS | +| `ports` | ⚠️ Limited | `mode: host` only, use [`x-ports`](2-extensions.md#x-ports) for HTTP/HTTPS | | `privileged` | ✅ Supported | Run containers in privileged mode | | `pull_policy` | ✅ Supported | `always`, `missing`, `never` | | `secrets` | ❌ Not supported | Use configs or environment variables | @@ -54,7 +54,7 @@ If you rely on a specific Compose feature that is not supported by Uncloud, plea | **Deploy** | | | | `labels` | ❌ Not supported | | | `mode` | ✅ Supported | Either `global` or `replicated` | -| `placement` | ❌ Not supported | Use [`x-machines`](#x-machines) extension | +| `placement` | ❌ Not supported | Use [`x-machines`](2-extensions.md#x-machines) extension | | `replicas` | ✅ Supported | Number of container replicas | | `resources` | ⚠️ Limited | CPU, memory limits and device reservations | | `restart_policy` | ❌ Not supported | Defaults to `unless-stopped` | @@ -91,115 +91,4 @@ If you rely on a specific Compose feature that is not supported by Uncloud, plea - ⚠️ **Limited**: Partial support or with restrictions - ❌ **Not supported**: Feature is not (yet) available -## Uncloud extensions - -Uncloud provides several custom extensions to enhance the Compose experience: - -### `x-context` - -Set the cluster context for all commands that use the Compose file, such as `deploy`, `build`, and `logs`. This is -useful when you manage multiple clusters and want to make sure a Compose file is always deployed to the right one. No -need to remember to manually switch clusters with `uc ctx` or `--context`. - -`x-context` is a top-level key, not a service-level attribute. - -```yaml -x-context: prod - -services: - web: - image: nginx -``` - -The `--context` and `--connect` flags take precedence over `x-context`. If you don't specify any of these, the current -context from your Uncloud config (`--uncloud-config`) is used. - -:::warning - -If you share the Compose file with other users, make sure to use the same context name for the target cluster in your -Uncloud configs. - -::: - -### `x-ports` - -Expose HTTP/HTTPS service ports via the Caddy reverse proxy, or bind TCP/UDP ports directly to the host: - -```yaml -services: - web: - image: nginx - x-ports: - - 80/https - - example.com:80/https - - 8080:80/tcp@host -``` - -See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details. - -### `x-caddy` - -Custom Caddy reverse proxy configuration for a service: - -```yaml -services: - web: - image: nginx - x-caddy: | - example.com { - reverse_proxy {{upstreams 80}} - } -``` - -See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details. - -### `x-machines` - -Restrict which machines can run your service. If you deploy multiple replicas, Uncloud automatically spreads them across -the specified machines. - -```yaml -services: - web: - image: nginx - x-machines: - - machine-1 - - machine-2 - # Short syntax for a single machine - # x-machines: machine-1 -``` - -### `x-pre_deploy` - -Configure a pre-deploy hook to run a one-off command in a separate container and wait for it to finish successfully -before rolling out service containers. It's useful for preparation tasks that need to run before every service -deployment, such as database migrations, static asset uploads, or cache invalidation. - -The hook container uses the service's image and inherits its environment variables, volumes, placement, and compute -resources. If the command fails or times out (5 minutes by default), the deployment stops. - -```yaml -services: - web: - build: . - x-pre_deploy: - command: python manage.py migrate - environment: - LOG_LEVEL: DEBUG - timeout: 10m -``` - -#### Attributes - -| Attribute | Type | Default | Description | -|---------------|-------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `command` | string / list | (required) | The command to run in the hook container (same format as the service's [`command`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#command)) | -| `environment` | map / list of KEY=VALUE | - | Additional env vars that override or extend the service's [`environment`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#environment) | -| `privileged` | bool | service's value | Override the service's [`privileged`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#privileged) mode | -| `timeout` | duration | `5m` | Max time to wait for the command to finish before killing it (e.g., `1m30s`, `30m`, `1h`) | -| `user` | string | service's value | Override the service's [`user`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#user) to run as (`user`, `UID`, `user:group`, or `UID:GID`) | - -The hook container also gets `UNCLOUD_HOOK_PRE_DEPLOY=true` environment variable set automatically. - -See [Pre-deploy hooks](../4-guides/1-deployments/5-pre-deploy-hooks.md) for more details, usage examples, and failure -handling. +See [Compose extensions](2-extensions.md) for details on additional Compose features provided by Uncloud. diff --git a/website/docs/8-compose-file-reference/2-extensions.md b/website/docs/8-compose-file-reference/2-extensions.md new file mode 100644 index 00000000..9ebfda5d --- /dev/null +++ b/website/docs/8-compose-file-reference/2-extensions.md @@ -0,0 +1,119 @@ +--- +title: Compose extensions +--- + +# Uncloud-specific Compose extensions + +Uncloud provides several custom extensions to the standard [Compose specification](https://compose-spec.io/) that let +you configure Uncloud-specific features directly in your Compose file. + +See the [support matrix](1-support-matrix.md) for the full list of supported standard Compose features. + +## `x-context` + +Set the cluster context for all commands that use the Compose file, such as `deploy`, `build`, and `logs`. This is +useful when you manage multiple clusters and want to make sure a Compose file is always deployed to the right one. No +need to remember to manually switch clusters with `uc ctx` or `--context`. + +`x-context` is a top-level key, not a service-level attribute. + +```yaml +x-context: prod + +services: + web: + image: nginx +``` + +The `--context` and `--connect` flags take precedence over `x-context`. If you don't specify any of these, the current +context from your Uncloud config (`--uncloud-config`) is used. + +:::warning + +If you share the Compose file with other users, make sure to use the same context name for the target cluster in your +Uncloud configs. + +::: + +## `x-ports` + +Expose HTTP/HTTPS service ports via the Caddy reverse proxy, or bind TCP/UDP ports directly to the host: + +```yaml +services: + web: + image: nginx + x-ports: + - 80/https + - example.com:80/https + - 8080:80/tcp@host +``` + +See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details. + +## `x-caddy` + +Custom Caddy reverse proxy configuration for a service: + +```yaml +services: + web: + image: nginx + x-caddy: | + example.com { + reverse_proxy {{upstreams 80}} + } +``` + +See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details. + +## `x-machines` + +Restrict which machines can run your service. If you deploy multiple replicas, Uncloud automatically spreads them across +the specified machines. + +```yaml +services: + web: + image: nginx + x-machines: + - machine-1 + - machine-2 + # Short syntax for a single machine + # x-machines: machine-1 +``` + +## `x-pre_deploy` + +Configure a pre-deploy hook to run a one-off command in a separate container and wait for it to finish successfully +before rolling out service containers. It's useful for preparation tasks that need to run before every service +deployment, such as database migrations, static asset uploads, or cache invalidation. + +The hook container uses the service's image and inherits its environment variables, volumes, placement, and compute +resources. If the command fails or times out (5 minutes by default), the deployment stops. + +```yaml +services: + web: + build: . + x-pre_deploy: + command: python manage.py migrate + environment: + LOG_LEVEL: DEBUG + timeout: 10m +``` + +### Attributes + +| Attribute | Type | Default | Description | +|---------------|-------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `command` | string / list | (required) | The command to run in the hook container (same format as the service's [`command`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#command)) | +| `environment` | map / list of KEY=VALUE | - | Additional env vars that override or extend the service's [`environment`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#environment) | +| `privileged` | bool | service's value | Override the service's [`privileged`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#privileged) mode | +| `timeout` | duration | `5m` | Max time to wait for the command to finish before killing it (e.g., `1m30s`, `30m`, `1h`) | +| `user` | string | service's value | Override the service's [`user`](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#user) to run as (`user`, `UID`, `user:group`, or `UID:GID`) | + +The hook container also gets `UNCLOUD_HOOK_PRE_DEPLOY=true` environment variable set automatically. + +See [Pre-deploy hooks](../4-guides/1-deployments/5-pre-deploy-hooks.md) for more details, usage examples, and failure +handling. diff --git a/website/docs/8-compose-file-reference/2-image-tag-template.md b/website/docs/8-compose-file-reference/3-image-tag-template.md similarity index 100% rename from website/docs/8-compose-file-reference/2-image-tag-template.md rename to website/docs/8-compose-file-reference/3-image-tag-template.md