diff --git a/docs/docs/1-overview.md b/docs/docs/1-overview.md index d18c0b7a..6dd93201 100644 --- a/docs/docs/1-overview.md +++ b/docs/docs/1-overview.md @@ -102,7 +102,7 @@ containers by their service names, `curl` service endpoints, or analyse traffic Install Uncloud CLI and deploy your first app in minutes: * [Install Uncloud CLI](./2-getting-started/1-install-cli.md) -* [Quick start guide](./2-getting-started/2-quick-start.md) +* [Deploy demo app](./2-getting-started/2-deploy-demo-app.md) ## Getting help diff --git a/docs/docs/2-getting-started/1-install-cli.md b/docs/docs/2-getting-started/1-install-cli.md index 1122c7e1..1a8c4a18 100644 --- a/docs/docs/2-getting-started/1-install-cli.md +++ b/docs/docs/2-getting-started/1-install-cli.md @@ -14,13 +14,13 @@ Windows is not natively supported yet, but you can install and run `uc` in a If you have [Homebrew](https://brew.sh/) package manager installed, this is the recommended installation method on macOS and Linux: -```bash +```shell brew install psviderski/tap/uncloud ``` To upgrade to the latest version: -```bash +```shell brew upgrade uncloud ``` @@ -28,7 +28,7 @@ brew upgrade uncloud For a quick automated installation, use the install script: -```bash +```shell curl -fsS https://get.uncloud.run/install.sh | sh ``` @@ -42,7 +42,7 @@ The script will: Don't like `curl | sh`? You can download and review the [install script](https://get.uncloud.run/install.sh) first and then run it: -```bash +```shell curl -fsSO https://get.uncloud.run/install.sh cat install.sh sh install.sh @@ -55,25 +55,25 @@ You can manually download and use a pre-built binary from the - ```bash + ```shell curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_macos_arm64.tar.gz | tar xz mv uncloud uc ``` - ```bash + ```shell curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_macos_amd64.tar.gz | tar xz mv uncloud uc ``` - ```bash + ```shell curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_linux_amd64.tar.gz | tar xz mv uncloud uc ``` - ```bash + ```shell curl -L https://github.com/psviderski/uncloud/releases/latest/download/uncloud_linux_arm64.tar.gz | tar xz mv uncloud uc ``` @@ -85,7 +85,7 @@ to run it as `uc` from any location. For example, move it to `/usr/local/bin` which is a common location for user-installed binaries: -```bash +```shell sudo mv ./uc /usr/local/bin ``` @@ -93,7 +93,7 @@ sudo mv ./uc /usr/local/bin After installation, verify that `uc` command is working: -```bash +```shell uc --version ``` @@ -101,4 +101,4 @@ uc --version Now that you have `uc` installed, you're ready to: -- [Quick start](./quick-start) — Deploy your first application +- [Deploy demo app](./2-deploy-demo-app.md) diff --git a/docs/docs/2-getting-started/2-deploy-demo-app.md b/docs/docs/2-getting-started/2-deploy-demo-app.md new file mode 100644 index 00000000..2e4f4b8a --- /dev/null +++ b/docs/docs/2-getting-started/2-deploy-demo-app.md @@ -0,0 +1,243 @@ +# Deploy demo app + +In this guide, we'll deploy [Excalidraw](https://excalidraw.com) — a popular sketching and diagramming tool — to your +Linux server. You'll learn the **basics of Uncloud** and see how simple it is to **run web apps** on your own +infrastructure with secure internet access. + +## Prerequisites + +Before you begin, you'll need: + +- **Uncloud CLI** [installed](1-install-cli.md) on your local machine +- A **Ubuntu or Debian server** with **public IP address** and **SSH access** (as `root` or a user with `sudo` + privileges) using a **private key**. + +:::tip Need a server? + +A small Virtual Private Server (VPS) or dedicated server from providers like [Hetzner](https://www.hetzner.com) or +[DigitalOcean](https://www.digitalocean.com) is a great choice for learning Uncloud and running lightweight services. We +recommend using a freshly installed server as existing services on ports 80 and 443 can cause conflicts. + +**Minimum requirements:** 1 vCPU, 512 MB RAM, Ubuntu 22.04 or Debian 11, AMD64 (recommended) or ARM64 architecture. +Other Linux distributions may work, but haven't been tested yet. + +::: + +## Set up your server + +First, let's turn your server into an Uncloud **machine**. This simply means setting it up so you can deploy and manage +services on it using `uc`. + +```shell +uc machine init root@ +``` + +If the SSH key to access your server isn't added to your [SSH agent](https://www.ssh.com/academy/ssh/agent), specify it +with the `-i` flag: + +```shell +uc machine init root@ -i ~/.ssh/id_xxx +``` + +This command will: + +- Install the latest stable Docker version on your server if it's not already installed +- Install the Uncloud daemon on your server +- Create a Docker network for Uncloud-managed containers +- Deploy [Caddy](https://caddyserver.com/) as your reverse proxy listening on host ports 80 and 443 +- Reserve a free `xxxxxx.cluster.uncloud.run` subdomain via the Uncloud managed DNS service and point it to your + server's IP + +All in about a minute! + +
+💡 Expand to see example output + +``` +$ uc machine init root@157.180.72.195 +Downloading Uncloud install script: https://raw.githubusercontent.com/psviderski/uncloud/refs/heads/main/scripts/install.sh +⏳ Running Uncloud install script... +⏳ Installing Docker... +# Executing docker install script, commit: 53a22f61c0628e58e1d6680b49e82993d304b449 ++ 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 + +Running kernel seems to be up-to-date. + +No services need to be restarted. + +No containers need to be restarted. + +No user sessions are running outdated binaries. + +No VM guests are running outdated hypervisor (qemu) binaries on this host. ++ sh -c docker version +Client: Docker Engine - Community + Version: 28.2.1 + API version: 1.50 + Go version: go1.24.3 + Git commit: 879ac3f + Built: Wed May 28 19:25:01 2025 + OS/Arch: linux/amd64 + Context: default + +Server: Docker Engine - Community + Engine: + Version: 28.2.1 + API version: 1.50 (minimum version 1.24) + Go version: go1.24.3 + Git commit: 0e2cc22 + Built: Wed May 28 19:25:01 2025 + OS/Arch: linux/amd64 + Experimental: false + containerd: + Version: 1.7.27 + GitCommit: 05044ec0a9a75232cad458027ca83437aae3f4da + runc: + Version: 1.2.5 + GitCommit: v1.2.5-0-g59923ef + docker-init: + Version: 0.19.0 + GitCommit: de40ad0 + +================================================================================ + +To run Docker as a non-privileged user, consider setting up the +Docker daemon in rootless mode for your user: + + dockerd-rootless-setuptool.sh install + +Visit https://docs.docker.com/go/rootless/ to learn about rootless mode. + + +To run the Docker daemon as a fully privileged service, but granting non-root +users access, refer to https://docs.docker.com/go/daemon-access/ + +WARNING: Access to the remote API on a privileged Docker daemon is equivalent + to root access on the host. Refer to the 'Docker daemon attack surface' + documentation for details: https://docs.docker.com/go/attack-surface/ + +================================================================================ + +✓ 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 +⏳ Starting Uncloud machine daemon (uncloud.service)... +✓ Uncloud machine daemon started. +✓ Uncloud installed on the machine successfully! 🎉 +Cluster initialised with machine 'machine-dc3c' and saved as context 'default' in your local config (/Users/spy/.config/uncloud/config.yaml) +Current cluster context is now 'default'. +Waiting for the machine to be ready... + +Reserved cluster domain: 7za6s7.cluster.uncloud.run +[+] 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 +``` + +
+ +## Deploy Excalidraw + +Now that your machine is set up, let's deploy `excalidraw` service from the +[official Docker image](https://hub.docker.com/r/excalidraw/excalidraw). The service will publish the container port 80 +as HTTPS endpoint on the previously reserved domain via Caddy. + +```shell +uc run --name excalidraw --publish 80/https excalidraw/excalidraw +``` + +You'll the progress of the deployment and the public URL where you can access the service: + +``` +[+] Running service excalidraw (replicated mode) 2/2 + ✔ Container excalidraw-azpc on machine-dc3c Started 8.9s + ✔ Image excalidraw/excalidraw on machine-dc3c Pulled 4.7s + +excalidraw endpoints: + • https://excalidraw.7za6s7.cluster.uncloud.run → :80 +``` + +## Verify your deployment + +After the service is deployed, use the `uc inspect` command to check its status and details: + +```shell +uc inspect excalidraw +``` + +``` +ID: 4d2de1600b6ada221a03896cd388836c +Name: excalidraw +Mode: replicated + +CONTAINER ID IMAGE CREATED STATUS MACHINE +fde7ac7f11ad excalidraw/excalidraw About a minute ago Up About a minute (healthy) machine-dc3c +``` + +In this example, the service has one container running on the machine `machine-dc3c` (our server). The container is up +and healthy. + +You can also list all deployed services and their public endpoints using the `uc ls` command: + +```shell +uc ls +``` + +``` +NAME MODE REPLICAS ENDPOINTS +caddy global 1 +excalidraw replicated 1 https://excalidraw.7za6s7.cluster.uncloud.run → :80 +``` + +You can see `caddy` service listed here. That's your reverse proxy, running as a regular Uncloud service. + +## It's live! Start drawing! + +Open your browser and navigate to the URL shown in the endpoints. + +![Excalidraw running on Uncloud](./img/excalidraw-browser.png) + +You now have: + +- Your **own Excalidraw instance** running on your server +- A **public URL** with **automatic HTTPS** you can share with your team and friends +- **Full control over your data** — no analytics or tracking + +## Convert to Docker Compose + +TBD + +## Use your own domain + +TBD + +## Clean up + +TBD + +## Next steps + +TBD diff --git a/docs/docs/2-getting-started/2-quick-start.md b/docs/docs/2-getting-started/2-quick-start.md deleted file mode 100644 index f067e668..00000000 --- a/docs/docs/2-getting-started/2-quick-start.md +++ /dev/null @@ -1,17 +0,0 @@ -# Quick start - -Please follow the [Quick start](https://github.com/psviderski/uncloud?tab=readme-ov-file#-quick-start) and -[User guide](https://github.com/psviderski/uncloud/blob/main/docs/user_guide.md) in the README. - ---- - -👋 Hey there! This page is still being written. I'm working hard to get all the documentation ready, but there's a lot to -cover and I want to make sure it's actually helpful rather than rushing it out with LLM slop. - -In the meantime, if you need help or have any questions, please jump into our -[Discord server](https://discord.gg/eR35KQJhPu). We're a friendly bunch and always happy to help troubleshoot issues or -answer questions! - -Thanks for your patience as I get the docs into shape. - -– Pasha diff --git a/docs/docs/2-getting-started/img/excalidraw-browser.png b/docs/docs/2-getting-started/img/excalidraw-browser.png new file mode 100644 index 00000000..29dac5ce Binary files /dev/null and b/docs/docs/2-getting-started/img/excalidraw-browser.png differ diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 0952a1bb..b50f9790 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -144,8 +144,8 @@ const config = { ] }, prism: { - theme: prismThemes.github, - darkTheme: prismThemes.dracula, + theme: prismThemes.palenight, + //darkTheme: prismThemes.dracula, }, }), };