Merge branch 'docs/uncloud-config'

cmd/uncloud/machine/init.go

@@ -151,7 +151,10 @@ Connection methods:
 func initCluster(ctx context.Context, uncli *cli.CLI, remoteMachine *cli.RemoteMachine, opts initOptions) error {
 	if uncli.Config == nil {
 		// Config is nil when connecting directly to a remote machine (--connect) without using Uncloud config.
-		return fmt.Errorf("do not specify --connect when initialising a new cluster")
+		return fmt.Errorf(
+			"do not use --connect when initialising a new cluster: --connect is for overriding the connection " +
+				"to an existing cluster, but 'machine init' creates a new one and writes the new cluster context " +
+				"to the Uncloud config file (--uncloud-config)")
 	}
 
 	netPrefix, err := netip.ParsePrefix(opts.network)

website/docs/2-getting-started/2-deploy-demo-app.md

@@ -446,6 +446,6 @@ Note: Docker installation was preserved. If you want to completely remove Docker
 ## Further reading
 
 - **[Add more machines](../9-cli-reference/uc_machine_add.md)**: Scale horizontally by creating a cluster of machines
-- **[Ingress & HTTP](../3-concepts/1-ingress/1-overview.md)**: Learn how Uncloud handles incoming traffic and how to
+- **[Ingress & HTTP](../3-concepts/2-ingress/1-overview.md)**: Learn how Uncloud handles incoming traffic and how to
   expose your services to the internet
 - **[CLI reference](../9-cli-reference/uc.md)**: Explore all available commands and options

website/docs/3-concepts/1-clusters/1-connecting.md

@@ -0,0 +1,90 @@
+# 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](../../7-cli-config-reference.md)
+(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
+
+The [config file](../../7-cli-config-reference.md) 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
+
+Use these commands to manage the contexts in your config:
+
+- [`uc ctx`](../../9-cli-reference/uc_ctx.md): Switch contexts using an interactive TUI
+- [`uc ctx ls`](../../9-cli-reference/uc_ctx_ls.md): List all contexts and see which one is current
+- [`uc ctx use`](../../9-cli-reference/uc_ctx_use.md): Switch the current context by name
+- [`uc ctx conn`](../../9-cli-reference/uc_ctx_connection.md): 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](../../4-guides/1-deployments/1-deploy-app.md#deploy-to-a-specific-cluster-context)
+for details.
+
+## Connection resolution
+
+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.
+
+## Global flags and environment variables
+
+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
+
+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:
+
+```shell
+# System 'ssh' command with full SSH config support
+uc --connect root@203.0.113.1 ls
+
+# System 'ssh' command (explicit scheme, same as above)
+uc --connect ssh://root@203.0.113.1 ls
+
+# Go's built-in SSH library (no SSH config support, useful when the system ssh is not available)
+uc --connect ssh+go://root@203.0.113.1 ls
+
+# Direct connection to machine gRPC API over TCP (for advanced users with custom setups)
+uc --connect tcp://[fdcc:4439:f545:3ca:5d17:66e5:7c96:40bd]:51000 ls
+
+# Direct connection to machine gRPC API over a Unix socket (for running uc locally on a cluster machine)
+uc --connect unix:///run/uncloud/uncloud.sock ls
+```
+
+:::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.
+
+:::

website/docs/3-concepts/1-clusters/_category_.yaml

@@ -0,0 +1,4 @@
+label: Clusters
+collapsed: true # keep the category closed by default
+link:
+  type: generated-index

website/docs/4-guides/1-deployments/4-rolling-deployments.md

@@ -131,7 +131,7 @@ services:
 :::info important
 
 If a health check fails after the deployment, Uncloud automatically removes the unhealthy container from the
-[Caddy](../../3-concepts/1-ingress/1-overview.md) configuration to prevent routing traffic to that container. But it
+[Caddy](../../3-concepts/2-ingress/1-overview.md) 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

website/docs/7-cli-config-reference.md

@@ -0,0 +1,115 @@
+# CLI configuration file
+
+The [`uc`](2-getting-started/1-install-cli.md) CLI stores **cluster connection details** in a YAML configuration file.
+Every time you run a command like `uc ls` or `uc deploy`, it reads this file to figure out which cluster to connect to
+and how to reach its machines over SSH.
+
+You rarely need to edit this file by hand. `uc` creates and updates it automatically when you run commands like
+`uc machine init`, `uc machine add`, or `uc ctx`.
+
+## Config location
+
+The default config file path is `~/.config/uncloud/config.yaml`. You can change this with the `--uncloud-config`
+global flag or the `UNCLOUD_CONFIG` environment variable:
+
+```shell
+# Use a custom config file for this command
+uc --uncloud-config ./my-config.yaml ls
+
+# Or set the environment variable to use a custom config file for all commands
+export UNCLOUD_CONFIG=~/my-uncloud-config.yaml
+uc ls
+```
+
+## Config structure
+
+Here is an example config file for a setup with two clusters, `prod` and `dev`:
+
+```yaml title="~/.config/uncloud/config.yaml"
+current_context: prod
+contexts:
+  prod:
+    connections:
+      - ssh: user@137.123.45.67
+      - ssh: myserver  # host alias from SSH config
+  dev:
+    connections:
+      - ssh: ubuntu@dev.example.com
+        ssh_key_file: ~/.ssh/id_ed25519
+        machine_id: 3f60c88ac6b0f250d8aecb92a090922f
+```
+
+The config has two top-level attributes: `current_context` and `contexts`.
+
+### `current_context`
+
+The name of the active context. `uc` uses this context by default when you run any command. You can switch to a
+different context with an interactive [`uc ctx`](9-cli-reference/uc_ctx.md) command, non-interactively with
+[`uc ctx use`](9-cli-reference/uc_ctx_use.md), or the `--context` flag.
+
+### `contexts`
+
+A map of named contexts. Each context represents a cluster and contains a list of machine connections.
+
+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. Two people on the same team can have different contexts pointing to the same cluster,
+each with their own preferred connection.
+
+See [Connecting to a cluster](3-concepts/1-clusters/1-connecting.md#cluster-contexts) for more details and examples.
+
+### `connections`
+
+Each connection in the list represents a machine in the 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.
+
+The first connection in the list is the default one that `uc` tries first. If it's unavailable, `uc` moves on to the
+next one. You can change the default connection with an interactive command
+[`uc ctx conn`](9-cli-reference/uc_ctx_connection.md).
+
+Every connection must have exactly one connection type attribute:
+
+| Attribute | Format                      | Description                                                                                                                        |
+|-----------|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------|
+| `ssh`     | `user@host[:port]`          | Connect using the system `ssh` command with full SSH config support (default for new connections added with `uc machine init/add`) |
+| `ssh_go`  | `user@host[:port]`          | Connect using Go's built-in SSH library (no SSH config support)                                                                |
+| `tcp`     | `host:port`                 | Connect directly to the machine gRPC API over TCP (for advanced users with custom setups)                                          |
+| `unix`    | `/run/uncloud/uncloud.sock` | Connect directly to the machine gRPC API over a Unix socket (for running `uc` locally on the cluster machines)                     |
+
+A connection can also have these optional attributes:
+
+| Attribute      | Description                                                                                                             |
+|----------------|-------------------------------------------------------------------------------------------------------------------------|
+| `ssh_key_file` | Path to the SSH private key for this machine (maps to `-i` in the `ssh` command)                                        |
+| `machine_id`   | Unique identifier of the machine (used to match and remove the connection when removing a machine with `uc machine rm`) |
+
+## How the config gets created and updated
+
+You don't typically need to create or edit the config file manually. `uc` creates and manages it for you:
+
+- [`uc machine init`](9-cli-reference/uc_machine_init.md) creates a file if it doesn't exist and adds a new context with
+  the first machine connection. If you don't specify a context name with `--context`, it uses `default`. If
+  `default` already exists, it auto-increments to `default-1`, `default-2`, and so on. You can rename contexts by
+  editing the config file.
+- [`uc machine add`](9-cli-reference/uc_machine_add.md) appends a new machine connection to the current context. You can
+  manually edit the connections in the config if needed.
+- [`uc ctx`](9-cli-reference/uc_ctx.md) or [`uc ctx use`](9-cli-reference/uc_ctx_use.md) updates `current_context` when
+  you switch contexts.
+- [`uc ctx conn`](9-cli-reference/uc_ctx_connection.md) moves the selected connection to the top of the list to make it
+  the default for that context.
+
+For example, after initialising a cluster:
+
+```shell
+uc machine init root@203.0.113.1 --context prod
+```
+
+It creates a config file that looks like this:
+
+```yaml title="~/.config/uncloud/config.yaml"
+current_context: prod
+contexts:
+  prod:
+    connections:
+      - ssh: root@203.0.113.1
+        machine_id: 4e81d368edf48480e5a2efb0915d6e38
+```

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

@@ -134,7 +134,7 @@ services:
       - 8080:80/tcp@host
 ```
 
-See [Publishing services](../3-concepts/1-ingress/2-publishing-services.md) for more details.
+See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details.
 
 ### `x-caddy`
 
@@ -150,7 +150,7 @@ services:
       }
 ```
 
-See [Publishing services](../3-concepts/1-ingress/2-publishing-services.md) for more details.
+See [Publishing services](../3-concepts/2-ingress/2-publishing-services.md) for more details.
 
 ### `x-machines`