From 2571498ed2e300fb384f9a40949b19cf62057c83 Mon Sep 17 00:00:00 2001
From: Connor Edwards <38229097+cedws@users.noreply.github.com>
Date: Sun, 16 Mar 2025 14:51:42 +0900
Subject: [PATCH] docs: add basic user guide

---
 README.md          |  4 +++-
 docs/user_guide.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 docs/user_guide.md

diff --git a/README.md b/README.md
index e195b113..8e0c023e 100644
--- a/README.md
+++ b/README.md
@@ -114,6 +114,8 @@ platform, whether you're running on a $5 VPS, a spare Mac mini, or a rack of bar
    uncloud-uninstall
    ```
 
+View the [user guide](docs/user_guide.md) for more information.
+
 ## ⚙️ How it works
 
 Check out the [design document](docs/design.md) to understand Uncloud's design philosophy and goals. Here, let's peek
@@ -204,7 +206,7 @@ Updating cluster domain records in Uncloud DNS to point to machines running cadd
 
 DNS records updated to use only the internet-reachable machines running caddy service:
   *.xuw3xd.cluster.uncloud.run  A → 152.67.101.197, 5.223.45.199
-  
+
 $ uc machine ls
 NAME             STATE   ADDRESS         PUBLIC IP        WIREGUARD ENDPOINTS
 oracle-vm        Up      10.210.0.1/24   152.67.101.197   10.0.0.95:51820, 152.67.101.197:51820
diff --git a/docs/user_guide.md b/docs/user_guide.md
new file mode 100644
index 00000000..05d11910
--- /dev/null
+++ b/docs/user_guide.md
@@ -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
+```