docs: add basic user guide

2026-08-26 11:03:34 +00:00 · 2025-03-16 14:51:42 +09:00
parent 5bcbfc332d
commit 2571498ed2
2 changed files with 60 additions and 1 deletions
@@ -0,0 +1,57 @@
+# User Guide
+
+## Initialising a cluster
+
+To begin setting up a new Uncloud cluster, create the desired nodes. Ensure that their firewall allows the required ports.
+
+### Ports
+
+Nodes running Uncloud with a standard configuration must have the following inbound ports allowed in the firewall:
+
+* 51820/udp (WireGuard meshnet)
+* 22/tcp (default SSH management port)
+* 80/tcp (required for challenge if uncloud.run DNS is enabled, pass --no-dns during init to disable)
+
+In addition, any ports for any workloads you want to expose will need to be open.
+
+### Configuration
+
+Uncloud stores its configuration in `~/.config/uncloud/config.toml`. If you wish to reinitialise a cluster, simply remove it from this config.
+
+### Initialisation
+
+Begin by initialising the first node in your cluster with `uncloud machine init [USER@HOST:PORT]`. If you do not have a need for Caddy reverse proxy, you may disable this feature with `--no-caddy`.
+
+This command will idempotently install Docker, uncloudd, uncloud-corrosion. If Caddy is enabled, it will set up a reverse proxy. If Uncloud DNS is enabled, it will create a DNS A record for the machine's public IP address under `*.[CLUSTER ID].cluster.uncloud.run`.
+
+If you wish to uninstall Uncloud and its components, run `uncloud-uninstall`.
+
+### Adding a node
+
+Just like the initialisation of the first node, a node can be added to the cluster with `uncloud machine add`.
+
+### DNS
+
+Uncloud (uncloud.run) DNS can be managed with the `uncloud dns` subcommand.
+
+* To reserve a domain name, run `uncloud dns reserve`
+* To release a domain name, run `uncloud dns release`.
+* To see the domain name, run `uncloud dns show`
+
+### Running a service
+
+Services on an Uncloud cluster can be managed with `uncloud service`.
+
+You can run a service with two replicas that expose port 80 like the following:
+
+```
+uncloud service run --mode replicated -p 80/http --replicas 2 nginxdemos/hello
+```
+
+Since this doesn't specify a service name, a random one will be generated.
+
+The service can be deleted by its service name:
+
+```
+uncloud service rm hello-gsdo
+```