Since excalidraw service is already running with the same configuration, Uncloud recognises there's nothing to change.
We've successfully converted our deployment created with uc run to a Compose file.
Use your own domain  Copy Chapter
Want to use your own domain, for example, excalidraw.example.com instead of excalidraw.sh8hsb.uncld.dev?
Add a CNAME record excalidraw.example.com in your DNS provider (Cloudflare, Namecheap, etc.) pointing to
excalidraw.sh8hsb.uncld.dev. Alternatively, you can add an A record pointing to your server's IP.
:::info note
These instructions set up your own domain in addition to the Uncloud managed DNS name
excalidraw.sh8hsb.uncld.dev.
If you want to avoid the managed service altogether, add --no-dns to your uc machine init command, and point an A
DNS record to your servers' IPs.
:::
Then update the published port 80/https in compose.yaml to use your domain:

Finally, deploy the changes:

Uncloud prints a deployment plan and asks for confirmation before making any changes. The plan says it will replace the
running container with a new one using the
start-first order. This means Uncloud starts the
new container with the updated configuration, waits for it to become healthy, and only then removes the old one. Your
service stays available throughout the update. That's a zero-downtime deployment.
Give it a moment for Caddy to obtain a TLS certificate, then visit https://excalidraw.example.com (use your own domain).
Clean up  Copy Chapter
When you're done experimenting, you can remove the excalidraw service or uninstall Uncloud completely.
Remove the service  Copy Section
Remove the excalidraw service while keeping your Uncloud machine running for future deployments:

Uninstall Uncloud  Copy Section
If you want to completely uninstall Uncloud from your server and clean up everything it created, SSH into your server
and run:

This command will:
- Remove all Uncloud-managed containers (including Caddy)
- Remove the Uncloud-managed Docker and WireGuard networks
- Uninstall the Uncloud daemon from the server
<details>
<summary>💡 Expand to see example output</summary>

</details>
Further reading  Copy Chapter
- Add more machines: Scale horizontally by creating a cluster of machines
- Ingress & HTTP: Learn how Uncloud handles incoming traffic and how to
  expose your services to the internet
- CLI reference: Explore all available commands and options
---
3 Concepts/1 Clusters/1 Connecting  Copy Section
Connecting to a cluster
uc only needs to reach one machine to work with the entire cluster. That machine acts as an entry point and
forwards requests to other machines as needed.
uc stores cluster contexts and connection details in a configuration file
(default location is ~/.config/uncloud/config.yaml).
When you initialise a new cluster with uc machine init or add a machine to an existing cluster with uc machine add,
they automatically save the SSH addresses of your machines to the config so you don't have to specify them every time.
Cluster contexts  Copy Chapter
The config file organises connections into contexts. Each context represents a
cluster. It has a name and a list of connection details for the machines in that cluster.
A context is not the same thing as a cluster. It is your local view of a cluster: which machines you can connect through
and in what order to try them. Different people or environments may need to reach the same cluster in different ways.
You can also manually create multiple contexts for the same cluster. For example, one that connects through
a machine with a public IP when you're not in the office, and another that connects through a private machine on the
office network when you're on-site to reduce latency. You can switch between them depending on where you are.
Managing contexts  Copy Section
Use these commands to manage the contexts in your config:
- uc ctx: Switch contexts using an interactive TUI
- uc ctx ls: List all contexts and see which one is current
- uc ctx use: Switch the current context by name
- uc ctx conn: Change the default connection for the current context
  using an interactive TUI
You can also set x-context in your Compose file to pin a specific context for deployments. See
Deploy to a specific cluster context
for details.
Connection resolution  Copy Chapter
When you run a uc command, it determines which cluster to connect to using this priority:
1. If --connect is set, uc connects directly to that machine and ignores the config file entirely.
2. If --context is set, uc uses that context from the config.
3. Otherwise, uc uses current_context from the config.
Once the context is resolved, uc tries each connection in the context's connections list in order until one
succeeds.
User permissions on the machine  Copy Chapter
When uc connects to a machine over SSH, it communicates with the Uncloud daemon through the Unix socket
/run/uncloud/uncloud.sock on that machine. The daemon restricts access to the socket to the root user and members
of the uncloud Linux group. This means your SSH user must be either root or a member of the uncloud group.
In most cases you don't need to set this up manually. When you initialise or add a machine with a non-root user,
uc machine init and uc machine add automatically add that user to the uncloud group during installation.
If you want to connect with a different non-root user later, add them to the group on the machine:

The group change only applies to new SSH sessions. If uc still fails with a permission denied error after adding the
user, close any long-running SSH connections to the machine (for example, SSH ControlMaster sessions) and try again.
The same requirement applies when running uc locally on a cluster machine with a unix:// connection. The local user
must be root or a member of the uncloud group.
Global flags and environment variables  Copy Chapter
These flags are available on every uc command. They can also be set with an environment variable. The flag takes
priority if both are set.
| Flag               | Environment variable | Description                                                       |
|--------------------|----------------------|-------------------------------------------------------------------|
| --uncloud-config | UNCLOUD_CONFIG     | Path to the config file                                           |
| --context        | UNCLOUD_CONTEXT    | Use a specific context instead of current_context in the config |
| --connect        | UNCLOUD_CONNECT    | Bypass the config file and connect directly                       |
Connecting directly without a config  Copy Section
The --connect flag or UNCLOUD_CONNECT environment variable let you run one-off commands against a cluster without
using a config. This is useful for CI pipelines and scripts where you don't want to set up a config file.
It accepts these formats:

:::info
Don't use --connect with uc machine init. --connect is for specifying or overriding the connection to an existing
cluster, but uc machine init creates a new one and writes the new cluster context to the config file. You can discard
the config when initialising a cluster with --uncloud-config /dev/null if you don't want to save it.
:::
---
3 Concepts/2 Ingress/1 Overview  Copy Section
---
sidebar_label: Overview
---
Ingress & HTTPS
Uncloud uses Caddy as its reverse proxy to handle incoming traffic, provide automatic HTTPS
with Let's Encrypt, and route requests to your services.
How it works  Copy Chapter
By default, Caddy runs as a global service caddy on every machine in your cluster, listening on the host ports 80
(HTTP), 443 (HTTPS), and 443/UDP (HTTP/3).
It's deployed during cluster initialisation (uc machine init) unless you use the --no-caddy flag.
See Managing Caddy for deployment and customisation instructions.
When you publish a service port, Uncloud automatically configures Caddy to:
1. Listen for requests on the specified hostname (domain name).
2. Automatically obtain and renew a TLS certificate from Let's Encrypt for HTTPS.
3. Route traffic to the healthy service container(s).
4. Load balance across healthy replicas if there are multiple.
For advanced use cases, Uncloud allows to customise the Caddy config using the x-caddy extension in Compose files.
See Custom Caddy configuration for details.
---
3 Concepts/2 Ingress/2 Publishing Services  Copy Section
Publishing services
Publishing service ports makes your services available outside the cluster. This means your services can be accessed
from the internet or local network, depending on your setup.
You can publish service ports in three ways:
- Using the -p/--publish flag with uc run.
- Using the x-ports extension in a Compose file with uc deploy.
- Using the --caddyfile flag with uc run or x-caddy extension in a Compose file for custom Caddy configuration.
For example, run a service with container port 8000 exposed as https://app.example.com via Caddy reverse proxy:

Create an A record in your DNS provider (Cloudflare, Namecheap, etc.) pointing app.example.com to the public IP
address or your machine(s). Once DNS is propagated and Caddy obtains a TLS certificate, you can access your service
securely over HTTPS.
Ingress vs host mode  Copy Chapter
HTTP/HTTPS ports are exposed via Caddy using the following format for the -p/--publish flag and x-ports
extension:

- hostname (optional): The domain name to use for accessing the service. If omitted and a cluster domain is reserved,
  <service-name>.<cluster-domain> is used.
- container_port: The port number within the container that's listening for traffic.
- protocol (optional): http or https (default: https)
TCP/UDP ports can only be exposed in host mode, which binds the container port directly to the host machine's
network interface(s). This is useful for non-HTTP services that need direct port access (bypasses Caddy):

- host_ip / host_prefix (optional): The IP address on the host to bind to. Or an IP prefix in
  CIDR notation, which binds to every host IP address
  that is contained in the prefix. If omitted, binds to all interfaces.
- host_port: The port number on the host to bind to.
- container_port: The port number within the container that's listening for traffic.
- protocol (optional): tcp or udp (default: tcp)
| Port value                           | Description                                                                          |
|--------------------------------------|--------------------------------------------------------------------------------------|
| 8000/http                          | Publish port 8000 as HTTP via Caddy using hostname <service-name>.<cluster-domain> |
| app.example.com:8080/https         | Publish port 8080 as HTTPS via Caddy using hostname app.example.com                |
| 127.0.0.1:5432:5432@host           | Bind TCP port 5432 to host port 5432 on loopback interface only                      |
| 53:5353/udp@host                   | Bind UDP port 5353 to host port 53 on all network interfaces                         |
| 192.168.76.0/24:5432:5432/tcp@host | Bind TCP port 5432 to host port 5432 on every host IP contained in 192.168.76.0/24   |
:::warning
Do not publish internal-only services like databases unless absolutely necessary. You only need to publish ports for
services that should be accessible from outside the cluster. Services within the cluster can communicate with each other
by their DNS names service-name or service-name.internal without publishing ports.
:::
Using Compose  Copy Chapter
Use the x-ports extension in a Compose file to publish service ports:

Custom Caddy configuration  Copy Chapter
For advanced routing and behavior, use x-caddy instead of x-ports. It allows you to provide custom Caddy
configuration for a service in Caddyfile format.

You can inline the Caddyfile or load it from a file: x-caddy: ./Caddyfile. When using a file, the path is relative to
the Compose file location. See the Caddy documentation for syntax and
features.
:::info note
You cannot use x-caddy with http or https ports in x-ports. tcp and udp ports in host mode are allowed
though.
:::
Use it when you need:
- Custom routing rules (different paths, redirects, rewrites, multiple services on one domain).
- Custom headers, authentication, or caching.
- Custom load balancing strategies and options.
- Request and response manipulation.
- Advanced TLS settings.
- Other Caddy features and plugins.
See Deploying or updating Caddy for details on deploying Caddy with a
custom global configuration.
Templates  Copy Section
x-caddy configs are processed as Go templates, allowing you to use dynamic values.
The following functions and variables are available:
| Template                              | Description                                                                                   |
| ------------------------------------- | --------------------------------------------------------------------------------------------- |
| {{upstreams [service-name] [port]}} | A space-separated list of healthy container IPs for the current or specified service and port |
| {{.Name}}                           | The name of the service the config belongs to                                                 |
| {{.Upstreams}}                      | A map of all service names to their healthy container IPs                                     |
The templates are automatically re-rendered and Caddy is reloaded when service containers start/stop or health status
changes.
Examples:
1. Current service upstreams, default port:

↓

2. Current service upstreams, port 8000:

↓

3. Current service upstreams with https scheme:

↓

4. api service upstreams, port 9000:

↓

Verifying Caddy config  Copy Section
Use uc caddy config to view the complete generated Caddyfile served by the caddy service. This is useful for
debugging and verifying your x-caddy configs.
Example output:

The generated config combines:
- Global Caddy configuration (x-caddy from the caddy service).
  See Deploying or updating Caddy for details.
- Auto-generated configs from published service ports (x-ports).
- Custom Caddy configs from services (x-caddy).
- Skipped invalid configs with error messages as comments.
:::warning important
Custom Caddy configs from different services must not conflict (all services must use unique hostnames).
See Multiple services on one domain for an example of how to share one hostname
between multiple services.
Conflicting or invalid configs are detected using caddy adapt
command and skipped. However, some errors could still break the entire config so Caddy will fail to load it. Check the
caddy service logs to troubleshoot.
:::
Common use cases  Copy Section
#### Redirects
Publish a service on example.com and redirect requests from www.example.com to example.com:
<Tabs>
<TabItem value="compose.yaml">

</TabItem>
<TabItem value="Caddyfile">

</TabItem>
</Tabs>
#### Multiple services on one domain
You can publish multiple services on the same hostname by using different paths for each service. For example, route
/ to the web service and /api to the API service:
<Tabs>
<TabItem value="compose.yaml">

</TabItem>
<TabItem value="Caddyfile">

</TabItem>
</Tabs>
---
3 Concepts/2 Ingress/3 Managing Caddy  Copy Section
Managing Caddy
Caddy is automatically deployed as a global service caddy when you initialise a cluster with uc machine init. By
default, it runs on every machine to handle incoming HTTP/HTTPS traffic and route it to your services.
Checking status  Copy Chapter
View the caddy service status and which machines it's running on:

Deploying or updating Caddy  Copy Chapter
Using CLI  Copy Section
Update to the latest stable version using the caddy image from Docker Hub:

Deploy a specific version or custom image:

Deploy only to a specific machine or a subset of machines (comma-separated list):

Deploy with custom global configuration:

Example global configuration:

Using Compose  Copy Section
You can manage the Caddy deployment with a Compose file for more control. For example, to deploy a custom global Caddy
config that uses the DNS challenge with Cloudflare to obtain a wildcard TLS certificate for *.example.com:
<Tabs>
<TabItem value="compose.yaml">

</TabItem>
<TabItem value="Caddyfile">

</TabItem>
</Tabs>
:::info note
The specified command, environment, volumes, and x-ports properties are essential for Caddy to function
correctly in the Uncloud cluster. Do not change the source paths of the volume mounts as the Uncloud daemon relies on
them to communicate with Caddy and update its configuration.
:::
Deploy or update the caddy service from the Compose file:

Verifying config  Copy Chapter
View the complete generated Caddyfile served by the caddy service. This is useful for debugging and verifying custom
global and service-specific Caddy configs.

Example output:

The generated config combines:
- Global Caddy configuration (x-caddy from the caddy service).
- Auto-generated configs from published service ports (x-ports).
- Custom Caddy configs from services (x-caddy).
- Skipped invalid configs with error messages as comments.
---
3 Concepts/6 Services/1 Internal Dns  Copy Section
Internal DNS
Services can be addressed on the internal WireGuard network by service name, service ID, or a machine-scoped service name:
Service name  Copy Chapter

Service ID  Copy Chapter

Machine ID scoped service name  Copy Chapter

IP Ordering Mode  Copy Chapter
Additionally, the IP ordering preference can be specified with a rr (round-robin) or nearest subdomain prefix.
rr (round-robin) current default  (round-robin) current default')" title="Copy section prompt for LLMs"> Copy Section

Randomly shuffled order on each lookup.

Nearest scope  Copy Chapter

Returns machine-local instances first.
machine-a:

machine-b:

The prefixes can be used with service ID and machine-scoped service names, as well (e.g. nearest.3ecb3a8bbec5fd3f46efb056a934714a.internal or rr.0903f0ee483aa97d559eeeaac5e22283.m.worker.internal).
---
3 Concepts/6 Services/2 Container Env  Copy Section
Container ENV Variables
- UNCLOUD_MACHINE_ID
  - Machine ID the service container is running on.
  - Example: UNCLOUD_MACHINE_ID=0903f0ee483aa97d559eeeaac5e22283
- HOSTNAME
  - Service name with unique suffix.
  - Example: HOSTNAME=worker-c1zd
---
3 Concepts/7 Configs  Copy Section
Configs
Uncloud supports Compose configs for managing configuration files in your services. Configs allow you to store non-sensitive configuration data separately from your container images and mount them into containers at runtime.
See also Docker Compose documentation for the same feature.
Overview  Copy Chapter
Configs provide a way to:
- Store configuration files outside of container images
- Share configuration between multiple services
- Update configuration without rebuilding images
- Version control your configuration separately
Defining Configs  Copy Chapter
Configs are defined in two places in your compose.yaml:
1. Top-level configs section: Define the config content
2. Service-level configs section: Mount configs into containers
Top-level Configs  Copy Chapter
Define configs using either file-based or inline content:
File-based Configs  Copy Section
Read configuration from a file on the (local/control) host where uc deploy is run:

The file path is relative to the compose file location.
Inline Configs  Copy Section
Define configuration content directly in the compose file:

When using inline configs, environment variable interpolation is supported so that you can customize configuration based on your deployment environment. Variables are resolved from the environment where uc deploy is executed.
Service-level Config Mounts  Copy Chapter
Mount configs into containers using the long syntax:

Config Mount Options  Copy Section
| Option   | Description                                       | Default    |
| -------- | ------------------------------------------------- | ---------- |
| source | Name of the config (from top-level configs)       | Required   |
| target | Path where the config is mounted in the container | Required   |
| mode   | File permissions (octal format)                   | 0644     |
| uid    | User ID that owns the file                        | Root user  |
| gid    | Group ID that owns the file                       | Root group |
Complete Examples  Copy Chapter
Example 1: Web Server with Custom Configuration  Copy Section

Create nginx.conf in the same directory as your compose file:

Example 2: Application with Multiple Config Files  Copy Section

Implementation details  Copy Chapter
Here are the key characteristics of the configs feature implementation:
- Client-side processing: When you run uc deploy, the Uncloud CLI reads config files from your local machine and includes their content in the service specification.
- Content transfer: Config content (both file-based and inline) is sent to the Uncloud daemon via gRPC as part of the deployment request.
- Container deployment: During container creation, configs are copied inside the container.
- File lifecycle: Config files exist only for the lifetime of the container. When a container is removed, its config files are cleaned up automatically.
- Per-container isolation: Each container gets its own copy of config files.
- Atomic updates: Config changes require redeployment, ensuring consistency across all replicas.
Best Practices  Copy Chapter
Security Considerations  Copy Section
- Sensitive Data: Don't put secrets in configs. Use environment variables or external secret management
- File Permissions: Set appropriate mode, uid, and gid for sensitive config files
- Version Control: Be careful about committing sensitive configuration files to git
Config Sharing  Copy Section
Configs can be shared across multiple services:

Limitations  Copy Chapter
- External configs: Not supported. All configs must be defined in the compose file
- Short syntax: Not yet supported. Use the long syntax with source and target
- Config updates: Changing config content requires redeployment to take effect
Troubleshooting  Copy Chapter
Config File Not Found  Copy Section
If you get an error about config file not found:
1. Check the file path is correct relative to the compose file
2. Ensure the file exists and is readable
3. Verify file permissions
Permission Denied  Copy Section
If containers can't read config files:
1. Check the mode setting allows read access
2. Verify uid and gid match the container's user
3. Ensure the container user has permission to access the target directory
Config Not Updating  Copy Section
If config changes don't take effect:
1. Run uc deploy to redeploy with new config content
2. Check that you're modifying the correct config file
3. Verify the config is properly mounted in the container with docker exec <service> cat <config-path> on the remote machine
See also  Copy Chapter
- Secrets: Pass sensitive values such as passwords, tokens, and keys to your services
- Compose support matrix: Which Compose features Uncloud supports
---
3 Concepts/8 Secrets  Copy Section
Secrets
Secrets allow you to keep sensitive data for your services out of your Compose file and version control. This
includes database passwords, API tokens, TLS or SSH private keys.
Uncloud provides an extended support for
Compose secrets, allowing you to fetch secret
values at deploy time from your password manager, a cloud secrets store, or local files.
How it works  Copy Chapter
Two things go into your Compose file:
1. Define a secret in the top-level secrets section. This tells Uncloud how to get the secret value.
2. Reference that secret value in a service's environment using the secret://<name> format. This tells Uncloud to
   resolve the secret and set the environment variable to its value at deploy time.

When you run uc deploy, it sees each secret://<name> reference, resolves the secret on your local machine, and sets
the environment variable to its value. For example, it runs the command for db_password and reads the file for
tls_key. The values never land in your Compose file or git. They go straight into the deployment.
Only secrets you reference in the services that you currently deploy get resolved. A secret referenced in multiple
places or by several services resolves only once, and the value is reused.
Secrets are resolved after building images (if any) and before preparing the deployment plan.
:::info note
Secrets can only be used to set environment variables in your services. \
Mounting a secret as a file inside the container is not supported yet. For mounting config files,
see Configs.
:::
Secret sources  Copy Chapter
Uncloud supports multiple sources for fetching secret values. Choose the one for each secret that fits your workflow.
Arbitrary command  Copy Section
The x-command extension runs a command and uses its output as the secret value. It's the most versatile option that
lets you pull a secret from a system Keychain, password managers, cloud services and secrets stores, or any CLI tool you
already use.

The command runs on the machine where you run uc deploy, in the same directory as your Compose file and with the same
environment. So it uses the CLIs and credentials you are already logged into.
If your password manager needs you to unlock it or touch a hardware key, the prompt shows up right in your terminal.
Uncloud never stores your provider credentials.
A few details worth knowing:
- The command runs directly without a shell. To use pipes or variables, call a shell yourself: sh -c 'cmd1 | cmd2'.
- A single trailing newline is trimmed from the output, because most CLI tools add one. Everything else is kept as is.
- The command has 1 minute to finish before uc times out and aborts the deployment.
x-command is a short form for driver: exec. Use the long form if you prefer to be explicit:

:::tip
To pull secrets from many providers through a single CLI, or to keep encrypted secrets in your git repository,
consider fnox. It works with AWS, GCP, Azure, HashiCorp Vault, 1Password, Bitwarden, and more,
and prints a plain value you can read with x-command:

:::
File  Copy Section
Read the content of a local file as the secret value. The file path is relative to the Compose file location.

The file content is used verbatim without trimming any whitespaces.
:::warning
Do NOT commit these files to your repository and ensure they are protected with proper file permissions. For example,
make the file readable only by your user with chmod 600 ./secrets/db_password.txt.
:::
Things to keep in mind  Copy Chapter
- Secrets resolve on the machine where you run uc deploy, not on the cluster. The cluster only receives the final
  value.
- Secret values passed as environment variables are stored unencrypted as part of the service specification in the
  distributed cluster store.
- Docker also stores the resolved environment variables unencrypted in each container's configuration at
  /var/lib/docker/containers/<id>/config.v2.json on the machine running the container. Anyone with root access to
  that machine or able to run docker inspect can read them.
See also  Copy Chapter
- Configs: Mount non-sensitive configuration files into your containers
- Compose support matrix: Which Compose features Uncloud supports
---
4 Guides/1 Deployments/1 Deploy App  Copy Section
Deploy an app
Deploy a containerised application to your Uncloud cluster using either source code or pre-built images.
This guide covers both scenarios:
- Deploy from source code: Build Docker images from your application code and use them
  to deploy service containers
- Deploy pre-built images: Deploy service containers using existing images from a
  registry or your local machine
Uncloud uses Compose Specification 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 for details.
Prerequisites  Copy Chapter
- uc CLI installed on your local machine
- An Uncloud cluster with at least one machine (see Quick start)
- Basic knowledge of Compose Specification
Deploy from source code  Copy Chapter
Use this scenario when you want to build and deploy your application from
a Dockerfile and source code available on your local machine.
1. Create a Compose file  Copy Section
Create a compose.yaml file in your application directory with a
build section for each service you want to
build. Here is a minimal example of a Compose file that builds and deploys a web app that consists of a single service
called web:

If you don't have a Dockerfile for building an image from your source code, create one in the same directory.
2. Build and deploy your app  Copy Section
To build and deploy services defined in your Compose file, navigate to the directory with compose.yaml and run:

This command looks for a Compose file in your current working directory and:
1. Builds images for services with a build section using your local Docker and tags them with the current Git
   version
2. Pushes built images directly to cluster machines using
   unregistry, transferring only the missing layers
3. Plans the deployment and shows you what will change, asking for confirmation
4. Creates any missing volumes on target machines
5. Deploys service containers using the built images and latest configuration changes with zero-downtime rolling
   updates
See the uc deploy  reference for all available options.
Watch uc deploy building and deploying a demo app (12 seconds):
<video controls width="100%">
  <source src="https://media.uncloud.run/docs/uc-deploy-demo.mp4"/>
</video>
Customise the build configuration  Copy Section
If you need more control over the build configuration, you can specify additional attributes in the build section of
your Compose file. For example, to specify a custom Dockerfile location, set build-time arguments, or build
multi-platform images.

You can pass additional build arguments or override existing ones using the --build-arg flag with uc deploy:

You can also use advanced features like build caches or SSH access.
See Compose Build Specification for all supported
attributes. Note that build secrets are not
supported though.
:::info note
To build multi-platform images, you need to configure your local Docker to use the
containerd image store.
:::
Customise image tags  Copy Section
If you don't specify the image attribute, uc deploy tags built images with a Git-based version like

It uses your local date/time if the working directory is not a Git repository.
You can customise the image name and tag format using the image attribute. It can be a static name or a dynamic
template using environment variables and
the Go template syntax.

This generates tags like:
- myapp:20251030.84d33bb.local.dirty when building locally with uncommitted changes
- myapp:20251030.84d33bb.1234 when building in CI with GITHUB_RUN_ID=1234 and a clean repo
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 reference for all available
template variables and functions.
Separate build and deploy steps  Copy Section
You might want to build and deploy services as separate commands. For example, to run them as separate steps in your
CI/CD pipeline or have more control over the build and deploy process. Here are the commands that are equivalent to
uc deploy:

Deploy configuration changes only  Copy Section
You can use the --no-build flag with uc deploy to deploy only the configuration changes in your Compose file if your
source code and images haven't changed. However, the image tag may still change if you're using
dynamic tags based on the Git state (default). In that case, the deploy will likely fail
because the new tag won't be found on cluster machines.
Use less sensitive dynamic tags or specify the built and pushed image tags you want to deploy explicitly to avoid this
issue.
The recommended approach though is to commit all your changes, including the configuration ones, to the repo. Then
rebuild and deploy your services from a clean repo state. This way, the image tags will always reflect the exact source
code and configuration used for the deployment.
Deploy pre-built images  Copy Chapter
Use this scenario when you want to deploy your application using pre-built images from a container registry (for
example, Docker Hub or GitHub Container Registry) or your local Docker.
1. Create a Compose file  Copy Section
Create a compose.yaml file that references an image from a registry using the
image attribute. It's important that you don't
include a build section for services using pre-built images. Here is a minimal example of a Compose file that deploys
an app that consists of a single nginx service:

2. Deploy your app  Copy Section
To deploy services defined in your Compose file, navigate to the directory with compose.yaml and run:

This command looks for a Compose file in your current working directory and:
1. Plans the deployment and shows you what will change, asking for confirmation
2. Creates any missing volumes on target machines
3. Pulls images from a registry on cluster machines where services are deployed according to the
   pull_policy
4. Deploys service containers using the pulled images and latest configuration changes with zero-downtime rolling
   updates
Control image pulling  Copy Section
By default, uc deploy pulls an image from a registry only if it's missing on a target machine. You can change this
behavior using the pull_policy
attribute. For example, to always pull the latest version of an image before deploying.

Available pull_policy values:
- always: Always pull the image from the registry before deploying
- missing (default): Pull only if the image isn't available on the target machine
- never: Never pull, the image must be present on the target machine or the deploy will fail
Pull from a private registry  Copy Section
If your images are in a private registry, uc deploy needs an authentication token to pull them. You can provide it by
either:
- Logging in to the registry using your local Docker (recommended)
- Logging in to the registry using Docker on each cluster machine you want to deploy to
When you're logged in using your local Docker, uc deploy automatically passes your local Docker credentials for the
private registry to cluster machines when pulling images. This way, you don't need to log in on each machine manually.
See docker login for instructions on how to log in to a private
registry.
Push local images to cluster machines  Copy Section
You can also deploy pre-built images that exist only in your local Docker and are not available for pulling on cluster
machines. For example, images you built locally outside of the Compose workflow or pulled from a private registry that
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 command:

This command uploads the image from your local Docker to the cluster machines using
unregistry running as part of the Uncloud daemon on each machine. It
efficiently transfers only the image layers that don't already exist on the target machines.
After pushing the image, update your Compose file to reference it:

Run uc images to verify that the image is available on the target machines.
Then deploy as usual:

:::tip
Set pull_policy: never when using local images to prevent uc deploy from trying to pull them from a registry.
:::
Mix source builds and pre-built images  Copy Chapter
Define multiple services in your Compose file, mixing source builds and pre-built images:

uc deploy builds and pushes images for services with a build section and pulls images from a registry for services
with only an image attribute.
:::warning
Service names must be globally unique across all Compose files deployed to the same cluster.
Unlike Docker Compose or Docker Swarm, Uncloud doesn't automatically prefix service names with project or stack names.
Choose unique names to avoid conflicts with services deployed from other Compose files.
:::
Deploy to a specific cluster context  Copy Chapter
If you manage multiple clusters, you can set x-context in your Compose file to make sure it always deploys to the
correct one. You won't need to remember to manually switch clusters with uc ctx or --context.

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 for more details.
Use a different Compose file location  Copy Chapter
If your Compose file has a different name or location, use the -f/--file flag to specify its path:

You can also specify multiple Compose files to merge configurations:

See Use multiple Compose files for details on how you
can customise your Compose application for different environments or workflows.
Verify your deployment  Copy Chapter
After deploying your app, you can verify that your services are running as expected by listing all deployed services in
the cluster:

and inspecting the status of containers for a specific service:

See also
- Deploy to specific machines: Deploy services to specific machines in your cluster
- Deploy a global service: Deploy one service replica on each cluster machine
- Compose Specification: Official specification for the Compose file format
- Compose support matrix: Supported Compose features and Uncloud
  extensions
---
4 Guides/1 Deployments/2 Deploy Specific Machines  Copy Section
Deploy to specific machines
Deploy services to specific machines in your cluster using the
x-machines extension in your Compose file.
When to target specific machines  Copy Chapter
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 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  Copy Chapter
Set x-machines to a list of machine names or a single machine name to restrict which machines a service can run on.

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 to see available machines in your cluster.
:::
Push images to specific machines only  Copy Chapter
When building from source, 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 command:

See Push local images to cluster machines for more details.
See also  Copy Chapter
- Deploy an app: Build and deploy from source code or pre-built images
- Deploy a global service: Deploy one service replica on each cluster machine
- Compose support matrix: Supported Compose features and Uncloud
  extensions
---
4 Guides/1 Deployments/3 Deploy Global Services  Copy Section
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  Copy Chapter
To deploy exactly one replica on each machine in your cluster for a specific service, set
mode: global under the deploy section in
your Compose file:

Then 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  Copy Chapter
You can combine the global mode with x-machines
to deploy one container to each specified machine:

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  Copy Chapter
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  Copy Chapter
- Deploy an app: Deploy from source code or pre-built images
- Deploy to specific machines: Deploy services to specific machines in your cluster
- Compose Specification: deploy.mode:
  Compose specification for deployment modes
---
4 Guides/1 Deployments/4 Rolling Deployments  Copy Section
Rolling deployments
How uc deploy updates your services without downtime and automatically rolls back on failure.
Uncloud uses a rolling deployment to update your service by replacing its containers one at a time. Before moving on
to the next container, Uncloud waits for the new one to pass health monitoring. If it fails to
become healthy, Uncloud stops the deployment and rolls back that container to the old one. This keeps your service
available throughout the update.
For a service with three replicas and the default start-first update order, the deployment looks like
this:
1. Start new container #1, wait until healthy
2. Stop and remove old container #1
3. Start new container #2, wait until healthy
4. Stop and remove old container #2
5. Start new container #3, wait until healthy
6. Stop and remove old container #3
At every step, at least three containers are serving traffic.
Update order  Copy Chapter
The update order controls whether Uncloud starts the new container before or after stopping the old one.
| Order         | What happens                                                                | Best for                            |
|---------------|-----------------------------------------------------------------------------|-------------------------------------|
| start-first | Start new container, then stop old<br/>(running containers briefly overlap) | Stateless services (web apps, APIs) |
| stop-first  | Stop old container, then start new                                          | Stateful services (databases)       |
The default is start-first so there's no downtime. But it automatically switches to stop-first in two cases:
- Host port conflicts: the old container must free the port before the new one can bind to it.
- Single-replica service with a volume: two containers simultaneously writing to the same volume can
  corrupt data, so Uncloud stops the old container first to prevent this.
stop-first can cause a brief downtime while the old container stops and the new one starts in these cases. The
deployment plan printed by uc deploy indicates which containers will be replaced with stop-first.
A multiple-replica service with a volume doesn't automatically switch to stop-first as Uncloud assumes that the
concurrent access is desired and safe. Host path and tmpfs mounts don't trigger the switch either.
Override update order  Copy Section
You can override the update order with deploy.update_config.order:

This single-replica service uses a volume, so Uncloud would normally use stop-first. Setting order: start-first
overrides that.
This is useful if your app handles concurrent access to data safely and you want to avoid downtime. For example, the app
uses an SQLite database in WAL mode on the volume.
Health monitoring  Copy Chapter
After starting each new container, Uncloud monitors it for failures for 5 seconds to make sure it keeps running
and not crashing. If it keeps restarting after this period, the deployment fails and Uncloud
rolls back that container to the old one.
This is a safeguard to prevent you from deploying broken code or misconfiguration that would cause downtime. 5 seconds
is typically enough for a process in a container to initialise all its dependencies and start.
You can change the monitoring period for a service with deploy.update_config.monitor. For example, increase it if your
app takes longer to start or if you want to give it more time to recover from transient errors on startup.

Set it to 0s to skip monitoring entirely if you are confident the new containers will start correctly and want to
speed up the deployment. A safer alternative is to configure a health check instead.
You can also change the default monitoring period (5s) for all services globally with an environment variable
UNCLOUD_HEALTH_MONITOR_PERIOD:

deploy.update_config.monitor overrides the global default for that service.
Health checks  Copy Section
If your service has a healthcheck
configured, Uncloud also checks its health status during and after the monitoring period.
If a container becomes healthy before the monitoring period ends, the deployment succeeds early and moves on to the
next container. If the container is unhealthy after the monitoring period, Uncloud
rolls it back and fails the deployment. Transient unhealthy states during the monitoring
period are tolerated to give the container time to recover from startup issues.
To make deployments safer and faster, it's recommended to configure a health check that can quickly notify
Uncloud when containers start successfully and become ready to serve traffic. You can configure it with
healthcheck in your Compose file or
HEALTHCHECK in your image Dockerfile:

:::info important
If a health check fails after the deployment, Uncloud automatically removes the unhealthy container from the
Caddy configuration to prevent routing traffic to that container. But it
doesn't automatically restart or roll it back.
Uncloud automatically adds it back to Caddy when it recovers and becomes healthy again. You can inspect the health
status of your containers with uc ps or
uc inspect and check their logs with
uc logs.
:::
Skip health monitoring  Copy Section
To skip health monitoring for faster emergency deployments, use uc deploy --skip-health.
:::warning
--skip-health won't detect containers that crash on startup or become unhealthy so won't roll them back or stop the
deployment. Use this only for emergency deployments when you are confident the new containers will start correctly.
:::
Rollback on failure  Copy Chapter
If a new container fails health monitoring during a deployment, Uncloud stops it but keeps it around for inspection. For
stop-first order, Uncloud also restarts the old container. The deployment then stops and the remaining containers are
left untouched.
For example, if the first container in a rolling update succeeds but the second one fails, the first replacement stays
in place.
Failed container logs  Copy Section
To help you diagnose the failure, uc deploy prints the last 10 log lines from the failed container.
You can change how many lines are printed with the UNCLOUD_FAILED_CONTAINER_LOGS_TAIL environment variable. Set it to
a number or to all to print the full container log:

You can fetch the full logs with uc logs or inspect the status of the stopped
container with uc inspect or uc ps.
Retry after failure  Copy Chapter
You can retry the deployment by running uc deploy again. Uncloud will skip the successfully deployed containers if the
configuration hasn't changed and only redeploy the remaining ones.
See also  Copy Chapter
- Pre-deploy hooks: Run a command before deploying service containers
- Deploy an app: Build and deploy from source code or pre-built images
- Compose support matrix: Supported Compose features and Uncloud
  extensions
---
4 Guides/1 Deployments/5 Pre Deploy Hooks  Copy Section
Pre-deploy hooks
Run a one-off command before deploying a service.
Pre-deploy hooks are useful for one-off tasks such as:
- Database schema and data migrations
- Uploading static assets to a CDN
- Cache invalidation
- Any setup task that needs to run once before new code goes live, not on every container startup
How it works  Copy Chapter
When you run uc deploy for a service with a pre-deploy hook configured, the hook command runs after building and
pushing the new image (if building from source) but before rolling out
any new containers.
uc deploy runs your hook command inside a new container and waits for it to finish or time out (5 minutes by
default). This container inherits most of the service's configuration, including the image, environment
variables, volumes, placement, and compute resources.
If the command exits with code 0, the deployment continues with a normal rolling update. If
the command fails or times out, the deployment stops immediately with an error. uc deploy will display the latest logs
from the hook container to help you diagnose the issue.

The hook runs on one of the machines where the service will be deployed. Similar to service containers, hook containers
can reach other services over the network, connect to databases, and read or write shared volumes. Note that file system
changes do not persist after the hook finishes, except for changes written to shared volumes.
Usage  Copy Chapter
Add the 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.

:::info note
The command replaces the image's default command (CMD) but the
ENTRYPOINT still runs. If your image has an entrypoint,
the hook command is passed as arguments to it. You can override the entrypoint for the service using
entrypoint which applies to both
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 for all available attributes and their
defaults.
Database migrations  Copy Section
The most common use case for pre-deploy hooks is running database migrations before deploying a new app version:

When you run uc deploy, the migration runs first inside a new container created with the same image and environment
variables as the web service. Only after it succeeds, the deployment starts replacing service containers with the new
image.
Running multiple commands  Copy Section
If you need to run several tasks before deployment, you can wrap them in a single shell command:

For more complex scenarios, create a dedicated script and use it as the hook command:
<Tabs>
<TabItem value="compose.yaml">

</TabItem>
<TabItem value="scripts/pre_deploy.sh">

</TabItem>
</Tabs>
Make sure the script is included in your service image and exits with a non-zero code on any command failure (set -e).
Custom environment and user  Copy Section
The hook container inherits environment variables from the service. You can add hook-specific variables or override
existing ones with environment. Use user to run the command as a different user.
For example, if your service runs as a non-root user but the hook needs root to fix file permissions on a shared volume:

:::tip
Uncloud automatically sets UNCLOUD_HOOK_PRE_DEPLOY=true in the hook container. You can check this variable in a shared
entrypoint script or your command to detect when it's running as a pre-deploy hook versus a regular service container.
:::
Failure handling  Copy Chapter
Non-zero exit code  Copy Section
When the hook command exits with a non-zero code, the deployment stops immediately. No service containers are created or
replaced. uc deploy prints the latest logs from the failed hook container to help you diagnose the issue and keeps it
around for inspection. See Failed hook logs below for details.
Fix the issue and run uc deploy again to retry.
Timeout  Copy Section
If the hook doesn't finish within the timeout (default 5 minutes), Uncloud kills the container and fails the
deployment. The killed container is kept for inspection. See Failed hook logs below for details.
You can increase the timeout for long-running tasks like large database migrations or data uploads:

Failed hook logs  Copy Section
When a hook fails with a non-zero exit code or a timeout, uc deploy prints the last 10 log lines from the failed hook
container to help you diagnose the issue.
You can change how many lines are printed with the UNCLOUD_FAILED_CONTAINER_LOGS_TAIL environment variable. Set it to
a number or to all to print the full container log. The same setting applies to regular containers that fail during a
rolling deployment:

You can fetch the full logs as part of the service logs with uc logs or inspect
the status of the failed container with uc inspect
or uc ps.
Idempotency  Copy Section
Design your hook commands to be idempotent when possible. If a deployment fails after the hook succeeds (for
example, a new container crashes on startup) and you retry with uc deploy, the hook runs again.
Most database migration tools handle this naturally since they track which migrations have already been applied.
See also  Copy Chapter
- x-pre_deploy reference: All available attributes and
  their defaults
- Rolling deployments: How Uncloud updates containers with zero downtime
- Deploy an app: Build and deploy from source code or pre-built images
---
8 Compose File Reference/1 Support Matrix  Copy Section
Compose support matrix
Uncloud supports a subset of the Compose specification with some
extensions and limitations. The following table shows the support status for main Compose features.
:::info
If you rely on a specific Compose feature that is not supported by Uncloud, please submit a feature request in
GitHub Discussions or on Discord.
:::
| Feature                          | Support Status     | Notes                                                                                                                                      |
|----------------------------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| Services                     |                    |                                                                                                                                            |
| build                          | ✅ Supported        | Build context and Dockerfile                                                                                                               |
| cap_add                        | ✅ Supported        | Additional kernel capabilities                                                |
| cap_drop                       | ✅ Supported        | Which kernel capabilities to drop                                             |
| command                        | ✅ Supported        | Override container command                                                                                                                 |
| configs                        | ✅ Supported        | File-based and inline configs                                                                                                              |
| cpus                           | ✅ Supported        | CPU limit                                                                                                                                  |
| depends_on                     | ⚠️ Limited         | Deployed in dependency order. Use pre-deploy hooks for service_completed_successfully |
| devices                        | ✅ Supported        | Device mappings                                                                                                                            |
| dns                            | ❌ Not supported    | Built-in service discovery                                                                                                                 |
| dns_search                     | ❌ Not supported    | Built-in service discovery                                                                                                                 |
| entrypoint                     | ✅ Supported        | Override container entrypoint                                                                                                              |
| env_file                       | ✅ Supported        | Environment file                                                                                                                           |
| environment                    | ✅ Supported        | Environment variables                                                                                                                      |
| gpus                           | ✅ Supported        | GPU device access                                                                                                                          |
| healthcheck                    | ✅ Supported        | Health check configuration                                                                                                                 |
| image                          | ✅ Supported        | Container image specification                                                                                                              |
| init                           | ✅ Supported        | Run init process in container                                                                                                              |
| labels                         | ❌ Not supported    |                                                                                                                                            |
| links                          | ❌ Not supported    | Use service names for communication                                                                                                        |
| logging                        | ✅ Supported        | Defaults to local log driver                                                      |
| mem_limit                      | ✅ Supported        | Memory limit                                                                                                                               |
| mem_reservation                | ✅ Supported        | Memory reservation                                                                                                                         |
| mem_swappiness                 | ❌ Not supported    |                                                                                                                                            |
| 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 for HTTP/HTTPS                                                                 |
| privileged                     | ✅ Supported        | Run containers in privileged mode                                                                                                          |
| pull_policy                    | ✅ Supported        | always, missing, never                                                                                                               |
| secrets                        | ⚠️ Limited         | Reference secrets in environment, see Secrets. File mounts not supported                                   |
| security_opt                   | ❌ Not supported    |                                                                                                                                            |
| shm_size                       | ✅ Supported        | Shared memory size                                                                                                                         |
| stdin_open                     | ✅ Supported        | Allocate standard input and keep it open                                                                                                   |
| stop_grace_period              | ✅ Supported        | Time to wait after SIGTERM before SIGKILL                                                                                                  |
| storage_opt                    | ❌ Not supported    |                                                                                                                                            |
| sysctls                        | ✅ Supported        | Namespaced kernel parameters                                                                                                               |
| tty                            | ✅ Supported        | Allocate a pseudo-TTY and connect the container's standard streams to it                                                                   |
| ulimits                        | ✅ Supported        | Resource limits                                                                                                                            |
| user                           | ✅ Supported        | Set container user                                                                                                                         |
| volumes                        | ✅ Supported        | Named volumes, bind mounts, tmpfs                                                                                                          |
| Deploy                       |                    |                                                                                                                                            |
| labels                         | ❌ Not supported    |                                                                                                                                            |
| mode                           | ✅ Supported        | Either global or replicated                                                                                                            |
| placement                      | ❌ Not supported    | Use 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                                                                                                               |
| rollback_config                | ❌ Not supported    | See #151                                                                               |
| update_config                  | ⚠️ Limited         | order and monitor supported. See rolling deployments                             |
| Volumes                      |                    |                                                                                                                                            |
| Named volumes                    | ✅ Supported        | Docker volumes                                                                                                                             |
| Bind mounts                      | ✅ Supported        | Host path binding                                                                                                                          |
| Tmpfs mounts                     | ✅ Supported        | In-memory filesystems                                                                                                                      |
| Volume labels                    | ✅ Supported        | Custom labels                                                                                                                              |
| External volumes                 | ✅ Supported        | Must exist before deployment                                                                                                               |
| [Volume drivers][volume-drivers] | ✅ Supported        | local (supports [NFS][volume-nfs], [CIFS/Samba][volume-cifs]) and manually installed third-party drivers                                 |
| Configs                      |                    |                                                                                                                                            |
| File-based configs               | ✅ Supported        | Read from file                                                                                                                             |
| Inline configs                   | ✅ Supported        | Defined in compose file                                                                                                                    |
| External configs                 | ❌ Not supported    | Not supported                                                                                                                              |
| Short syntax                     | ❌ Not supported    | Use long syntax only                                                                                                                       |
| Extensions                   |                    |                                                                                                                                            |
| x-context                      | ✅ Uncloud-specific | Cluster context override                                                                                                                   |
| x-caddy                        | ✅ Uncloud-specific | Custom Caddy configuration                                                                                                                 |
| x-machines                     | ✅ Uncloud-specific | Machine placement constraints                                                                                                              |
| x-ports                        | ✅ Uncloud-specific | Service port publishing                                                                                                                    |
| x-pre_deploy                   | ✅ Uncloud-specific | Pre-deploy hook command                                                                                                                    |
[volume-drivers]: https://docs.docker.com/engine/storage/volumes/#use-a-volume-driver
[volume-nfs]: https://docs.docker.com/engine/storage/volumes/#create-a-service-which-creates-an-nfs-volume
[volume-cifs]: https://docs.docker.com/engine/storage/volumes/#create-cifssamba-volumes
Legend  Copy Section
- ✅ Supported: Feature works as documented
- ⚠️ Limited: Partial support or with restrictions
- ❌ Not supported: Feature is not (yet) available
See Compose extensions for details on additional Compose features provided by Uncloud.
---
8 Compose File Reference/2 Extensions  Copy Section
---
title: Compose extensions
---
Uncloud-specific Compose extensions
Uncloud provides several custom extensions to the standard Compose specification that let
you configure Uncloud-specific features directly in your Compose file.
See the support matrix for the full list of supported standard Compose features.
x-context ')" title="Copy chapter prompt for LLMs"> Copy Chapter
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.

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 ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Expose HTTP/HTTPS service ports via the Caddy reverse proxy, or bind TCP/UDP ports directly to the host:

See Publishing services for more details.
x-caddy ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Custom Caddy reverse proxy configuration for a service:

See Publishing services for more details.
x-machines ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Restrict which machines can run your service. If you deploy multiple replicas, Uncloud automatically spreads them across
the specified machines.

x-pre_deploy ')" title="Copy chapter prompt for LLMs"> Copy Chapter
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.

Attributes  Copy Section
| Attribute     | Type                    | Default         | Description                                                                                                                                                        |
|---------------|-------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| command     | string / list           | (required)      | The command to run in the hook container (same format as the service's command) |
| environment | map / list of KEY=VALUE | -               | Additional env vars that override or extend the service's environment       |
| privileged  | bool                    | service's value | Override the service's 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 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 for more details, usage examples, and failure
handling.
secrets..x-command ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Resolve a secret by running a command locally and using its output as the value. Define a secret under the top-level
secrets section, then reference it as secret://<name> in a service's environment: