From 6465f3f1b94230d1beaded0cf2f96a23cd8f9fb0 Mon Sep 17 00:00:00 2001 From: Dylan Hunt Date: Mon, 26 Feb 2024 17:05:29 +0800 Subject: [PATCH] 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. --- docs/deploying/hosted.md | 74 +++++++++++++++++++++++++++++++++++ docs/deploying/index.md | 48 +++++++++++++++++++++++ docs/deploying/self-hosted.md | 60 ++++++++++++++++++++++++++++ docs/deploying/testnet.md | 34 ---------------- docs/index.md | 10 ++--- docs/nav.js | 19 ++++++--- nav.ts | 34 ++++++++++------ 7 files changed, 220 insertions(+), 59 deletions(-) create mode 100644 docs/deploying/hosted.md create mode 100644 docs/deploying/index.md create mode 100644 docs/deploying/self-hosted.md delete mode 100644 docs/deploying/testnet.md diff --git a/docs/deploying/hosted.md b/docs/deploying/hosted.md new file mode 100644 index 0000000..0898a26 --- /dev/null +++ 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 new file mode 100644 index 0000000..5e0fcba --- /dev/null +++ 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 new file mode 100644 index 0000000..2886b5b --- /dev/null +++ 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 deleted file mode 100644 index ce64804..0000000 --- a/docs/deploying/testnet.md +++ /dev/null @@ -1,34 +0,0 @@ -# SpacetimeDB Cloud Deployment - -The SpacetimeDB Cloud is a managed cloud service that provides developers an easy way to deploy their SpacetimeDB apps to the cloud. - -Currently only the `testnet` is available for SpacetimeDB cloud which is subject to wipes. The `mainnet` will be available soon. - -## Deploy via CLI - -1. [Install](/install) the SpacetimeDB CLI. -1. Configure your CLI to use the SpacetimeDB Cloud. To do this, run the `spacetime server` command: - -```bash -spacetime server add --default "https://testnet.spacetimedb.com" testnet -``` - -## Connecting your Identity to the Web Dashboard - -By associating an email with your CLI identity, you can view your published modules on the web dashboard. - -1. Get your identity using the `spacetime identity list` command. Copy it to your clipboard. -1. Connect your email address to your identity using the `spacetime identity set-email` command: - -```bash -spacetime identity set-email -``` - -1. Open the SpacetimeDB website and log in using your email address. -1. Choose your identity from the dropdown menu. -1. Validate your email address by clicking the link in the email you receive. -1. You should now be able to see your published modules on the web dashboard. - ---- - -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/index.md b/docs/index.md index 7a95f4f..904abeb 100644 --- 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 --lang=csharp ``` diff --git a/docs/nav.js b/docs/nav.js index cb8d22f..f013f78 100644 --- 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 index 6d5a304..b7af65a 100644 --- 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"), ], };