doc(deploy): Split Deploy section, impr mentions

- Deploy section split: - BEFORE: [ Testnet ] - AFTER: [ Overview, Hosted, Self-Hosted ] - In root doc overview, added a name to the publish command (to prevent confusion later) - Added instructions how to add back `local` and `testnet` servers via CLI after repeatedly experiencing a bug that wipes the servers.
clockworklabs · Feb 26, 2024 · 6465f3f · 6465f3f
1 parent f6d1353
commit 6465f3f
Show file tree

Hide file tree

Showing 7 changed files with 220 additions and 59 deletions.
diff --git a/docs/deploying/hosted.md b/docs/deploying/hosted.md
@@ -0,0 +1,74 @@
+# Deploying - Hosted
+
+This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI. Via CLI, we will then:
+
+1. Ensure our hosted server named `testnet` exists as the default.
+1. Create an `Identity`.
+1. `Publish` your app.
+
+💡 This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI and that you already have `testnet` server added (exists by default). If you accidentally removed `testnet`, add it back via CLI:
+
+```bash
+spacetime server add "https://testnet.spacetimedb.com" testnet
+```
+
+## SpacetimeDB Cloud (Hosted) Deployment
+
+Currently, for hosted deployment, only the `testnet` server is available for SpacetimeDB cloud, which is subject to wipes.
+
+📢 Stay tuned (such as [via Discord](https://discord.com/invite/SpacetimeDB)) for `mainnet` coming soon!
+
+## Set the Server Default
+
+To make CLI commands easier so that we don't need to keep specifying `testnet` as the target server, let's set it as default: 
+
+```bash
+spacetime server set-default testnet
+```
+
+## Creating an Identity
+
+By default, there are no identities created. Let's create a new one via CLI:
+```bash
+spacetime identity new --name {Nickname} --email {Email}
+```
+
+💡If you already created an identity but forgot to attach an email, add it via CLI:
+```bash
+spacetime identity set-email {Email}
+```
+
+## Create and Publish a Module
+
+Let's create a vanilla Rust module called `HelloSpacetimeBD` from our home dir, then publish it "as-is". For Windows users, use `PowerShell`:
+
+```bash
+cd ~
+spacetime init --lang rust HelloSpacetimeDB
+cd HelloSpacetimeDB
+spacetime publish HelloSpacetimeDB
+```
+
+## Hosted Web Dashboard
+
+By earlier associating an email with your CLI identity, you can now view your published modules on the web dashboard. For multiple identities, first list them and copy the hash you want to use:
+
+```bash
+spacetime identity list
+```
+
+1. Open the SpacetimeDB [login page](https://spacetimedb.com/login) using the same email above.
+1. Choose your identity from the dropdown menu.
+   - \[For multiple identities\] `CTRL+F` to highlight the correct identity you copied earlier.
+1. Check your email for a validation link.
+
+You should now be able to see your published modules on the web dashboard!
+
+---
+
+## Summary
+
+- We ensured the hosted `testnet` server existed, then set it as the default.
+- We added an `identity` to bind with our hosted `testnet` server, ensuring it contained both a Nickname and Email.
+- We then logged in the web dashboard via an email `one-time password (OTP)` and were then able to view our published apps.
+- With SpacetimeDB Cloud, you benefit from automatic scaling, robust security, and the convenience of not having to manage the hosting environment.
diff --git a/docs/deploying/index.md b/docs/deploying/index.md
@@ -0,0 +1,48 @@
+# Deploying Overview
+
+SpacetimeDB supports both hosted and self-hosted publishing in multiple ways. Below, we will:
+
+1. Generally introduce Identities.
+1. Generally introduce Servers.
+1Choose to proceed with either a [Hosted](/docs/deploying/hosted.md) or [Self-Hosted](/docs/deploying/self-hosted.md) deployment.
+
+💡 This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI.
+
+## About Identities
+
+An `Identity` is a hash attached to a `Nickname` and `Email`, allowing you to manage your app (such as `Publishing` your app).
+
+Each `Identity` is bound to one, single `Server`: Unlike GitHub, for example, you would require one identity per server.
+
+By default, there are no identities created. While the next tutorial will go more in-depth, you may create a new one via CLI:
+```bash
+spacetime identity new --name {Nickname} --email {Email}
+```
+
+See the [API reference](/docs/http/identity.md) or CLI help (below) for further managing `Identities`:
+```bash
+spacetime identity --help
+```
+
+## About Servers
+
+You `publish` your app to a target `Server` database: While we recommend to **host** your SpacetimeDB app with us for simplicity and scalability, you may also **self-host** (such as locally).
+
+By default, there are already two default servers added ([testnet](/docs/deploying/hosted.md) and [local](/docs/deploying/self-hosted.md)). While the next tutorial will go more in-depth, you may list your servers via CLI:
+```bash
+spacetime server list
+```
+
+See the [API reference](/docs/http/database.md) or CLI help (below) for further managing `Servers`:
+```bash
+spacetime server --help
+```
+
+---
+
+## Deploying via CLI
+
+Choose a server for your hosting tutorial path to set a server as default, create an identity, and deploy (`publish`) your app:
+
+1. [testnet](/docs/deploying/hosted.md) (hosted)
+2. [local](/docs/deploying/self-hosted.md) (self-hosted)
diff --git a/docs/deploying/self-hosted.md b/docs/deploying/self-hosted.md
@@ -0,0 +1,60 @@
+# Deploying - Self-Hosted
+
+This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI. Via CLI, we will then:
+
+1. Ensure our localhost server named `local` exists as the default.
+1. Start our localhost server in a separate terminal window.
+1. Create an `Identity` with at least a Nickname.
+1. `Publish` your app.
+
+💡 This tutorial assumes that you have already [installed](/install) the SpacetimeDB CLI and that you already have `local` server added (exists by default). If you accidentally removed `local`, add it back via CLI with the `--no-fingerprint` flag (since our server is not yet running):
+
+```bash
+spacetime server add "http://127.0.0.1:3000" local --no-fingerprint
+```
+
+## Set the Server Default
+
+To make CLI commands easier so that we don't need to keep specifying `local` as the target server, let's set it as default:
+
+```bash
+spacetime server set-default local
+```
+
+## Start the Local Server
+
+In a **separate** terminal window, start the local listen server in the foreground:
+```bash
+spacetime start
+```
+
+## Creating an Identity
+
+By default, there are no identities created. Let's create a new one via CLI:
+```bash
+spacetime identity new --name {Nickname}
+```
+
+💡We could optionally add `--email {Email}` to the above command, but is currently unnecessary for local deployment since there's no web dashboard. If you already created an identity but forgot to attach a Nickname, add it via CLI to easier identify your modules:
+```bash
+spacetime identity set-name {Nickname}
+```
+
+## Create and Publish a Module
+
+Let's create a vanilla Rust module called `HelloSpacetimeBD` from our home dir, then publish it "as-is". For Windows users, use `PowerShell`:
+
+```bash
+cd ~
+spacetime init --lang rust HelloSpacetimeDB
+cd HelloSpacetimeDB
+spacetime publish HelloSpacetimeDB
+```
+
+---
+
+## Summary
+
+- We ensured the self-hosted `local` server existed, then set it as the default. 
+- We then opened a separate terminal to run the self-hosted `local` server in the foreground.
+- We added an `identity` to bind with our self-hosted `local` server set to default, ensuring it contained a Nickname.
diff --git a/docs/deploying/testnet.md b/docs/deploying/testnet.md
diff --git a/docs/index.md b/docs/index.md
@@ -100,23 +100,21 @@ SpacetimeDB was designed first and foremost as the backend for multiplayer Unity
 1. How do I get/install SpacetimeDB?
    Just install our command line tool and then upload your application to the cloud.
 
-1. How do I create a new database with SpacetimeDB?
+4. How do I create a new database with SpacetimeDB?
    Follow our [Quick Start](/docs/getting-started) guide!
 
-TL;DR in an empty directory:
+TL;DR in an empty directory, init and publish a barebones app named HelloWorld.
 
 ```bash
 spacetime init --lang=rust
-spacetime publish
+spacetime publish HelloWorld
 ```
 
 5. How do I create a Unity game with SpacetimeDB?
    Follow our [Unity Project](/docs/unity-project) guide!
 
-TL;DR in an empty directory:
+TL;DR after already initializing and publishing (see FAQ #5), generate the SDK:
 
 ```bash
-spacetime init --lang=rust
-spacetime publish
 spacetime generate --out-dir <path-to-unity-project> --lang=csharp
 ```
diff --git a/docs/nav.js b/docs/nav.js
@@ -9,14 +9,21 @@ function section(title) {
 const nav = {
     items: [
         section("Intro"),
-        page("Overview", "index", "index.md"),
+        page("Overview", "index", "index.md"), // TODO(BREAKING): For consistency & clarity, 'index' slug should be renamed 'intro'?
         page("Getting Started", "getting-started", "getting-started.md"),
         section("Deploying"),
-        page("Testnet", "deploying/testnet", "deploying/testnet.md"),
-        section("Unity Tutorial"),
-        page("Part 1 - Basic Multiplayer", "unity/part-1", "unity/part-1.md"),
-        page("Part 2 - Resources And Scheduling", "unity/part-2", "unity/part-2.md"),
-        page("Part 3 - BitCraft Mini", "unity/part-3", "unity/part-3.md"),
+        page("Overview", "deploying", "deploying/index.md"),
+        page("Hosted", "deploying/hosted", "deploying/hosted.md"),
+        page("Self-Hosted", "deploying/hosted", "deploying/self-hosted.md"),
+        section("Unity Tutorial - Basic Multiplayer"),
+        page("Overview", "unity-tutorial", "unity/index.md"),
+        page("1 - Setup", "unity/part-1", "unity/part-1.md"),
+        page("2a - Server (Rust)", "unity/part-2a-rust", "unity/part-2a-rust.md"),
+        page("2b - Server (C#)", "unity/part-2b-c-sharp", "unity/part-2a-c-sharp.md"),
+        page("3 - Client", "unity/part-3", "unity/part-3.md"),
+        section("Unity Tutorial - Advanced"),
+        page("4 - Resources And Scheduling", "unity/part-4", "unity/part-4.md"),
+        page("5 - BitCraft Mini", "unity/part-5", "unity/part-5.md"),
         section("Server Module Languages"),
         page("Overview", "modules", "modules/index.md"),
         page("Rust Quickstart", "modules/rust/quickstart", "modules/rust/quickstart.md"),

diff --git a/nav.ts b/nav.ts
@@ -25,16 +25,24 @@ function section(title: string): NavSection {
 const nav: Nav = {
   items: [
     section("Intro"),
-    page("Overview",        "index",            "index.md"),
-    page("Getting Started", "getting-started",  "getting-started.md"),
+    page("Overview",            "index",                  "index.md"), // TODO(BREAKING): For consistency & clarity, 'index' slug should be renamed 'intro'?
+    page("Getting Started",     "getting-started",        "getting-started.md"),
 
     section("Deploying"),
-    page("Testnet", "deploying/testnet", "deploying/testnet.md"),
+    page("Overview",            "deploying",              "deploying/index.md"),
+    page("Hosted",              "deploying/hosted",       "deploying/hosted.md"),
+    page("Self-Hosted",         "deploying/hosted",       "deploying/self-hosted.md"),
 
-    section("Unity Tutorial"),
-    page("Part 1 - Basic Multiplayer",        "unity/part-1", "unity/part-1.md"),
-    page("Part 2 - Resources And Scheduling", "unity/part-2", "unity/part-2.md"),
-    page("Part 3 - BitCraft Mini",            "unity/part-3", "unity/part-3.md"),
+    section("Unity Tutorial - Basic Multiplayer"),
+    page("Overview",            "unity-tutorial",         "unity/index.md"),
+    page("1 - Setup",           "unity/part-1",           "unity/part-1.md"),
+    page("2a - Server (Rust)",  "unity/part-2a-rust",     "unity/part-2a-rust.md"),
+    page("2b - Server (C#)",    "unity/part-2b-c-sharp",  "unity/part-2a-c-sharp.md"),
+    page("3 - Client",          "unity/part-3",           "unity/part-3.md"),
+
+    section("Unity Tutorial - Advanced"),
+    page("4 - Resources And Scheduling", "unity/part-4",  "unity/part-4.md"),
+    page("5 - BitCraft Mini",            "unity/part-5",  "unity/part-5.md"),
 
     section("Server Module Languages"),
     page("Overview",        "modules",                    "modules/index.md"),
@@ -44,7 +52,7 @@ const nav: Nav = {
     page("C# Reference",    "modules/c-sharp",            "modules/c-sharp/index.md"),
 
     section("Client SDK Languages"),
-    page("Overview",              "sdks", "sdks/index.md"),
+    page("Overview",              "sdks",                         "sdks/index.md"),
     page("Typescript Quickstart", "sdks/typescript/quickstart",   "sdks/typescript/quickstart.md"),
     page("Typescript Reference",  "sdks/typescript",              "sdks/typescript/index.md"),
     page("Rust Quickstart",       "sdks/rust/quickstart",         "sdks/rust/quickstart.md"),
@@ -55,7 +63,7 @@ const nav: Nav = {
     page("C# Reference",          "sdks/c-sharp",                 "sdks/c-sharp/index.md"),
 
     section("WebAssembly ABI"),
-    page("Module ABI Reference", "webassembly-abi", "webassembly-abi/index.md"),
+    page("Module ABI Reference",  "webassembly-abi",              "webassembly-abi/index.md"),
 
     section("HTTP API"),
     page("HTTP",        "http",           "http/index.md"),
@@ -64,14 +72,14 @@ const nav: Nav = {
     page("`/energy`",   "http/energy",    "http/energy.md"),
 
     section("WebSocket API Reference"),
-    page("WebSocket", "ws", "ws/index.md"),
+    page("WebSocket",   "ws",             "ws/index.md"),
 
     section("Data Format"),
-    page("SATN",  "satn",   "satn.md"),
-    page("BSATN", "bsatn",  "bsatn.md"),
+    page("SATN",        "satn",           "satn.md"),
+    page("BSATN",       "bsatn",          "bsatn.md"),
 
     section("SQL"),
-    page("SQL Reference", "sql", "sql/index.md"),
+    page("SQL Reference", "sql",    "sql/index.md"),
   ],
 };