Uncloud

https://uncloud.run/docs
Admin
Uncloud is a platform for self-hosting and scaling multi-service, multi-container web applications...
Tokens:13,956
Snippets:122
Trust Score:7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Uncloud Binaries and Setup Services

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

Downloads and installs the Uncloud daemon (uncloudd), uninstall script, and corrosion binary. It also creates and enables systemd services for both the Uncloud daemon and the corrosion service, ensuring they start on boot.

```shell
✓ Docker installed successfully.
✓ Linux user and group 'uncloud' created.
⏳ Installing Uncloud binaries...
⏳ Downloading uncloudd binary: https://github.com/psviderski/uncloud/releases/latest/download/uncloudd_linux_amd64.tar.gz
✓ uncloudd binary installed: /usr/local/bin/uncloudd
⏳ Downloading uninstall script: https://raw.githubusercontent.com/psviderski/uncloud/refs/heads/main/scripts/uninstall.sh
✓ uncloud-uninstall script installed: /usr/local/bin/uncloud-uninstall
✓ Systemd unit file created: /etc/systemd/system/uncloud.service
Created symlink /etc/systemd/system/multi-user.target.wants/uncloud.service → /etc/systemd/system/uncloud.service.
⏳ Downloading uncloud-corrosion binary: https://github.com/psviderski/corrosion/releases/latest/download/corrosion-x86_64-unknown-linux-gnu.tar.gz
✓ uncloud-corrosion binary installed: /usr/local/bin/uncloud-corrosion
✓ Systemd unit file created: /etc/systemd/system/uncloud-corrosion.service
```

--------------------------------

### Install Uncloud CLI using Install Script

Source: https://uncloud.run/docs/getting-started/install-cli

Automates the installation of the Uncloud CLI on macOS and Linux by downloading and executing a script. The script detects the OS, downloads the latest binary, and installs it to /usr/local/bin/uncloud, creating a 'uc' alias.

```shell
curl -fsS https://get.uncloud.run/install.sh | sh
```

```shell
curl -fsSO https://get.uncloud.run/install.sh
cat install.sh
sh install.sh
```

--------------------------------

### Install Docker Engine on Ubuntu

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

Installs Docker Engine, CLI, containerd.io, and plugins on Ubuntu systems. It involves updating package lists, installing prerequisites, adding the Docker GPG key and repository, and then installing the Docker packages. This script assumes a Debian-based system like Ubuntu.

```shell
+ sh -c apt-get -qq update >/dev/null
+ sh -c DEBIAN_FRONTEND=noninteractive apt-get -y -qq install ca-certificates curl >/dev/null
+ sh -c install -m 0755 -d /etc/apt/keyrings
+ sh -c curl -fsSL "https://download.docker.com/linux/ubuntu/gpg" -o /etc/apt/keyrings/docker.asc
+ sh -c chmod a+r /etc/apt/keyrings/docker.asc
+ sh -c echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu noble stable" > /etc/apt/sources.list.d/docker.list
+ sh -c apt-get -qq update >/dev/null
+ sh -c DEBIAN_FRONTEND=noninteractive apt-get -y -qq install docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-ce-rootless-extras docker-buildx-plugin >/dev/null
```

--------------------------------

### Generated Caddyfile Example

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

An example of a complete Caddyfile generated by Uncloud, showing global configuration, site definitions for services, and handling of invalid configurations.

```caddyfile
# This file is autogenerated by Uncloud based on the configuration of running services.
# Do not edit manually. Any manual changes will be overwritten on the next update.
  
# User-defined global config from service 'caddy'.
*.example.com {
	tls {
		dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	}
	respond "No host matched" 404
}
  
# Health check endpoint to verify Caddy reachability on this machine.
http:// {
	handle /.uncloud-verify {
		respond "a369b9388812f9557feef6a0f5b46f2e" 200
	}
	log
}
  
(common_proxy) {
	# Retry failed requests up to lb_retries times against other available upstreams.
	lb_retries 3
	# Upstreams are marked unhealthy for fail_duration after a failed request (passive health checking).
	fail_duration 30s
}
  
# Sites generated from service ports.
  
https://app.example.com {
	reverse_proxy 10.210.1.3:8000 10.210.2.5:8000 {
		import common_proxy
	}
	log
}
  
https://api.example.com {
	reverse_proxy 10.210.2.2:9000 10.210.1.7:9000 10.210.2.3:9000 {
		import common_proxy
	}
	log
}
  
# User-defined config for service 'web'.
www.example.com {
    redir https://example.com{uri} permanent
}
  
example.com {
    reverse_proxy 10.210.0.3:8000 {
        import common_proxy
    }
    log
}
  
# Skipped invalid user-defined configs:
# - service 'duplicate-hostname': validation failed: adapting config using caddyfile adapter: ambiguous site definition: example.com
# - service 'invalid': validation failed: adapting config using caddyfile adapter: Caddyfile:61: unrecognized directive: invalid_directive

```

--------------------------------

### Start Uncloud Machine Daemon

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

Starts the Uncloud machine daemon service. This ensures that the core Uncloud functionality is running and available to manage cluster resources.

```shell
⏳ Starting Uncloud machine daemon (uncloud.service)...
✓ Uncloud machine daemon started.
```

--------------------------------

### Verify Docker Installation

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

Checks the installed Docker version. This command is used to confirm that the Docker client and server components have been successfully installed and are running.

```shell
+ sh -c docker version
```

--------------------------------

### Install Uncloud CLI via GitHub Download (Linux AMD64)

Source: https://uncloud.run/docs/getting-started/install-cli

Manually downloads and installs the Uncloud CLI binary for Linux on AMD64 architecture from GitHub releases. It then moves the binary to 'uc'.

```shell
curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_linux_amd64.tar.gz | tar xz
mv uncloud uc
```

--------------------------------

### Initialize Uncloud Machine (CLI)

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

Initializes a Linux server as an Uncloud machine. This command installs Docker, the Uncloud daemon, sets up networking, and deploys Caddy as a reverse proxy. It also reserves a subdomain and points it to your server's IP. Use the -i flag if your SSH key is not in the SSH agent.

```bash
uc machine init root@<your-server-ip>
```

```bash
uc machine init root@<your-server-ip> -i ~/.ssh/id_xxx
```

--------------------------------

### Verify Uncloud CLI Installation

Source: https://uncloud.run/docs/getting-started/install-cli

Checks if the Uncloud CLI ('uc') is installed and accessible by running the version command.

```shell
uc --version
```

--------------------------------

### Install Uncloud CLI via GitHub Download (Linux ARM64)

Source: https://uncloud.run/docs/getting-started/install-cli

Manually downloads and installs the Uncloud CLI binary for Linux on ARM64 architecture from GitHub releases. It then moves the binary to 'uc'.

```shell
curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_linux_arm64.tar.gz | tar xz
mv uncloud uc
```

--------------------------------

### Caddyfile Configuration for Path-Based Routing

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

This Caddyfile configures example.com to route traffic based on the URL path. It directs requests starting with '/api/' to the 'api' service and all other requests to the default upstream. It also enables logging for requests.

```caddyfile
example.com {
    handle_path /api/* {
        reverse_proxy {{upstreams "api" 9000}} {
            import common_proxy
        }
    }

    reverse_proxy {{upstreams}} {
        import common_proxy
    }

    log
}

```

--------------------------------

### Mount Volumes and Configure Entrypoint

Source: https://uncloud.run/docs/cli-reference/uc_service_run

This example demonstrates mounting volumes (data volumes or host paths) into the service container and overriding the default entrypoint. This is useful for data persistence and customizing the container's startup behavior.

```bash
uc service run -v volume-name:/container/path --entrypoint "/app/start.sh" IMAGE
```

--------------------------------

### Install Uncloud CLI via GitHub Download (macOS Intel)

Source: https://uncloud.run/docs/getting-started/install-cli

Manually downloads and installs the Uncloud CLI binary for macOS on Intel architecture from GitHub releases. It then moves the binary to 'uc'.

```shell
curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_macos_amd64.tar.gz | tar xz
mv uncloud uc
```

--------------------------------

### Install Uncloud CLI on Debian

Source: https://uncloud.run/docs/getting-started/install-cli

Installs the Uncloud CLI on Debian-based systems using an unofficial repository. This involves adding the repository's GPG key and source list, then installing the package via apt.

```shell
curl -sS https://debian.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/debian.griffo.io.gpg
echo "deb https://debian.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/debian.griffo.io.list
apt install -y uncloud
```

--------------------------------

### Move Uncloud CLI to System PATH

Source: https://uncloud.run/docs/getting-started/install-cli

Moves the downloaded Uncloud CLI binary ('uc') to a system-wide PATH directory, allowing it to be executed from any location.

```shell
sudo mv ./uc /usr/local/bin
```

--------------------------------

### Configure Service Resources and Environment

Source: https://uncloud.run/docs/cli-reference/uc_service_run

This example shows how to configure CPU and memory limits for a service container, along with setting environment variables. These options are crucial for managing resource consumption and application behavior.

```bash
uc service run --cpu 0.5 --memory 512m -e VAR_NAME=value IMAGE
```

--------------------------------

### Install Uncloud CLI using Homebrew

Source: https://uncloud.run/docs/getting-started/install-cli

Installs or upgrades the Uncloud CLI using the Homebrew package manager on macOS and Linux. Requires Homebrew to be pre-installed.

```shell
brew install psviderski/tap/uncloud
```

```shell
brew upgrade uncloud
```

--------------------------------

### List All Deployed Services and Endpoints with Uncloud CLI

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

This command lists all currently deployed services on Uncloud, including their mode, replica count, and public endpoints. It helps in getting an overview of all running services and their accessibility.

```bash
uc ls
```

--------------------------------

### Install Uncloud CLI via GitHub Download (macOS ARM64)

Source: https://uncloud.run/docs/getting-started/install-cli

Manually downloads and installs the Uncloud CLI binary for macOS on Apple Silicon architecture from GitHub releases. It then moves the binary to 'uc'.

```shell
curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_macos_arm64.tar.gz | tar xz
mv uncloud uc
```

--------------------------------

### Custom Caddy Configuration using Compose x-caddy Extension

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

This YAML snippet illustrates how to provide a custom Caddyfile configuration for a service using the `x-caddy` extension in a Compose file. It includes examples of redirects, basic authentication, header manipulation, and reverse proxying.

```yaml
services:
  app:
    image: app:latest
    x-caddy: |
      www.example.com {
          redir https://example.com{uri} permanent
      }

      example.com {
          basic_auth /admin/* {
              admin $2a$14$...
          }

          header /static/* Cache-Control max-age=604800
          reverse_proxy {{upstreams 8000}}
              import common_proxy
          log
      }
```

--------------------------------

### Deploy Caddy with Custom Global Configuration (CLI)

Source: https://uncloud.run/docs/concepts/ingress/managing-caddy

This command enables the deployment of Caddy with a custom global configuration file. The '--caddyfile' flag specifies the path to your custom Caddyfile, allowing for advanced configurations such as custom snippets, TLS settings, and reverse proxy rules. The provided Caddyfile example demonstrates global options and a reusable snippet.

```bash
uc caddy deploy --caddyfile global.Caddyfile
```

```caddyfile
# Global options.  
{
    debug
}

# A snippet that can be reused in custom Caddy configs for services (x-caddy).  
(my_snippet) {
    ...
}

# Expose an internal service that is not managed by Uncloud.  
internal.example.com {
    reverse_proxy 192.168.1.100
}

```

--------------------------------

### List Services with uc ls Command

Source: https://uncloud.run/docs/cli-reference/uc_ls

This command lists all services managed by Uncloud. It accepts flags to specify the cluster context. Ensure the Uncloud CLI is installed and configured to use this command.

```bash
uc ls [flags]
```

--------------------------------

### Deploy Caddy using Compose File

Source: https://uncloud.run/docs/concepts/ingress/managing-caddy

This section details how to manage Caddy deployment using a Docker Compose file for enhanced control. The provided `compose.yaml` example shows how to configure Caddy with a custom image, command, environment variables, volumes, and network ports. It also includes a sample Caddyfile for wildcard TLS certificate generation using Cloudflare DNS.

```yaml
services:
  caddy:
    image: caddybuilds/caddy-cloudflare:2.10.2
    command: caddy run -c /config/Caddyfile
    environment:
      CADDY_ADMIN: unix//run/caddy/admin.sock
    env_file:
      # Contains CLOUDFLARE_API_TOKEN=xxxxx
      - .env.secrets
    volumes:
      - /var/lib/uncloud/caddy:/data
      - /var/lib/uncloud/caddy:/config
      - /run/uncloud/caddy:/run/caddy
    x-ports:
      - 80:80@host
      - 443:443@host
    x-caddy: Caddyfile
    deploy:
      mode: global

```

```caddyfile
# Global options.  
{
    debug
}

# A snippet that can be reused in custom Caddy configs for services (x-caddy).  
(my_snippet) {
    ...
}

# Obtain a wildcard TLS certificate for all subdomains of example.name using DNS challenge with Cloudflare.  
# It will be used for services that publish ports with hostnames under example.name.  
*.example.com {
    tls {
            dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
    respond "No host matched" 404
}

# Expose an internal service that is not managed by Uncloud.  
internal.example.com {
    reverse_proxy 192.168.1.100
}

```

--------------------------------

### Specify User and Pull Policy

Source: https://uncloud.run/docs/cli-reference/uc_service_run

This example shows how to specify the user and group for running the command inside the service container and define the image pull policy. These options help in controlling execution context and image update behavior.

```bash
uc service run --user user:group --pull always IMAGE
```

--------------------------------

### Mount volumes with uc run

Source: https://uncloud.run/docs/cli-reference/uc_run

This example demonstrates how to mount data volumes or host paths into service containers using the '-v' or '--volume' flag. It covers both named volume mounts and bind mounts, including read-only options. This is vital for persistent storage and data sharing between the host and containers.

```bash
# Mount named volume 'postgres-data' to container path
uc run -v postgres-data:/var/lib/postgresql/data IMAGE

# Bind mount host directory '/data/uploads' to container path
uc run -v /data/uploads:/app/uploads IMAGE

# Bind mount a host directory as read-only
uc run -v /host/path:/container/path:ro IMAGE
```

--------------------------------

### Release Reserved Cluster Domain (Shell)

Source: https://uncloud.run/docs/cli-reference/uc_dns_release

This command releases a reserved cluster domain. It accepts a context flag to specify the target cluster. Dependencies include the Uncloud CLI being installed and configured.

```shell
uc dns release [flags]

Options:
  -c, --context string   Name of the cluster context. (default is the current context)
  -h, --help             help for release

Options inherited from parent commands:
      --connect string          Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT]
                                Format: [ssh://]user@host[:port] or tcp://host:port
      --uncloud-config string   Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default "~/.config/uncloud/config.yaml")
```

--------------------------------

### Deploy or Update Caddy Latest Stable Version (CLI)

Source: https://uncloud.run/docs/concepts/ingress/managing-caddy

This CLI command deploys or updates the Caddy service to the latest stable version by utilizing the official 'caddy' image from Docker Hub. Ensure you have the 'uc' CLI installed and configured for your Uncloud cluster.

```bash
uc caddy deploy
```

--------------------------------

### Set service replication mode with uc run

Source: https://uncloud.run/docs/cli-reference/uc_run

This example demonstrates setting the replication mode for a service using the '--mode' flag. Services can be 'replicated' (multiple instances) or 'global' (one instance per machine). The '--replicas' flag specifies the number of instances for replicated services.

```bash
# Run a replicated service with 3 instances
uc run --mode replicated --replicas 3 IMAGE

# Run a global service (one instance per machine)
uc run --mode global IMAGE
```

--------------------------------

### Configure service environment variables with uc run

Source: https://uncloud.run/docs/cli-reference/uc_run

This example shows how to set environment variables for a service container using the '-e' or '--env' flag. Environment variables can be set directly using 'VAR=value' or by referencing existing environment variables on the local machine by just providing 'VAR'. This is crucial for configuring application settings within containers.

```bash
# Set environment variable VAR to value
uc run --env VAR=value IMAGE

# Use local environment variable value for VAR
uc run --env VAR IMAGE
```

--------------------------------

### Add Remote Machine to Uncloud Cluster

Source: https://uncloud.run/docs/cli-reference/uc_machine_add

This command adds a remote machine to an Uncloud cluster. It requires the user and host of the machine, optionally including a port. Various flags allow for customization, such as specifying the cluster context, assigning a name to the machine, controlling the Caddy reverse proxy deployment, skipping initial installations, configuring public IP for ingress, and providing an SSH key path.

```bash
uc machine add [USER@]HOST[:PORT] [flags]
```

--------------------------------

### Caddyfile for Main Domain Proxy with Templates

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

A Caddyfile configuration for the main domain 'example.com', using a template to dynamically proxy requests to upstreams on port 8000 and importing common proxy settings.

```caddyfile
example.com {
    reverse_proxy {{upstreams 8000}} {
        import common_proxy
    }
    log
}

```

--------------------------------

### Caddyfile for www Redirect

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

A Caddyfile configuration demonstrating how to redirect traffic from 'www.example.com' to 'example.com' using the 'redir' directive.

```caddyfile
www.example.com {
    redir https://example.com{uri} permanent
}

```

--------------------------------

### Run a Service with Basic Configuration

Source: https://uncloud.run/docs/cli-reference/uc_service_run

This snippet demonstrates the basic usage of the 'uc service run' command to deploy a service using a specified image and optionally a command. It highlights the core arguments required for service execution.

```bash
uc service run IMAGE [COMMAND...]
```

--------------------------------

### Execute uc ctx Command

Source: https://uncloud.run/docs/cli-reference/uc_ctx

This snippet shows the basic execution of the 'uc ctx' command. It requires no specific inputs but can accept flags for help.

```bash
uc ctx [flags]
```

--------------------------------

### List Uncloud Cluster Contexts (Shell)

Source: https://uncloud.run/docs/cli-reference/uc_ctx_ls

Lists all available cluster contexts configured in Uncloud. It accepts a help flag and can inherit connection details and configuration file paths from parent commands.

```shell
uc ctx ls [flags]

Flags:
  -h, --help   help for ls

Inherited options:
      --connect string          Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT]
                                Format: [ssh://]user@host[:port] or tcp://host:port
      --uncloud-config string   Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default "~/.config/uncloud/config.yaml")
```

--------------------------------

### Create Volume Command Syntax

Source: https://uncloud.run/docs/cli-reference/uc_volume_create

This snippet shows the basic command-line syntax for creating a volume. It requires a volume name and accepts several optional flags for configuration. The default driver is 'local'.

```bash
uc volume create VOLUME_NAME [flags]
```

--------------------------------

### Help Options for uc volume

Source: https://uncloud.run/docs/cli-reference/uc_volume

Displays help information for the 'uc volume' command. This is useful for understanding the available subcommands and their usage.

```bash
  -h, --help   help for volume  
```

--------------------------------

### Display help for uc service command

Source: https://uncloud.run/docs/cli-reference/uc_service

This code snippet displays the help information for the 'uc service' command. It shows the available flags and their descriptions. No specific dependencies are required beyond the 'uc' CLI tool.

```bash
uc service --help
```

--------------------------------

### Caddy Deploy Command Options

Source: https://uncloud.run/docs/cli-reference/uc_caddy_deploy

Lists the available options for the 'uc caddy deploy' command, including arguments for custom Caddyfile, context, image, and specific machines.

```bash
      --caddyfile string   Path to a custom global Caddy config (Caddyfile) that will be prepended to the auto-generated Caddy config.  
  -c, --context string     Name of the cluster context to deploy to. (default is the current context)  
  -h, --help               help for deploy  
      --image string       Caddy Docker image to deploy. (default caddy:LATEST_VERSION)  
  -m, --machine strings    Machine names to deploy to. Can be specified multiple times or as a comma-separated list of machine names. (default is all machines)  
```

--------------------------------

### Deploy Excalidraw Service using Uncloud CLI

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

This command deploys the Excalidraw service from its official Docker image. It publishes the container's port 80 as an HTTPS endpoint on a reserved domain. The output shows the deployment progress and the public URL.

```bash
uc run --name excalidraw --publish 80/https excalidraw/excalidraw
```

--------------------------------

### Publish Service with HTTPS via Caddy using uc run

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

This command publishes a service container port 8000 and makes it accessible via HTTPS through a Caddy reverse proxy at the specified hostname 'app.example.com'. DNS records must be configured to point to the machine's IP address.

```bash
uc run -p app.example.com:8000/https app:latest
```

--------------------------------

### Deploy Caddy Service and Verify Access

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

Deploys the Caddy service within the Uncloud cluster and updates DNS records to point to the running Caddy instances. It then verifies internet accessibility to the deployed service.

```shell
[+] Deploying service caddy 7/2
 ✔ Container caddy-d7uk on machine-dc3c     Started                                            6.1s
   ✔ Image caddy:2.10.0 on machine-dc3c       Pulled                                           3.7s

Updating cluster domain records in Uncloud DNS to point to machines running caddy service...
[+] Verifying internet access to caddy service 1/1
 ✔ Machine machine-dc3c (157.180.72.195)  Reachable                                            0.7s

DNS records updated to use only the internet-reachable machines running caddy service:
  *.7za6s7.cluster.uncloud.run  A → 157.180.72.195
```

--------------------------------

### Caddyfile Template: Dynamic Upstream Proxy

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

Demonstrates using Go templates within Caddyfile configurations to dynamically proxy requests to healthy service upstreams. Supports specifying service name, port, and scheme for flexible routing.

```caddyfile
reverse_proxy {{upstreams}}

```

```caddyfile
reverse_proxy {{upstreams 8000}}

```

```caddyfile
reverse_proxy {{- range $ip := index .Upstreams .Name}} https://{{$ip}}{{end}}

```

```caddyfile
handle_path /api/* {
    reverse_proxy {{upstreams "api" 9000}}
}

```

--------------------------------

### Help Option for uc ctx

Source: https://uncloud.run/docs/cli-reference/uc_ctx

This snippet demonstrates how to access help information for the 'uc ctx' command. It uses the standard '--help' flag.

```bash
uc ctx --help
```

--------------------------------

### Uncloud CLI Options

Source: https://uncloud.run/docs/cli-reference/uc

This snippet details the available command-line options for the 'uc' CLI tool. It includes flags for connecting to remote clusters and specifying configuration file paths, along with their default values and environment variable overrides.

```bash
uc --connect string          Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT]
                                Format: [ssh://]user@host[:port] or tcp://host:port
  -h, --help                    help for uc
      --uncloud-config string   Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default "~/.config/uncloud/config.yaml")
```

--------------------------------

### Volume Creation Options

Source: https://uncloud.run/docs/cli-reference/uc_volume_create

This snippet details the available options for the 'uc volume create' command. These options allow customization of the volume's context, driver, labels, the target machine, and driver-specific parameters.

```bash
  -c, --context string   Name of the cluster context. (default is the current context)
  -d, --driver string    Volume driver to use. (default "local")
  -h, --help             help for create
  -l, --label strings    Labels to assign to the volume in the form of 'key=value' pairs. Can be specified multiple times.
  -m, --machine string   Name or ID of the machine to create the volume on.
  -o, --opt strings      Driver specific options in the form of 'key=value' pairs. Can be specified multiple times.
```

--------------------------------

### Caddy Deploy Command Synopsis

Source: https://uncloud.run/docs/cli-reference/uc_caddy_deploy

This is the basic command synopsis for deploying or upgrading Caddy. It shows the command and its potential flags.

```bash
uc caddy deploy [flags]
```

--------------------------------

### Inspect Excalidraw Service Status with Uncloud CLI

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

After deployment, this command inspects the Excalidraw service to check its status and retrieve detailed information, including container status and machine assignment. The output confirms if the container is running and healthy.

```bash
uc inspect excalidraw
```

--------------------------------

### Verify Caddy Configuration (CLI)

Source: https://uncloud.run/docs/concepts/ingress/managing-caddy

This command displays the complete, generated Caddyfile that is currently being served by the 'caddy' service. It's invaluable for debugging and verifying both custom global configurations and service-specific Caddy configurations. The output shows the combined configuration, including user-defined settings and auto-generated rules for services.

```bash
uc caddy config
```

```caddyfile
# This file is autogenerated by Uncloud based on the configuration of running services.  
# Do not edit manually. Any manual changes will be overwritten on the next update.  

# User-defined global config from service 'caddy'.  
# Global options.  
{
    debug
}

# A snippet that can be reused in custom Caddy configs for services (x-caddy).  
(my_snippet) {
    ...
}

# Obtain a wildcard TLS certificate for all subdomains of example.name using DNS challenge with Cloudflare.  
# It will be used for services that publish ports with hostnames under example.name.  
*.example.com {
    tls {
            dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
    respond "No host matched" 404
}

# Expose an internal service that is not managed by Uncloud.  
internal.example.com {
    reverse_proxy 192.168.1.100
}

# Health check endpoint to verify Caddy reachability on this machine.  
http:// {
	handle /.uncloud-verify {
		respond "a369b9388812f9557feef6a0f5b46f2e" 200
	}
	log
}

(common_proxy) {
	# Retry failed requests up to lb_retries times against other available upstreams.  
	lb_retries 3
	# Upstreams are marked unhealthy for fail_duration after a failed request (passive health checking).  
	fail_duration 30s
}

# Sites generated from service ports.  

https://app.example.com {
	reverse_proxy 10.210.1.3:8000 10.210.2.5:8000 {
		import common_proxy
	}
	log
}

https://api.example.com {
	reverse_proxy 10.210.2.2:9000 10.210.1.7:9000 10.210.2.3:9000 {
		import common_proxy
	}
	log
}

```

--------------------------------

### Update Excalidraw Service with Custom Domain in Docker Compose

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

This snippet shows how to update the `compose.yaml` file to use a custom domain (e.g., `excalidraw.example.com`) for the Excalidraw service. The `x-ports` key is modified to include the custom domain and port.

```yaml
...
x-ports:
  - excalidraw.example.com:80/https
```

--------------------------------

### uc build Command Options

Source: https://uncloud.run/docs/cli-reference/uc_build

This snippet details the available options for the 'uc build' command. These options control aspects like the Compose file used, cache behavior, profiles, and image pushing.

```bash
  -f, --file strings      One or more Compose files to build (default compose.yaml)
  -h, --help              help for build
  -n, --no-cache          Do not use cache when building images. (default false)
  -p, --profile strings   One or more Compose profiles to enable.
  -P, --push              Push built images to the registry after building. (default false)
```

--------------------------------

### uc build Inherited Options

Source: https://uncloud.run/docs/cli-reference/uc_build

This snippet lists options inherited by the 'uc build' command from its parent commands. These relate to connecting to remote clusters and specifying Uncloud configuration files.

```bash
      --connect string          Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT]
                                Format: [ssh://]user@host[:port] or tcp://host:port
      --uncloud-config string   Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default "~/.config/uncloud/config.yaml")
```

--------------------------------

### Run a service with uc run

Source: https://uncloud.run/docs/cli-reference/uc_run

This snippet demonstrates the basic syntax for the 'uc run' command. It specifies the Docker image to use and optionally allows for overriding the default command and passing specific flags. This is the foundational command for deploying services.

```bash
uc run IMAGE [COMMAND...] [flags]
```

--------------------------------

### POST /websites/uncloud_run

Source: https://uncloud.run/docs/cli-reference/uc_service_run

The 'uc service run' command deploys a service to the Uncloud cluster. You specify the Docker image, optional command, and various flags to configure the service's behavior, resources, networking, and storage.

```APIDOC
## POST /websites/uncloud_run

### Description
Runs a specified service image with a given command and configuration flags within the Uncloud cluster.

### Method
POST

### Endpoint
/websites/uncloud_run

### Parameters
#### Path Parameters
- **IMAGE** (string) - Required - The Docker image to run for the service.
- **COMMAND...** (string) - Optional - The command to execute within the service container.

#### Query Parameters
- **caddyfile** (string) - Optional - Path to a custom Caddy configuration file.
- **context** (string) - Optional - Name of the cluster context to use.
- **cpu** (decimal) - Optional - Maximum CPU cores the service container can use.
- **entrypoint** (string) - Optional - Overwrite the default ENTRYPOINT of the image.
- **env** (strings) - Optional - Environment variables for the service containers (e.g., VAR=value).
- **machine** (strings) - Optional - Placement constraint by machine names.
- **memory** (bytes) - Optional - Maximum memory the service container can use (e.g., 1g, 1024m).
- **mode** (string) - Optional - Replication mode ('replicated' or 'global'). Defaults to 'replicated'.
- **name** (string) - Optional - Assign a name to the service.
- **privileged** (boolean) - Optional - Grant extended privileges to service containers.
- **publish** (strings) - Optional - Publish service ports (e.g., '8080/https', '53:5353/udp').
- **pull** (string) - Optional - Pull strategy for the image ('always', 'missing', 'never'). Defaults to 'missing'.
- **replicas** (uint) - Optional - Number of containers to run for a replicated service.
- **user** (string) - Optional - User name or UID for running the command inside containers (e.g., 'USER:GROUP').
- **volume** (strings) - Optional - Mount data volumes or host paths into containers (e.g., 'volume_name:/container/path').
- **connect** (string) - Optional - Connect to a remote cluster machine.
- **uncloud-config** (string) - Optional - Path to the Uncloud configuration file.

### Request Example
```json
{
  "image": "my-app:latest",
  "command": ["run", "--config", "/etc/app.conf"],
  "env": ["DB_HOST=localhost", "PORT=8080"],
  "publish": ["8080:8080"],
  "replicas": 3
}
```

### Response
#### Success Response (200)
- **service_id** (string) - The ID of the newly created service.
- **status** (string) - The deployment status of the service.

#### Response Example
```json
{
  "service_id": "srv-abcdef123456",
  "status": "running"
}
```
```

--------------------------------

### Inspect Command Options

Source: https://uncloud.run/docs/cli-reference/uc_inspect

This section details the available options for the 'uc inspect' command. These include specifying the cluster context and accessing help information.

```bash
-c, --context string   Name of the cluster context. (default is the current context)
-h, --help             help for inspect
```

--------------------------------

### Docker Compose Configuration for Multiple Services

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

This docker-compose.yaml file defines two services, 'api' and 'web', intended to be published on the same domain using different paths. It specifies the Docker images for each service and includes a Caddy configuration directive for the 'web' service.

```yaml
services:
  api:
    image: api:latest
  web:
    image: web:latest
    # Make sure only one service defines a Caddy config for the hostname.
    x-caddy: ./Caddyfile

```

--------------------------------

### List Uncloud Services (CLI)

Source: https://uncloud.run/docs/cli-reference/uc_service_ls

The 'uc service ls' command lists all services currently deployed in an Uncloud cluster. It accepts optional flags to specify the cluster context, view help information, establish remote connections, and define the configuration file path.

```bash
uc service ls [flags]
```

```bash
# Example with context flag:
nc service ls -c my-cluster-context
```

```bash
# Example with help flag:
nc service ls --help
```

--------------------------------

### Display Help for uc caddy Command

Source: https://uncloud.run/docs/cli-reference/uc_caddy

This option displays the help message for the 'uc caddy' command, outlining its available flags and functionalities. It does not require any specific inputs.

```bash
uc caddy --help
```

--------------------------------

### Define Excalidraw Service in Docker Compose Format

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

This `compose.yaml` file defines the Excalidraw service using Docker Compose syntax, with an Uncloud-specific `x-ports` key to publish port 80 as an HTTPS endpoint. This configuration can be version-controlled and deployed with a single command.

```yaml
services:
  excalidraw:
    image: excalidraw/excalidraw
    x-ports:
      - 80/https
```

--------------------------------

### Uninstall Uncloud Completely using CLI

Source: https://uncloud.run/docs/getting-started/deploy-demo-app

This command performs a full uninstallation of Uncloud from your server. It removes all Uncloud-managed containers, networks, system services, binaries, and data, cleaning up the system completely.

```bash
sudo uncloud-uninstall
```

--------------------------------

### Docker Compose for Caddy and App Service

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

A Docker Compose configuration snippet defining an 'app' service that uses a local Caddyfile for its configuration.

```yaml
services:
  app:
    image: app:latest
    x-caddy: ./Caddyfile

```

--------------------------------

### Display Help for uc machine

Source: https://uncloud.run/docs/cli-reference/uc_machine

Displays the help message for the 'uc machine' command, outlining its available options and usage. This is a standard CLI help command.

```bash
uc machine --help
```

--------------------------------

### uc build Command Usage

Source: https://uncloud.run/docs/cli-reference/uc_build

This snippet shows the general usage of the 'uc build' command and its parameters. It is the primary command for initiating service builds within Uncloud.

```bash
uc build [FLAGS] [SERVICE...] [flags]
```

--------------------------------

### Volume Inspect Command Options

Source: https://uncloud.run/docs/cli-reference/uc_volume_inspect

This snippet details the specific options available for the 'uc volume inspect' command. These include specifying the cluster context, accessing help, and identifying the machine hosting the volume.

```bash
-c, --context string   Name of the cluster context. (default is the current context)
-h, --help             help for inspect
-m, --machine string   Name or ID of the machine where the volume is located. If not specified, the volume will be searched across all machines.
```

--------------------------------

### Inherited Options for Caddy Deploy

Source: https://uncloud.run/docs/cli-reference/uc_caddy_deploy

Shows options inherited from parent commands, such as connecting to a remote cluster or specifying the Uncloud configuration file path.

```bash
      --connect string          Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT]  
                                Format: [ssh://]user@host[:port] or tcp://host:port  
      --uncloud-config string   Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default "~/.config/uncloud/config.yaml")  
```

--------------------------------

### Display DNS Help Options

Source: https://uncloud.run/docs/cli-reference/uc_dns

Displays the help message for the 'uc dns' command and its available options. This is useful for understanding the command's functionality and parameters.

```bash
uc dns --help
```

--------------------------------

### Deploy Specific Caddy Version or Custom Image (CLI)

Source: https://uncloud.run/docs/concepts/ingress/managing-caddy

This command allows for the deployment of a specific version of Caddy or a custom Caddy image. You can specify the image using the '--image' flag, pointing to a Docker image hosted on a registry like Docker Hub. This provides flexibility for testing or using custom Caddy builds.

```bash
uc caddy deploy --image caddybuilds/caddy-cloudflare:2.10.2
```

--------------------------------

### Advanced Port Publishing Options

Source: https://uncloud.run/docs/cli-reference/uc_service_run

This snippet showcases advanced port publishing configurations, including specifying protocols (http, https, udp) and binding to specific host IPs or host ports. It also shows how to use custom hostnames for reverse proxying.

```bash
uc service run -p app.example.com:8080/https -p 53:5353/udp@host IMAGE
```

--------------------------------

### Inspect Service Command Options

Source: https://uncloud.run/docs/cli-reference/uc_service_inspect

This section details the specific options available for the `uc service inspect` command, including context selection and help flags. These options control how the command interacts with the Uncloud cluster.

```bash
  -c, --context string   Name of the cluster context. (default is the current context)
  -h, --help             help for inspect
```

--------------------------------

### Caddyfile Configuration for 'web' Service

Source: https://uncloud.run/docs/concepts/ingress/managing-caddy

This configuration defines how Caddy handles traffic for the 'web' service. It includes directives for domain management, permanent redirection, and reverse proxying to a backend. The configuration assumes the use of common proxy settings and logging.

```caddyfile
www.example.com {
    redir https://example.com{uri} permanent
}

example.com {
    reverse_proxy 10.210.0.3:8000 {
        import common_proxy
    }
    log
}
```

--------------------------------

### Publish HTTP/HTTPS Ports using uc run -p Flag or x-ports

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

Defines the format for publishing HTTP/HTTPS ports. The optional 'hostname' specifies the domain, 'container_port' is the port within the container, and 'protocol' (http/https) defaults to https. If hostname is omitted, it defaults to '<service-name>.<cluster-domain>'.

```syntax
[hostname:]container_port[/protocol]
```

--------------------------------

### Uncloud Machine Token Command Options

Source: https://uncloud.run/docs/cli-reference/uc_machine_token

Details the specific options available for the 'uc machine token' command, including the data directory flag and help option. These options control the behavior and storage of machine state.

```bash
  -d, --data-dir string   Directory for storing persistent machine state. (default "/var/lib/uncloud")  
  -h, --help              help for token  
```

--------------------------------

### Deploy Service from Compose File (CLI)

Source: https://uncloud.run/docs/concepts/ingress/managing-caddy

This command deploys or updates services defined in the `compose.yaml` file. It's used after modifying the Compose file to apply the changes to your Uncloud cluster, including the Caddy service if it's defined there.

```bash
uc deploy
```

--------------------------------

### Switch Cluster Context using uc ctx use

Source: https://uncloud.run/docs/cli-reference/uc_ctx_use

The 'uc ctx use' command switches the current Uncloud cluster context. If no context name is provided, it lists available contexts for interactive selection. It supports specifying connection details and configuration file paths.

```bash
uc ctx use [CONTEXT] [flags]

Options:
  -h, --help   help for use

Options inherited from parent commands:
      --connect string          Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT]  
                                Format: [ssh://]user@host[:port] or tcp://host:port  
      --uncloud-config string   Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default "~/.config/uncloud/config.yaml")
```

--------------------------------

### Specify Uncloud Configuration File Option

Source: https://uncloud.run/docs/cli-reference/uc_ctx

This snippet illustrates how to use the '--uncloud-config' option to specify the path to the Uncloud configuration file. It defaults to '~/.config/uncloud/config.yaml'.

```bash
--uncloud-config string Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default "~/.config/uncloud/config.yaml")
```

--------------------------------

### Publish Service Ports using Compose x-ports Extension

Source: https://uncloud.run/docs/concepts/ingress/publishing-services

This YAML snippet demonstrates how to publish service ports using the `x-ports` extension in a Compose file. It shows publishing port 8000 as HTTPS with multiple hostnames and another port 9000 with a different hostname.

```yaml
services:
  app:
    image: app:latest
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
      - api.domain.tld:9000/https
```

--------------------------------

### Initialize Uncloud Cluster with Remote Machine (Shell)

Source: https://uncloud.run/docs/cli-reference/uc_machine_init

Initialises a new Uncloud cluster by setting up a remote machine as the first member. This command creates a new context in your Uncloud config to manage the cluster. It supports various flags for customization, such as specifying SSH keys, context names, machine names, and disabling services like Caddy or DNS.

```shell
uc machine init [USER@HOST:PORT] [flags]

# Examples:
# Initialise a new cluster with default settings.
uc machine init root@<your-server-ip>

# Initialise with a context name 'prod' and machine name 'vps1'.
uc machine init root@<your-server-ip> -c prod -n vps1

# Initialise with a non-root user and custom SSH port and key.
uc machine init ubuntu@<your-server-ip>:2222 -i ~/.ssh/mykey

# Initialise without Caddy and without an automatically managed domain name.
uc machine init root@<your-server-ip> --no-caddy --no-dns
```
Tokens:
Raw