+ + + This document was generated automatically by +
clap-markdown.
+
+
diff --git a/docs/docs/cli-reference/standalone-config.md b/docs/docs/cli-reference/standalone-config.md
new file mode 100644
index 00000000000..0dd0a1502c8
--- /dev/null
+++ b/docs/docs/cli-reference/standalone-config.md
@@ -0,0 +1,82 @@
+# `spacetimedb-standalone` configuration
+
+A local database instance (as started by `spacetime start`) can be configured in `{data-dir}/config.toml`, where `{data-dir}` is the database's data directory. This directory is printed when you run `spacetime start`:
+
+
+spacetimedb-standalone version: 1.0.0
+spacetimedb-standalone path: /home/user/.local/share/spacetime/bin/1.0.0/spacetimedb-standalone
+database running in data directory /home/user/.local/share/spacetime/data
+
+On Linux and macOS, this directory is by default `~/.local/share/spacetime/data`. On Windows, it's `%LOCALAPPDATA%\SpacetimeDB\data`.
+
+## `config.toml`
+
+- [`certificate-authority`](#certificate-authority)
+- [`logs`](#logs)
+
+### `certificate-authority`
+
+```toml
+[certificate-authority]
+jwt-priv-key-path = "/path/to/id_ecdsas"
+jwt-pub-key-path = "/path/to/id_ecdsas.pub"
+```
+
+The `certificate-authority` table lets you configure the public and private keys used by the database to sign tokens.
+
+### `logs`
+
+```toml
+[logs]
+level = "error"
+directives = [
+ "spacetimedb=warn",
+ "spacetimedb_standalone=info",
+]
+```
+
+#### `logs.level`
+
+Can be one of `"error"`, `"warn"`, `"info"`, `"debug"`, `"trace"`, or `"off"`, case-insensitive. Only log messages of the specified level or higher will be output; e.g. if set to `warn`, only `error` and `warn`-level messages will be logged.
+
+#### `logs.directives`
+
+A list of filtering directives controlling what messages get logged, which overwrite the global [`logs.level`](#logslevel). See [`tracing documentation`](https://docs.rs/tracing-subscriber/0.3/tracing_subscriber/filter/struct.EnvFilter.html#directives) for syntax. Note that this is primarily intended as a debugging tool, and log message fields and targets are not considered stable.
+
+### `websocket`
+
+```toml
+[websocket]
+ping-interval = "15s"
+idle-timeout = "30s"
+close-handshake-timeout = "250ms"
+incoming-queue-length = 2048
+```
+
+#### `websocket.ping-interval`
+
+Interval at which the server will send `Ping` frames to keep the connection alive.
+Should be smaller than `websocket.idle-timeout` to be effective.
+
+Values are strings of any format the [`humantime`] crate can parse.
+
+#### `websocket.idle-timeout`
+
+If the server hasn't received any data from the client (including `Pong` responses to previous `Ping`s it sent), it will consider the client unresponsive and close the connection.
+Should be greater than `websocket.ping-interval` to be effective.
+
+Values are strings of any format the [`humantime`] crate can parse.
+
+#### `websocket.close-handshake-timeout`
+
+Time the server waits for the client to respond to a graceful connection close. If the client doesn't respond within this timeout, the connection is dropped.
+
+Values are strings of any format the [`humantime`] crate can parse.
+
+#### `websocket.incoming-queue-length`
+
+Maximum number of client messages the server will queue up in case it is not able to process them quickly enough. When the queue length exceeds this value, the server will start disconnecting clients.
+Note that the limit is per client, not across all clients of a particular database.
+
+
+[`humantime`]: https://crates.io/crates/humantime
diff --git a/docs/docs/deploying/maincloud.md b/docs/docs/deploying/maincloud.md
new file mode 100644
index 00000000000..66130fdcbe2
--- /dev/null
+++ b/docs/docs/deploying/maincloud.md
@@ -0,0 +1,51 @@
+# Deploy to Maincloud
+
+Maincloud is a managed cloud service that provides developers an easy way to deploy their SpacetimeDB apps to the cloud.
+
+## Deploy via CLI
+
+1. Install the SpacetimeDB CLI for your platform: [Install SpacetimeDB](/install)
+1. Create your module (see [Getting Started](/docs/getting-started))
+1. Publish to Maincloud:
+
+```bash
+spacetime publish -s maincloud my-cool-module
+```
+
+## Connecting your Identity to the Web Dashboard
+
+By logging in your CLI via spacetimedb.com, you can view your published modules on the web dashboard.
+
+If you did not log in with spacetimedb.com when publishing your module, you can log in by running:
+```bash
+spacetime logout
+spacetime login
+```
+
+1. Open the SpacetimeDB website and log in using your GitHub login.
+1. You should now be able to see your published modules https://spacetimedb.com/profile, or you can navigate to your database directly at https://spacetimedb.com/my-cool-module.
+
+---
+
+With SpacetimeDB Maincloud, you benefit from automatic scaling, robust security, and the convenience of not having to manage the hosting environment.
+
+# Connect from Client SDKs
+To connect to your deployed module in your client code, use the host url of `https://maincloud.spacetimedb.com`:
+
+## Rust
+```rust
+DbConnection::builder()
+ .with_uri("https://maincloud.spacetimedb.com")
+```
+
+## C#
+```csharp
+DbConnection.Builder()
+ .WithUri("https://maincloud.spacetimedb.com")
+```
+
+## TypeScript
+```ts
+ DbConnection.builder()
+ .withUri('https://maincloud.spacetimedb.com')
+```
diff --git a/docs/docs/deploying/spacetimedb-standalone.md b/docs/docs/deploying/spacetimedb-standalone.md
new file mode 100644
index 00000000000..db738dd8d73
--- /dev/null
+++ b/docs/docs/deploying/spacetimedb-standalone.md
@@ -0,0 +1,280 @@
+# Self Hosting SpacetimeDB
+
+This tutorial will guide you through setting up SpacetimeDB on an Ubuntu 24.04 server, securing it with HTTPS using Nginx and Let's Encrypt, and configuring a systemd service to keep it running.
+
+## Prerequisites
+- A fresh Ubuntu 24.04 server (VM or cloud instance of your choice)
+- A domain name (e.g., `example.com`)
+- `sudo` privileges on the server
+
+## Step 1: Create a Dedicated User for SpacetimeDB
+For security purposes, create a dedicated `spacetimedb` user to run SpacetimeDB:
+
+```sh
+sudo mkdir /stdb
+sudo useradd --system spacetimedb
+sudo chown -R spacetimedb:spacetimedb /stdb
+```
+
+Install SpacetimeDB as the new user:
+
+```sh
+sudo -u spacetimedb bash -c 'curl -sSf https://install.spacetimedb.com | sh -s -- --root-dir /stdb --yes'
+```
+
+## Step 2: Create a Systemd Service for SpacetimeDB
+To ensure SpacetimeDB runs on startup, create a systemd service file:
+
+```sh
+sudo nano /etc/systemd/system/spacetimedb.service
+```
+
+Add the following content:
+
+```ini
+[Unit]
+Description=SpacetimeDB Server
+After=network.target
+
+[Service]
+ExecStart=/stdb/spacetime --root-dir=/stdb start --listen-addr='127.0.0.1:3000'
+Restart=always
+User=spacetimedb
+WorkingDirectory=/stdb
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start the service:
+
+```sh
+sudo systemctl enable spacetimedb
+sudo systemctl start spacetimedb
+```
+
+Check the status:
+
+```sh
+sudo systemctl status spacetimedb
+```
+
+## Step 3: Install and Configure Nginx
+
+### Install Nginx
+
+```sh
+sudo apt update
+sudo apt install nginx -y
+```
+
+### Configure Nginx Reverse Proxy
+Create a new Nginx configuration file:
+
+```sh
+sudo nano /etc/nginx/sites-available/spacetimedb
+```
+
+Add the following configuration, remember to change `example.com` to your own domain:
+
+```nginx
+server {
+ listen 80;
+ server_name example.com;
+
+ #########################################
+ # By default SpacetimeDB is completely open so that anyone can publish to it. If you want to block
+ # users from creating new databases you should keep this section commented out. Otherwise, if you
+ # want to open it up (probably for dev environments) then you can uncomment this section and then
+ # also comment out the location / section below.
+ #########################################
+ # location / {
+ # proxy_pass http://localhost:3000;
+ # proxy_http_version 1.1;
+ # proxy_set_header Upgrade $http_upgrade;
+ # proxy_set_header Connection "Upgrade";
+ # proxy_set_header Host $host;
+ # }
+
+ # Anyone can subscribe to any database.
+ # Note: This is the only section *required* for the websocket to function properly. Clients will
+ # be able to create identities, call reducers, and subscribe to tables through this websocket.
+ location ~ ^/v1/database/[^/]+/subscribe$ {
+ proxy_pass http://localhost:3000;
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection "Upgrade";
+ proxy_set_header Host $host;
+ }
+
+ # Uncomment this section to allow all HTTP reducer calls
+ # location ~ ^/v1/[^/]+/call/[^/]+$ {
+ # proxy_pass http://localhost:3000;
+ # proxy_http_version 1.1;
+ # proxy_set_header Upgrade $http_upgrade;
+ # proxy_set_header Connection "Upgrade";
+ # proxy_set_header Host $host;
+ # }
+
+ # Uncomment this section to allow all HTTP sql requests
+ # location ~ ^/v1/[^/]+/sql$ {
+ # proxy_pass http://localhost:3000;
+ # proxy_http_version 1.1;
+ # proxy_set_header Upgrade $http_upgrade;
+ # proxy_set_header Connection "Upgrade";
+ # proxy_set_header Host $host;
+ # }
+
+ # NOTE: This is required for the typescript sdk to function, it is optional
+ # for the rust and the C# SDKs.
+ location /v1/identity {
+ proxy_pass http://localhost:3000;
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection "Upgrade";
+ proxy_set_header Host $host;
+ }
+
+ # Block all other routes explicitly. Only localhost can use these routes. If you want to open your
+ # server up so that anyone can publish to it you should comment this section out.
+ location / {
+ allow 127.0.0.1;
+ deny all;
+ }
+}
+```
+
+This configuration by default blocks all connections other than `/v1/identity` and `/v1/database/
+
+
+## `GET /v1/database/:name_or_identity/logs`
+
+Retrieve logs from a database.
+
+Accessible through the CLI as `spacetime logs Example response from `/schema?version=9` for the default module generated by `spacetime init`
+ +```json +{ + "typespace": { + "types": [ + { + "Product": { + "elements": [ + { + "name": { + "some": "name" + }, + "algebraic_type": { + "String": [] + } + } + ] + } + } + ] + }, + "tables": [ + { + "name": "person", + "product_type_ref": 0, + "primary_key": [], + "indexes": [], + "constraints": [], + "sequences": [], + "schedule": { + "none": [] + }, + "table_type": { + "User": [] + }, + "table_access": { + "Private": [] + } + } + ], + "reducers": [ + { + "name": "add", + "params": { + "elements": [ + { + "name": { + "some": "name" + }, + "algebraic_type": { + "String": [] + } + } + ] + }, + "lifecycle": { + "none": [] + } + }, + { + "name": "identity_connected", + "params": { + "elements": [] + }, + "lifecycle": { + "some": { + "OnConnect": [] + } + } + }, + { + "name": "identity_disconnected", + "params": { + "elements": [] + }, + "lifecycle": { + "some": { + "OnDisconnect": [] + } + } + }, + { + "name": "init", + "params": { + "elements": [] + }, + "lifecycle": { + "some": { + "Init": [] + } + } + }, + { + "name": "say_hello", + "params": { + "elements": [] + }, + "lifecycle": { + "none": [] + } + } + ], + "types": [ + { + "name": { + "scope": [], + "name": "Person" + }, + "ty": 0, + "custom_ordering": true + } + ], + "misc_exports": [], + "row_level_security": [] +} +``` + +
+
+
+ );
+}
+
+export default App;
+```
+
+We have configured the `onSubmitNewName` and `onSubmitMessage` callbacks to be called when the user clicks the submit button in the profile and new message sections, respectively. For now, they do nothing when called, but later we'll add some logic to call SpacetimeDB reducers when these callbacks are called.
+
+Let's also make it pretty. Replace the contents of `client/src/App.css` with the following:
+
+```css
+.App {
+ display: grid;
+ /*
+ 3 rows:
+ 1) Profile
+ 2) Main content (left = message, right = system)
+ 3) New message
+ */
+ grid-template-rows: auto 1fr auto;
+ /* 2 columns: left for chat, right for system */
+ grid-template-columns: 2fr 1fr;
+
+ height: 100vh; /* fill viewport height */
+ width: clamp(300px, 100%, 1200px);
+ margin: 0 auto;
+}
+
+/* ----- Profile (Row 1, spans both columns) ----- */
+.profile {
+ grid-column: 1 / 3;
+ display: flex;
+ align-items: center;
+ gap: 1rem;
+ padding: 1rem;
+ border-bottom: 1px solid var(--theme-color);
+}
+
+.profile h1 {
+ margin-right: auto; /* pushes name/edit form to the right */
+}
+
+.profile form {
+ display: flex;
+ flex-grow: 1;
+ align-items: center;
+ gap: 0.5rem;
+ max-width: 300px;
+}
+
+.profile form input {
+ background-color: var(--textbox-color);
+}
+
+/* ----- Chat Messages (Row 2, Col 1) ----- */
+.message {
+ grid-row: 2 / 3;
+ grid-column: 1 / 2;
+
+ /* Ensure this section scrolls if content is long */
+ overflow-y: auto;
+ padding: 1rem;
+ display: flex;
+ flex-direction: column;
+ gap: 1rem;
+}
+
+.message h1 {
+ margin-right: 0.5rem;
+}
+
+/* ----- System Panel (Row 2, Col 2) ----- */
+.system {
+ grid-row: 2 / 3;
+ grid-column: 2 / 3;
+
+ /* Also scroll independently if needed */
+ overflow-y: auto;
+ padding: 1rem;
+ border-left: 1px solid var(--theme-color);
+ white-space: pre-wrap;
+ font-family: monospace;
+}
+
+/* ----- New Message (Row 3, spans columns 1-2) ----- */
+.new-message {
+ grid-column: 1 / 3;
+ display: flex;
+ justify-content: center;
+ align-items: center;
+ padding: 1rem;
+ border-top: 1px solid var(--theme-color);
+}
+
+.new-message form {
+ display: flex;
+ flex-direction: column;
+ gap: 0.75rem;
+ width: 100%;
+ max-width: 600px;
+}
+
+.new-message form h3 {
+ margin-bottom: 0.25rem;
+}
+
+/* Distinct background for the textarea */
+.new-message form textarea {
+ font-family: monospace;
+ font-weight: 400;
+ font-size: 1rem;
+ resize: vertical;
+ min-height: 80px;
+ background-color: var(--textbox-color);
+ color: inherit;
+
+ /* Subtle shadow for visibility */
+ box-shadow:
+ 0 1px 3px rgba(0, 0, 0, 0.12),
+ 0 1px 2px rgba(0, 0, 0, 0.24);
+}
+
+@media (prefers-color-scheme: dark) {
+ .new-message form textarea {
+ box-shadow: 0 0 0 1px #17492b;
+ }
+}
+```
+
+Next we need to replace the global styles in `client/src/index.css` as well:
+
+```css
+/* ----- CSS Reset & Global Settings ----- */
+*,
+*::before,
+*::after {
+ box-sizing: border-box;
+ margin: 0;
+ padding: 0;
+}
+
+/* ----- Color Variables ----- */
+:root {
+ --theme-color: #3dc373;
+ --theme-color-contrast: #08180e;
+ --textbox-color: #edfef4;
+ color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+ :root {
+ --theme-color: #4cf490;
+ --theme-color-contrast: #132219;
+ --textbox-color: #0f311d;
+ }
+}
+
+/* ----- Page Setup ----- */
+html,
+body,
+#root {
+ height: 100%;
+ margin: 0;
+}
+
+body {
+ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+ 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+ sans-serif;
+ -webkit-font-smoothing: antialiased;
+ -moz-osx-font-smoothing: grayscale;
+}
+
+code {
+ font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
+ monospace;
+}
+
+/* ----- Buttons ----- */
+button {
+ padding: 0.5rem 0.75rem;
+ border: none;
+ border-radius: 0.375rem;
+ background-color: var(--theme-color);
+ color: var(--theme-color-contrast);
+ cursor: pointer;
+ font-weight: 600;
+ letter-spacing: 0.1px;
+ font-family: monospace;
+}
+
+/* ----- Inputs & Textareas ----- */
+input,
+textarea {
+ border: none;
+ border-radius: 0.375rem;
+ caret-color: var(--theme-color);
+ font-family: monospace;
+ font-weight: 600;
+ letter-spacing: 0.1px;
+ padding: 0.5rem 0.75rem;
+}
+
+input:focus,
+textarea:focus {
+ outline: none;
+ box-shadow: 0 0 0 2px var(--theme-color);
+}
+```
+
+Now when you run `pnpm run dev` and open `http://localhost:5173`, you should see a basic chat app that does not yet send or receive messages.
+
+## Generate your module types
+
+The `spacetime` CLI's `generate` command will generate client-side interfaces for the tables, reducers and types defined in your server module.
+
+In your `quickstart-chat` directory, run:
+
+```bash
+mkdir -p client/src/module_bindings
+spacetime generate --lang typescript --out-dir client/src/module_bindings --project-path server
+```
+
+> This command assumes you've already created a server module in `quickstart-chat/server`. If you haven't completed one of the server module quickstart guides, you can follow either the [Rust](/docs/modules/rust/quickstart) or [C#](/docs/modules/c-sharp/quickstart) module quickstart to create one and then return here.
+
+Take a look inside `client/src/module_bindings`. The CLI should have generated several files:
+
+```
+module_bindings
+├── identity_connected_reducer.ts
+├── identity_disconnected_reducer.ts
+├── index.ts
+├── init_reducer.ts
+├── message_table.ts
+├── message_type.ts
+├── send_message_reducer.ts
+├── set_name_reducer.ts
+├── user_table.ts
+└── user_type.ts
+```
+
+With `spacetime generate` we have generated TypeScript types derived from the types you specified in your module, which we can conveniently use in our client. We've placed these in the `module_bindings` folder. The main entry to the SpacetimeDB API is the `DbConnection`, a type which manages a connection to a remote database. Let's import it and a few other types into our `client/src/App.tsx`.
+
+```tsx
+import { DbConnection, type ErrorContext, type EventContext, Message, User } from './module_bindings';
+import { Identity } from '@clockworklabs/spacetimedb-sdk';
+```
+
+## Create your SpacetimeDB client
+
+Now that we've imported the `DbConnection` type, we can use it to connect our app to our database.
+
+Add the following to your `App` function, just below `const [newMessage, setNewMessage] = useState('');`:
+
+```tsx
+ const [connected, setConnected] = useState
+
+ Profile
+ {!settingName ? ( + <> +{name}
+ + + ) : ( + + )} +
+
+ Messages
+ {prettyMessages.length < 1 &&No messages
} +
+ {prettyMessages.map((message, key) => (
+
+
+
+ ))}
+ + {message.senderName} +
+{message.text}
+
+
+ System
+
+
+ {systemMessage}
+
+
+
+
+
+ );
+ }
+```
+
+Finally, let's also compute the name of the user from the `Identity` in our `name` variable. Replace `const name = '';` with the following:
+
+```tsx
+ const name =
+ users.get(identity?.toHexString())?.name ||
+ identity?.toHexString().substring(0, 8) ||
+ 'unknown';
+```
+
+### Calling Reducers
+
+Let's hook up our callbacks so we can send some messages and see them displayed in the app after being synchronized by SpacetimeDB. We need to update the `onSubmitNewName` and `onSubmitMessage` callbacks to send the appropriate reducer to the module.
+
+Modify the `onSubmitNewName` callback by adding a call to the `setName` reducer:
+
+```tsx
+ const onSubmitNewName = (e: React.FormEvent