diff --git a/README.md b/README.md index e07dfe68a6..b799df82f8 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,226 @@

- rivet_logo -

- -

- Managed game servers, matchmaking, and DDoS mitigation that lets you focus on building your game. + + + Rivet +

License Apache-2.0 - Calendar versioning - PRs Welcome GitHub commit activity GitHub closed issues + GitHub closed issues

-

- Home - Docs - Twitter - Discord -

+## Features -## 👾 Features +### 🎮 Dedicated Game Servers -- Everything is accessible from an easy to use [GUI, CLI, or API](https://rivet.gg/docs/general/gui-cli-api) -- [Serverless Lobbies](https://rivet.gg/docs/serverless-lobbies) for auto-scaling game lobbies -- [Flexible matchmaker](https://rivet.gg/docs/matchmaker) for placing players in lobbies with no wait times -- [CDN](https://rivet.gg/docs/cdn) for hosting assets and webpages with a custom domain or provided rivet.game subdomain -- [Game Guard](https://rivet.gg/docs/serverless-lobbies/concepts/game-guard) for DDoS mitigation and managed WebSocket SSL, TCP+TLS, and UDP -- Streamlined DevOps for teams -- Unified logging & monitoring & analytics -- No downtime deploys with easy rollbacks +Deploy game servers in minutes across multiple regions & clouds providers. -

- rivet_screenshot -

+- Optimize for performance or cost, servers starting at $2.85/mo +- Auto-scales 90% faster than AWS GameLift +- No-downtime deploys & instant rollbacks +- Monitoring & crash reporting -## 🚀 Getting Started +[Documentation](https://rivet.gg/docs/dynamic-servers) + +### 🛡️ DDoS Mitigation + +- No added latency +- Supports UDP & TCP & WebSockets & WebRTC +- Automatic SSL for game servers (WebSockets & TCP+TLS) + +[Documentation](https://rivet.gg/docs/dynamic-servers/concepts/game-guard) + +### 🌐 CDN + +Asset delivery, game downloads, & website hosting -### Rivet Cloud +- Custom domains +- Instant rollbacks +- Automatic SSL -[Rivet Cloud](https://rivet.gg) is the fastest way to get your game up and running. Sign up at [rivet.gg](https://rivet.gg) and get a free game server. +[Documentation](https://rivet.gg/docs/cdn) -### Self-hosting +### 🧩 Backend Modules + +Write server-side logic using TypeScript (or use your own API server) + +- Modules include matchmaking, parties, authentication, & more +- Postgres database included for persistence +- Powered by Open Game Backend + +[Documentation](https://opengb.dev/) + +## 🚀 Getting Started + +**Self-hosting & development** See the [setup guide](/docs/getting_started/DEVELOPMENT.md) to develop & deploy Rivet yourself. -## 📐 Architecture +**Rivet Cloud** -Below is a simplified architecture diagram of a Rivet cluster. +[Rivet Cloud](https://rivet.gg) is the fastest and most affordable way to get your game up and running. Sign up at [rivet.gg](https://rivet.gg). -![Architecture](/media/simplified_architecture.png) +## 💬 Community & Support -## 📖 Documentation Overview +**Discord** -> **Looking for documentation on building a game with Rivet?** -> -> Visit our [documentation for game developers](https://rivet.gg/docs)! +[Invite](https://rivet.gg/discord) -**Getting Started** +- **Lounge** The Rivet team is remote and does most of their work in public Discord voice chat. Come drop by if you have questions or want to hang! +- **#support** Ask questions about getting your game runnin on Rivet +- **#open-source-dev** Ask questions about the open source repo +- **#showcase** Show off your game, get feedback -- [Project Structure](/docs/getting_started/PROJECT_STRUCTURE.md) -- [Developing on Rivet](/docs/getting_started/DEVELOPMENT.md) -- [Debugging Rivet](/docs/getting_started/DEBUGGING.md) -- [Services](/docs/getting_started/SERVICES.md) -- [Error Handling](/docs/libraries/chirp/ERROR_HANDLING.md) +**Releases** -**Philosophy** +Stay up to date on the latest releases on [X](https://x.com/rivet_gg). -- [Why open source](/docs/philosophy/WHY_OPEN_SOURCE.md) +Technical release notes can be subscribed to by watcing this repository. -**Architecture** +**Bugs & Feature Requests** -- [Software Bill of Materials](/docs/infrastructure/SBOM.md) +Bugs and feature requests can be submitted as a GitHub Issue. -**About** +**Roadmap** -- [Notable missing features](/docs/about/MISSING_FEATURES.md) +We create public issues for most items on our roadmpa. +Subscribe to issues to get notified when they're updated. Add a 👍 reaction to issues to get them prioritized faster + +## 📐 Architecture + +We maintain a detailed architecture diagram [here](https://www.figma.com/file/GvCj77EG79NUoW1dRG4qkg/Architecture?type=whiteboard&node-id=0%3A1&t=WqMQ2r6avjM0jPK0-1). + +![Architecture](./media/architecture.png) + +## 📖 Documentation + +### Game developers + +Visit our documentation for game developers [here](https://rivet.gg/docs). + +### Internal documentation + + + +- [About](docs/about) + - [Telemetry](docs/about/TELEMETRY.md) +- [Getting Started](docs/getting_started) + - [Debugging](docs/getting_started/DEBUGGING.md) + - [Development Firewalls](docs/getting_started/DEVELOPMENT_FIREWALLS.md) + - [Development](docs/getting_started/DEVELOPMENT.md) + - [Project Structure](docs/getting_started/PROJECT_STRUCTURE.md) + - [Rust Analyzer](docs/getting_started/RUST_ANALYZER.md) + - [Services](docs/getting_started/SERVICES.md) +- [Infrastructure](docs/infrastructure) + - [Alertmanager](docs/infrastructure/alertmanager/TESTING_ALERTS.md) + - [ClickHouse](docs/infrastructure/clickhouse) + - [Readme](docs/infrastructure/clickhouse/README.md) + - [Troubleshooting](docs/infrastructure/clickhouse/TROUBLESHOOTING.md) + - [Why ClickHouse](docs/infrastructure/clickhouse/WHY_CLICKHOUSE.md) + - [Cockroach](docs/infrastructure/cockroach) + - [Readme](docs/infrastructure/cockroach/README.md) + - [Why Cockroach](docs/infrastructure/cockroach/WHY_COCKRAOCH.md) + - [Helm](docs/infrastructure/helm/TROUBLESHOOTING.md) + - [Imagor](docs/infrastructure/imagor/MEDIA_DELIVERY_AND_RESIZING.md) + - [K3d](docs/infrastructure/k3d/TROUBLESHOOTING.md) + - [K8s](docs/infrastructure/k8s) + - [Tips](docs/infrastructure/k8s/TIPS.md) + - [Troubleshooting](docs/infrastructure/k8s/TROUBLESHOOTING.md) + - [Minio](docs/infrastructure/minio/TROUBLESHOOTING.md) + - [Nats](docs/infrastructure/nats/TROUBLESHOOTING.md) + - [Networking](docs/infrastructure/networking) + - [Edge Cluster Networking](docs/infrastructure/networking/EDGE_CLUSTER_NETWORKING.md) + - [IP Ranges](docs/infrastructure/networking/IP_RANGES.md) + - [IPv6](docs/infrastructure/networking/IPV6.md) + - [Nix](docs/infrastructure/nix) + - [Lorri](docs/infrastructure/nix/LORRI.md) + - [Readme](docs/infrastructure/nix/README.md) + - [Nomad](docs/infrastructure/nomad/README.md) + - [Prometheus](docs/infrastructure/prometheus/README.md) + - [Protobuf](docs/infrastructure/protobuf/TIMESTAMPS.md) + - [Redis](docs/infrastructure/redis) + - [Hosting Providers](docs/infrastructure/redis/HOSTING_PROVIDERS.md) + - [Readme](docs/infrastructure/redis/README.md) + - [Sharding](docs/infrastructure/redis/SHARDING.md) + - [Tips](docs/infrastructure/redis/TIPS.md) + - [Troubleshooting](docs/infrastructure/redis/TROUBLESHOOTING.md) + - [Why Redis](docs/infrastructure/redis/WHY_REDIS.md) + - [Rust](docs/infrastructure/rust/TROUBLESHOOTING.md) + - [S3](docs/infrastructure/s3/TROUBLESHOOTING.md) + - [SBOM](docs/infrastructure/SBOM.md) + - [Terraform](docs/infrastructure/terraform) + - [Configs and Secrets](docs/infrastructure/terraform/CONFIGS_AND_SECRETS.md) + - [Readme](docs/infrastructure/terraform/README.md) + - [Troubleshooting](docs/infrastructure/terraform/TROUBLESHOOTING.md) + - [Timeouts](docs/infrastructure/TIMEOUTS.md) + - [Traefik](docs/infrastructure/traefik) + - [Ing Job Sizing Methodology](docs/infrastructure/traefik/ING_JOB_SIZING_METHODOLOGY.md) + - [Readme](docs/infrastructure/traefik/README.md) + - [Router Priorities](docs/infrastructure/traefik/ROUTER_PRIORITIES.md) + - [Traffic Server](docs/infrastructure/traffic_server) + - [Readme](docs/infrastructure/traffic_server/README.md) + - [Why Traffic Server](docs/infrastructure/traffic_server/WHY_TRAFFIC_SERVER.md) +- [Libraries](docs/libraries) + - [Bolt](docs/libraries/bolt) + - [Buggy Cache Purging](docs/libraries/bolt/BUGGY_CACHE_PURGING.md) + - [Config](docs/libraries/bolt/config) + - [Cloudflare](docs/libraries/bolt/config/CLOUDFLARE.md) + - [DNS](docs/libraries/bolt/config/DNS.md) + - [Linode](docs/libraries/bolt/config/LINODE.md) + - [Namespace](docs/libraries/bolt/config/NAMESPACE.md) + - [Sendgrid](docs/libraries/bolt/config/SENDGRID.md) + - [Debugging Services](docs/libraries/bolt/DEBUGGING_SERVICES.md) + - [Feature Flagging](docs/libraries/bolt/FEATURE_FLAGGING.md) + - [Readme](docs/libraries/bolt/README.md) + - [Regions](docs/libraries/bolt/REGIONS.md) + - [Chirp](docs/libraries/chirp) + - [Error Handling](docs/libraries/chirp/ERROR_HANDLING.md) + - [Glossary](docs/libraries/chirp/GLOSSARY.md) + - [Readme](docs/libraries/chirp/README.md) + - [Claims](docs/libraries/claims/JWT.md) +- [Packages](docs/packages) + - [Api-Auth](docs/packages/api-auth/HUB_AUTH.md) + - [Cluster](docs/packages/cluster) + - [Autoscaling](docs/packages/cluster/AUTOSCALING.md) + - [Server Provisioning](docs/packages/cluster/SERVER_PROVISIONING.md) + - [TLS and DNS](docs/packages/cluster/TLS_AND_DNS.md) + - [Job](docs/packages/job/DOCKER_IMAGE_DELIVERY.md) + - [Mm](docs/packages/mm/IDLE_LOBBIES.md) + - [Upload](docs/packages/upload/UPLOADS.md) +- [Philosophy](docs/philosophy) + - [Infra as Code](docs/philosophy/INFRA_AS_CODE.md) + - [Licensing](docs/philosophy/LICENSING.md) + - [Why Open Source](docs/philosophy/WHY_OPEN_SOURCE.md) +- [Processes](docs/processes) + - [Changelog](docs/processes/CHANGELOG.md) + - [Deploy Process](docs/processes/DEPLOY_PROCESS.md) + - [Making Changes](docs/processes/MAKING_CHANGES.md) + - [Project Management](docs/processes/PROJECT_MANAGEMENT.md) + - [Pull Requests](docs/processes/PULL_REQUESTS.md) + - [Refactoring](docs/processes/REFACTORING.md) + - [Releasing](docs/processes/RELEASING.md) + - [Versioning](docs/processes/VERSIONING.md) + + + +## License + +Apache 2.0 + +_Trust no-one, own your backend_ diff --git a/docs/about/MISSING_FEATURES.md b/docs/about/MISSING_FEATURES.md deleted file mode 100644 index 451b47054e..0000000000 --- a/docs/about/MISSING_FEATURES.md +++ /dev/null @@ -1,43 +0,0 @@ -# Notable Missing Features - -Have a feature request you don't see here? File an issue! - -## Standalone production setup guide - -We don't have a formal guide on how to deploy a production instance of Rivet yourself. - -#45 - -## Multiple clouds - -The open source version of Rivet only supports Linode at the moment. As we progress, we'll be bringing our other cloud providers to open source soon. - -## BYO job servers - -Rivet does not support bringing your own job servers (regardless of cloud) at the moment. This will eventually let you run your own hardware, including that toaster sitting in your basement. - -#44 - -## Slow development setup times - -It takes a long time to bootstrap a standalone Rivet cluster for development. Like _really_ long. Trust us, we get it. - -#43 - -## Distributed ClickHouse - -Self-hosted ClickHouse doesn't have a failover or sharding mechanism at the moment. - -#42 - -## Traffic Server `consistent_hash` routing - -Rivet heavily uses pull-through caching. At the moment, efficient caching is done through the good old throw-more-hardware-at-the-problem solution. Traffic Server has mechanics built in to make this work better. - -#31 - -## Sharable Grafana dashboards - -Rivet exposes metrics and logs for everything, but we don't publish Grafana internal dashboards. - -#41 diff --git a/docs/getting_started/DEVELOPMENT.md b/docs/getting_started/DEVELOPMENT.md index ed8136ce03..7aff6fc447 100644 --- a/docs/getting_started/DEVELOPMENT.md +++ b/docs/getting_started/DEVELOPMENT.md @@ -1,108 +1,117 @@ -# Developing +# Development -> 🚨 **READ BEFORE PROCEEDING** 🚨 +> [!IMPORTANT] +> +> **WIP Open-source Developer Experience** > > We encourage developers to use the self-hosted version of Rivet, but we're -> still working on improving the self-hosted developer experience. +> still working on improving the open source developer experience. > -> At the moment, all the services need to be built from scratch and deployed -> to a fully loaded Kubernetes cluster, which requires a beefy Linux machine. -> (Ideally 8 CPU cores, 32 GB RAM to build the required components for the -> cluster & run Rust Analyzer at the same time.) +> Once running, Rivet itself is very lightweight since it's all Rust. > -> Once running, Rivet itself is very lightweight since it's all Rust. If you -> want to help make Rivet easier to run, please reach out and we can help -> provide guidance on [Discord](https://discord.gg/BG2vqsJczH) when -> implementing the following issues: +> Relevant issues: > -> - -> - -> - - -There are two methods to set up a development environment: +> - +> - +> - +> - +> - +> - +> - -- Using Devcontainers/Codespaces ([instructions](#dev-container)) -- Directly on a virtual machine ([instructions](#virtual-machine)) +## Overview -Devcontainers are the primary choice as they're more supported by the -Rivet team. This is because their setup is consistant across Linux, MacOS, and -Windows, since devcontainers run inside of a Docker container. The Devcontainer -spec also allows you to use [GitHub -Codespaces](https://github.com/features/codespaces) if that is easier. +There are two ways to run Rivet: -## Dev Container +- [Dev Container](#method-1-dev-container) +- [Virtual Machine](#method-2-virtual-machine) -### Prerequisites +Once you have set up the fundamentals, you'll follow the [common steps](#common-steps). -- Visual Studio Code +## Method 1: Dev Container -**Windows Note**: If you're on Windows, you'll also [need WSL -installed](https://learn.microsoft.com/en-us/windows/wsl/install). Because the -default settings only give 16GB of ram to WSL, you'll need to [change the WSL -config](https://learn.microsoft.com/en-us/windows/wsl/wsl-config), and allocate -at least 24GB of ram to WSL. This is needed for the Rivet's source code to build -without running out of memory. +This method is recommended if testing Rivet locally or actively developing on the cluster. -**Codespaces Notes** At this point, you can either run a Devcontainer locally, or set up a GitHub -Codespace. Codespaces cost money to use, but are a zero-configuration -setup in case you might not have good hardware to use. You can start a Codespace from Rivet's main -repo, though you will need to configure it so that it has at least 32GB of ram. +Dev containers also allow you to use [GitHub Codespaces](https://github.com/features/codespaces) in order to develop without installing anything locally. -The rest of this section will assist you in setting up a Devcontainer locally. +### Prerequisites -### Step 1: Install dependencies +- Visual Studio Code -#### [Docker](https://docs.docker.com/engine/install/) +> [!NOTE] +> +> **Windows Users** +> +> You'll also [need WSL +> installed](https://learn.microsoft.com/en-us/windows/wsl/install). Because the +> default settings only give 16GB of ram to WSL, you'll need to [change the WSL +> config](https://learn.microsoft.com/en-us/windows/wsl/wsl-config), and allocate +> at least 24GB of ram to WSL. This is needed for the Rivet's source code to build +> without running out of memory. + +> [!NOTE] +> +> **Optionally using GitHub Codespaces** +> +> At this point, you can either run a dev containers locally, or set up a GitHub +> Codespace. Codespaces cost money to use, but are a zero-configuration setup in +> case you might not have good hardware to use. You can start a Codespace from +> Rivet's main repo, though you will need to configure it so that it has at least +> 32GB of ram. +> +> The rest of this section will assist you in setting up a dev container locally. -_Docker is required to run Rivet services._ +### Step 1: Install dependencies -See [here](https://docs.docker.com/engine/install/) for install instructions. +- **[Docker](https://docs.docker.com/engine/install/)** See [here](https://docs.docker.com/engine/install/) for install instructions. +- **[Git](https://git-scm.com/)** See [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) for install instructions. -### Step 2: Set up Devcontainers +### Step 2: Set up Dev Container -Devcontainers are a feature of Visual Studio Code, so you won't be able to use -them in other editors. To set up your editor to work with Devcontainers, you can +Dev containers are a feature of Visual Studio Code, so you won't be able to use +them in other editors. To set up your editor to work with dev containers, you can follow [this official guide](https://code.visualstudio.com/docs/devcontainers/containers) ### Step 3: Clone repository -We need to clone the repository for the Devcontainer configuration to work. Run: +We need to clone the repository for the dev container configuration to work. Run: ```sh git clone https://github.com/rivet-gg/rivet.git ``` -#### [Git](https://git-scm.com/) - -See [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) for -install instructions. - -**Windows Note**: If you're on Windows, you'll need to run a script that will -set up symlinks properly. This command needs to be run from inside WSL, or -inside the Devcontainer. Run: - -```sh -rm -rf "infra/helm/clickhouse/charts" -ln -s ../charts "infra/helm/clickhouse/charts" - -rm -rf "infra/helm/redis/charts" -ln -s ../charts "infra/helm/redis/charts" - -rm -rf "infra/helm/redis-cluster/charts" -ln -s ../charts "infra/helm/redis-cluster/charts" -``` +> [!IMPORTANT] +> +> **Windows Patch** +> +> If you're on Windows, you'll need to run a script that will +> set up symlinks properly. This command needs to be run from inside WSL, or +> inside the dev container. Run: +> +> ```sh +> rm -rf "infra/helm/clickhouse/charts" +> ln -s ../charts "infra/helm/clickhouse/charts" +> +> rm -rf "infra/helm/redis/charts" +> ln -s ../charts "infra/helm/redis/charts" +> +> rm -rf "infra/helm/redis-cluster/charts" +> ln -s ../charts "infra/helm/redis-cluster/charts" +> ``` -### Step 4: Open in Devcontainer +### Step 4: Open in Dev Container Open the repository in Visual Studio Code. You should see a prompt to "Reopen in -Container". Click this to start the Devcontainer. If you don't see this prompt, +Container". Click this to start the dev container. If you don't see this prompt, you can open the command palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and run and run "Remote-Containers: Reopen in Container". You can now skip to the [Common steps](#common-steps) section. -## Virtual Machine +## Method 2: Virtual Machine + +This is best if running a small deployment of Rivet on a cloud provider. ### Prerequisites @@ -114,21 +123,12 @@ You can now skip to the [Common steps](#common-steps) section. ### Step 1: Install dependencies -#### [Docker](https://docs.docker.com/engine/install/) - -_Docker is required to run Rivet services._ - -See [here](https://docs.docker.com/engine/install/) for install instructions. - -#### [Nix package manager](https://nixos.org/download.html) - -_Nix is required to set up the development environment._ - -Run: - -```sh -sh <(curl -L https://nixos.org/nix/install) --daemon -``` +- **[Docker](https://docs.docker.com/engine/install/)** See [here](https://docs.docker.com/engine/install/) for install instructions. +- **[Nix package manager](https://nixos.org/download.html)** Nix is required to set up the development environment. + - ```sh + sh <(curl -L https://nixos.org/nix/install) --daemon + ``` +- **[Git](https://git-scm.com/)** See [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) for install instructions. ### Step 2: Clone repository @@ -138,13 +138,9 @@ Run: git clone https://github.com/rivet-gg/rivet.git ``` -#### [Git](https://git-scm.com/) - -See [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) for install instructions. - ## Common steps -Now that you have the environment set up either in a Devcontainer or VM, we can +Now that you have the environment set up either in a dev container or VM, we can start setting up the Rivet cluster. > **Warp compatibility** @@ -159,17 +155,35 @@ Run: nix-shell --run "bolt init dev --yes" ``` -This will: - -1. Prompt you for parameters to generate your cluster's config -2. Provision required infrastructure for the cluster +This will run a series of scripts to set up the required Kubernetes cluster, required dependencies, and deploy Rivet to the cluster. Run this command any time you update to a new version of Rivet. -> **Tip** +> [!TIP] > > See the `namespaces/dev.toml` and `secrets/dev.toml` file to see the generated namespace configs. +> [!IMPORTANT] +> +> **Configure Public IP** +> +> If you're running Rivet on a virtual machine with a public IP, configure the IP in `namespaces/dev.toml`. +> +> For example: +> +> ```toml +> [cluster.single_node] +> public_ip = "1.2.3.4" +> ``` +> +> Then run again: +> +> ```sh +> nix-shell --run "bolt init dev --yes" +> ``` +> +> Ngrok support coming soon to simplify this for local development: + ### Step 2: Boot the Rivet Hub Now, you have to start the hub frontend. @@ -181,20 +195,18 @@ Now, you have to start the hub frontend. 4. Visit 5. Register an account with your email -### Step 3: Promote yourself to admin +### Step 3: Log in to cluster dashboard ```sh -nix-shell --run "bolt db sh db-user --query 'UPDATE users SET is_admin = true'" +bolt admin login ``` -You may need to clear the local cache for this change to appear. ([Related issue](https://github.com/rivet-gg/rivet/issues/152)) +This will provide you a URL to authenticate as an admin to the cluster. If you get logged out, run this command again to sign in again. -_This command sets all users to admin. We're assuming you're the only user in the cluster. Do not run this command again._ - -### Step 4: Create a developer group +### Next steps -You should now see a "Create Group" button on the hub. Proceed to create a group and start developing. +You now have a standalone instance of Rivet running. -### Next steps +This currently does not create & run game servers. This requires further tokens & configuration. Read more about [working with Bolt](/docs/libraries/bolt/README.md) or see other [helpful docs](/README.md#-documentation-overview) diff --git a/media/architecture.png b/media/architecture.png new file mode 100644 index 0000000000..c10bc282e0 Binary files /dev/null and b/media/architecture.png differ diff --git a/media/banner.png b/media/banner.png deleted file mode 100644 index d56b3d8969..0000000000 Binary files a/media/banner.png and /dev/null differ diff --git a/media/icon-text-black.svg b/media/icon-text-black.svg new file mode 100644 index 0000000000..14f0fe0526 --- /dev/null +++ b/media/icon-text-black.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/media/icon-text-white.svg b/media/icon-text-white.svg new file mode 100644 index 0000000000..1807618212 --- /dev/null +++ b/media/icon-text-white.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/media/simplified_architecture.png b/media/simplified_architecture.png deleted file mode 100644 index 47f6ba4d7a..0000000000 Binary files a/media/simplified_architecture.png and /dev/null differ diff --git a/media/splash_screenshot.png b/media/splash_screenshot.png deleted file mode 100644 index bfb4466910..0000000000 Binary files a/media/splash_screenshot.png and /dev/null differ