From 235fe43553d429e72679d75ab70b2a0d23b6c92c Mon Sep 17 00:00:00 2001 From: Nathan Flurry Date: Fri, 17 Jan 2025 12:09:23 -0800 Subject: [PATCH] docs: reorganize self-hosting documentation --- docker/dev-full/README.md | 49 ++++++++++++ docker/monolith/README.md | 80 +++++++------------ .../docs/self-hosting/docker-compose.mdx | 53 +----------- site/src/content/docs/self-hosting/index.mdx | 5 +- .../docs/self-hosting/manual-deployment.mdx | 6 ++ .../docs/self-hosting/single-container.mdx | 72 +++++++++++++++++ site/src/sitemap/mod.ts | 4 + 7 files changed, 163 insertions(+), 106 deletions(-) create mode 100644 site/src/content/docs/self-hosting/single-container.mdx diff --git a/docker/dev-full/README.md b/docker/dev-full/README.md index 72b69b2bd9..4369d71f47 100644 --- a/docker/dev-full/README.md +++ b/docker/dev-full/README.md @@ -1,3 +1,52 @@ # Full Development Docker Compose +## Operating + Find our docs [here](https://rivet.gg/docs/self-hosting/docker-compose). + +## Development + +### Rebuilding + +To rebuild all services, run: + +```bash +docker compose -f docker/dev-full/docker-compose.yml up -d --build +``` + +To rebuild just the server, run: + +```bash +docker compose -f docker/dev-full/docker-compose.yml up -d --build rivet-server +``` + +### Logs + +To fetch logs for a service, run: + +```bash +docker compose -f docker/dev-full/docker-compose.yml logs {name} +``` + +#### Following + +To follow logs, run: + +```bash +docker compose -f docker/dev-full/docker-compose.yml logs -f {name} +``` + +#### Grep + +It's common to use grep (or the more modern +[ripgrep](https://www.google.com/search?q=ripgrep&oq=ripgrep&sourceid=chrome&ie=UTF-8)) to filter logs. + +For example, to find all errors in `rivet-server` with the 10 preceding lines, run: + +```bash +docker compose -f docker/dev-full/docker-compose.yml logs rivet-server | grep -B 10 level=error +``` + +Logs for `rivet-server` and `rivet-client` can also be configured via the environment. See [here](/docs/self-hosting/client-config) for +more information. + diff --git a/docker/monolith/README.md b/docker/monolith/README.md index 1033fe9631..5ada744a57 100644 --- a/docker/monolith/README.md +++ b/docker/monolith/README.md @@ -1,56 +1,46 @@ # Monolith Development Container -This container is intended for quickly running Rivet with a single `docker run` command or integrating Rivet -in to an existing Docker Compose environment. +## Operating -## Running +Find our docs [here](https://rivet.gg/docs/self-hosting/single-container). -### Build image +## Development + +### Build & run -Before running the image, it needs to be built: +Build & run the monolith container with extra logs enabled with: ```bash -docker build -f docker/universal/Dockerfile --target monolith -t rivet . +./scripts/docker/monolith_dev.ts ``` -### Run via `docker run` +Flags: -```bash -docker run -v "$(pwd)/rivet-data:/data" -p 8080:8080 -p 9000:9000 -p 7080:7080 -p 7443:7443 -p 7500-7599:7500-7599 -p 7600-7699:7600-7699 --platform linux/amd64 rivetgg/rivet -``` +- `--no-build` Skip build step +- `--no-clean` Skips removing data dir + +Data will be stored in `/tmp/rivet-data`. + +### Build & run manually -### Run via Docker Compose - -```yaml -services: - rivet: - image: rivetgg/rivet - platform: linux/amd64 - volumes: - - rivet-data:/data - ports: - - "8080:8080" - - "9000:9000" - - "7080:7080" - - "7443:7443" - - "7500-7599:7500-7599" - - "7600-7699:7600-7699" - -volumes: - rivet-data: +To build & run without using external scripts, run: + +```bash +docker build -f docker/universal/Dockerfile --target monolith -t rivet . +docker run --name rivet -v "$(pwd)/rivet-data:/data" -p 8080:8080 -p 9000:9000 -p 7080:7080 -p 7443:7443 -p 7500-7599:7500-7599 -p 7600-7699:7600-7699 --platform linux/amd64 rivet ``` -## Logs +### Logs Logs live in the `/var/log/{service name}` directory. You can read the logs by running: ```bash -docker exec mycontainer cat /var/log/rivet-server/current +docker exec rivet cat /var/log/rivet-server/current ``` -## Monitoring Vector +### Monitoring Vector Monitor `vector-server`: @@ -64,31 +54,17 @@ Monitor `vector-client`: vector top --url http://0.0.0.0:9510/graphql ``` -## Development - -Build & run the monolith container with extra logs enabled with: - -```bash -./scripts/docker/monolith_dev.ts -``` - -Flags: +### `s6-overlay` & generating services -- `--no-build` Skip build step -- `--no-clean` Skips removing data dir +All required services run inside the container by default using `s6-overlay`. -Data will be stored in `/tmp/rivet-data`. +These services are auto-generated by the `./scripts/docker/generate.ts` script. -## Port collisions +### Port collisions -Because all services live in the same address space, a lot of ports for dependent services are remapped. +Because all services live in the same address space, a lot of ports for dependent services are remapped internally. If a port uses numbers non-standard ports (e.g. ClickHouse has [many ports](https://clickhouse.com/docs/en/guides/sre/network-ports) while Redis uses a single well-known -port 6379). TODO +port 6379). -## `s6-overlay` & generating services - -All required services run inside the container by default using `s6-overlay`. - -These services are auto-generated by the `./scripts/docker/generate.ts` script. diff --git a/site/src/content/docs/self-hosting/docker-compose.mdx b/site/src/content/docs/self-hosting/docker-compose.mdx index 5a819884bb..62f36c0e49 100644 --- a/site/src/content/docs/self-hosting/docker-compose.mdx +++ b/site/src/content/docs/self-hosting/docker-compose.mdx @@ -61,58 +61,6 @@ To destroy all containers & volumes immediately, run: docker compose -f docker/dev-full/docker-compose.yml down -v -t 0 ``` -## Development - -### Rebuilding - -To rebuild all services, run: - -```bash -docker compose -f docker/dev-full/docker-compose.yml up -d --build -``` - -To rebuild just the server, run: - -```bash -docker compose -f docker/dev-full/docker-compose.yml up -d --build rivet-server -``` - -### Logs - -To fetch logs for a service, run: - -```bash -docker compose -f docker/dev-full/docker-compose.yml logs {name} -``` - -#### Following - -To follow logs, run: - -```bash -docker compose -f docker/dev-full/docker-compose.yml logs -f {name} -``` - -#### Grep - -It's common to use grep (or the more modern -[ripgrep](https://www.google.com/search?q=ripgrep&oq=ripgrep&sourceid=chrome&ie=UTF-8)) to filter logs. - -For example, to find all errors in `rivet-server` with the 10 preceding lines, run: - -```bash -docker compose -f docker/dev-full/docker-compose.yml logs rivet-server | grep -B 10 level=error -``` - -Logs for `rivet-server` and `rivet-client` can also be configured via the environment. See [here](/docs/self-hosting/client-config) for -more information. - -## Caveats - -The docker compose currently only supports host networking and host ports. - -Read more about host networking and ports here. - ## Troubleshooting ### Have you tried turning it off and on again? @@ -124,3 +72,4 @@ docker compose -f docker/dev-full/docker-compose.yml down -v -t 0 ``` This will destroy all containers & volumes immediately. + diff --git a/site/src/content/docs/self-hosting/index.mdx b/site/src/content/docs/self-hosting/index.mdx index 3e09fb3a91..e089381234 100644 --- a/site/src/content/docs/self-hosting/index.mdx +++ b/site/src/content/docs/self-hosting/index.mdx @@ -12,7 +12,8 @@ Join our Discord if you have any questions, we're h ## Deployment Methods - Best for quick, hobby setups. Easy to set up. + Best for local dev, including in existing Docker Compose, and single-node deployments. + Best for quick hobby setups. Best for complex architectures. Requires familiarity with Linux systems. @@ -21,4 +22,4 @@ Join our Discord if you have any questions, we're h - \ No newline at end of file + diff --git a/site/src/content/docs/self-hosting/manual-deployment.mdx b/site/src/content/docs/self-hosting/manual-deployment.mdx index 9124f5b2b5..3d839b359e 100644 --- a/site/src/content/docs/self-hosting/manual-deployment.mdx +++ b/site/src/content/docs/self-hosting/manual-deployment.mdx @@ -4,6 +4,12 @@ import Link from 'next/link'; Manual deployment of Rivet is meant for advanced use cases. For a simpler solution, try our Docker Compose. + + If you're deploying Rivet on a single machine or just want to try it, Rivet + can be started with a single `docker run` command. See [Single Container + Deployments](/docs/self-hosting/single-container) for more information. + + ## Prerequisites - Git diff --git a/site/src/content/docs/self-hosting/single-container.mdx b/site/src/content/docs/self-hosting/single-container.mdx new file mode 100644 index 0000000000..8dfcacd174 --- /dev/null +++ b/site/src/content/docs/self-hosting/single-container.mdx @@ -0,0 +1,72 @@ +# Local Development & Single Container + +A full Rivet cluster can be ran in a single container for use cases like: + +- Develop your app with a local Rivet cluster +- Including in an existing Docker Compose project +- Quick, single-node deployments + +## Prerequisites + +- Docker + +## Operation + +### Run with Docker CLI + +Start a Rivet cluster: + + + + +Run Rivet with: + +```sh +docker run --name rivet -v "$(pwd)/rivet-data:/data" -p 8080:8080 -p 9000:9000 -p 7080:7080 -p 7443:7443 -p 7500-7599:7500-7599 -p 7600-7699:7600-7699 --platform linux/amd64 rivetgg/rivet +``` + +This runs Rivet with HTTP, TCP, and UDP networking support. + + + + +If you don't need TCP & UDP support (which is common), you can run Rivet with just HTTP support: + +```sh +docker run --name rivet -v "$(pwd)/rivet-data:/data" -p 8080:8080 -p 9000:9000 -p 7080:7080 -p 7443:7443 --platform linux/amd64 rivetgg/rivet +``` + +This is sometimes needed if the port ranges required above have port conflicts with other software on your computer. + + + + +Data will be stored in a folder named `rivet-data` in your current directory. + +Next, follow the [setup guide](/docs/setup). + +### Integrate in to existing Docker Compose + +Integrate in to an existing project's Docker Compose with: + +```yaml +services: + rivet: + image: rivetgg/rivet + platform: linux/amd64 + volumes: + - rivet-data:/data + ports: + - "8080:8080" + - "9000:9000" + - "7080:7080" + - "7443:7443" + # Optional: Rivet Guard TCP & UDP + - "7500-7599:7500-7599" + # Optional: Host networking TCP & UDP + - "7600-7699:7600-7699" + +volumes: + rivet-data: +``` + diff --git a/site/src/sitemap/mod.ts b/site/src/sitemap/mod.ts index d553cb7d84..00643fb34a 100644 --- a/site/src/sitemap/mod.ts +++ b/site/src/sitemap/mod.ts @@ -248,6 +248,10 @@ export const sitemap = [ title: "Overview", href: "/docs/self-hosting", }, + { + title: "Local Dev & Single Container", + href: "/docs/self-hosting/single-container", + }, { title: "Docker Compose", href: "/docs/self-hosting/docker-compose",