From e57c1555cbb9635235b739b0a1d192d3dfe9b028 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Tue, 28 Oct 2025 14:54:38 -0700 Subject: [PATCH 1/3] clarify examples --- docs/pages/fund-agents-apps/run-gateway.mdx | 45 ++++++++++++--------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/pages/fund-agents-apps/run-gateway.mdx b/docs/pages/fund-agents-apps/run-gateway.mdx index 7924424a..d286eafd 100644 --- a/docs/pages/fund-agents-apps/run-gateway.mdx +++ b/docs/pages/fund-agents-apps/run-gateway.mdx @@ -94,20 +94,12 @@ Every app and agent needs an XMTP Gateway Service. ### For browser and mobile client apps -You must run the XMTP Gateway Service written in Go. Choose the option that works best for you: +You must run the XMTP Gateway Service written in Go. You have two options: -**Option 1: Basic Docker image** (No Go knowledge required) +- **For production**: Use the [example gateway service repository](https://github.com/xmtp/gateway-service-example) as a starting point to build your own custom gateway with authentication +- **For testing only**: Use the prebuilt Docker image (`xmtp/xmtpd-gateway:main`) which authorizes all requests without authentication -- XMTP provides a Docker image that works out of the box -- Authorizes all requests (add authentication for production) -- Suitable for testing - -**Option 2: Custom implementation** (Go knowledge required) - -- Start with XMTP's Go implementation -- Add your own authentication logic -- Implement custom rate limiting -- Required for apps with authentication needs +For detailed implementation steps, see [Deploy your XMTP Gateway Service](#deploy-your-xmtp-gateway-service). ### For agents and Node.js apps @@ -275,7 +267,7 @@ This identity will then be used for rate limiting, and will be passed to your `A :::code-group -```go [IP Address] +```go [IP address] // We provide a simple implementation that uses the client's IP address to identify users. For a production application, you should limit requests to only users actually authenticated in your application. package main @@ -393,7 +385,7 @@ func main() { ``` -```go [Rate Limiting] +```go [Rate limiting] package main import ( @@ -480,17 +472,34 @@ func main() { Deploy the XMTP Gateway Service on your infrastructure of choice, such as a container hosting service ($25-50/month minimum). -We provide a Docker image that corresponds to the bare bones example above that you can run with the appropriate environment variables set in any hosting provider that supports Docker. +### For production deployments + +Use the [example gateway service repository](https://github.com/xmtp/gateway-service-example) as your starting point: + +1. Fork or clone the repository +2. Customize the authentication logic for your app +3. Build your own Docker image from the included Dockerfile +4. Deploy your custom image to your hosting provider + +#### Additional recommendations + +The system is able to run without any external dependencies, but we recommend configuring a Redis instance to use for nonce management and rate limiting. + +If your XMTP Gateway Service goes down, messages will queue until it comes back online. Build redundancy, if needed. + +### For testing only + +You can use the prebuilt Docker image for local development and testing: ```bash [Bash] docker run -p 5050:5050 -p 5055:5055 -e XMTPD_PAYER_PRIVATE_KEY=... xmtp/xmtpd-gateway:main ``` -Most production apps will require some level of customization to authorize user requests. You can fork our [example repository](https://github.com/xmtp/gateway-service-example), which includes a Dockerfile and a sample configuration. +:::warning -The system is able to run without any external dependencies, but we recommend configuring a Redis instance to use for nonce management and rate limiting. +This pre-built image authorizes all requests without authentication. Never use it in production. -If your XMTP Gateway Service goes down, messages will queue until it comes back online. Build redundancy, if needed. +::: ## Test your XMTP Gateway Service From b66bf144f73466c752f727393e0de0e554896668 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Tue, 28 Oct 2025 16:15:11 -0700 Subject: [PATCH 2/3] feedback from saul <3 --- docs/pages/fund-agents-apps/run-gateway.mdx | 24 ++++++++++----------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/pages/fund-agents-apps/run-gateway.mdx b/docs/pages/fund-agents-apps/run-gateway.mdx index d286eafd..85fc673a 100644 --- a/docs/pages/fund-agents-apps/run-gateway.mdx +++ b/docs/pages/fund-agents-apps/run-gateway.mdx @@ -94,10 +94,7 @@ Every app and agent needs an XMTP Gateway Service. ### For browser and mobile client apps -You must run the XMTP Gateway Service written in Go. You have two options: - -- **For production**: Use the [example gateway service repository](https://github.com/xmtp/gateway-service-example) as a starting point to build your own custom gateway with authentication -- **For testing only**: Use the prebuilt Docker image (`xmtp/xmtpd-gateway:main`) which authorizes all requests without authentication +Use the [example gateway service repository](https://github.com/xmtp/gateway-service-example) as a starting point to build your own custom gateway with authentication For detailed implementation steps, see [Deploy your XMTP Gateway Service](#deploy-your-xmtp-gateway-service). @@ -470,16 +467,17 @@ func main() { ## Deploy your XMTP Gateway Service -Deploy the XMTP Gateway Service on your infrastructure of choice, such as a container hosting service ($25-50/month minimum). +:::tip[Example repo] -### For production deployments +You can start with the [example gateway service repository](https://github.com/xmtp/gateway-service-example). -Use the [example gateway service repository](https://github.com/xmtp/gateway-service-example) as your starting point: +::: -1. Fork or clone the repository -2. Customize the authentication logic for your app -3. Build your own Docker image from the included Dockerfile -4. Deploy your custom image to your hosting provider +1. Fork or clone the repository. +2. Add your own authentication logic. +3. Implement custom rate limiting. +4. Build your own Docker image from the included Dockerfile. +5. Deploy your custom image on your infrastructure of choice, such as a container hosting service ($25-50/month minimum). #### Additional recommendations @@ -487,7 +485,7 @@ The system is able to run without any external dependencies, but we recommend co If your XMTP Gateway Service goes down, messages will queue until it comes back online. Build redundancy, if needed. -### For testing only +## Test your XMTP Gateway Service You can use the prebuilt Docker image for local development and testing: @@ -501,7 +499,7 @@ This pre-built image authorizes all requests without authentication. Never use i ::: -## Test your XMTP Gateway Service +### Test scenarios Here are some high priority scenarios to test: From b4782dfa247792631419732369c9ab7111f4576a Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Tue, 4 Nov 2025 18:13:40 -0800 Subject: [PATCH 3/3] feedback from nick <3 --- docs/pages/fund-agents-apps/run-gateway.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/pages/fund-agents-apps/run-gateway.mdx b/docs/pages/fund-agents-apps/run-gateway.mdx index 85fc673a..02503bba 100644 --- a/docs/pages/fund-agents-apps/run-gateway.mdx +++ b/docs/pages/fund-agents-apps/run-gateway.mdx @@ -475,9 +475,8 @@ You can start with the [example gateway service repository](https://github.com/x 1. Fork or clone the repository. 2. Add your own authentication logic. -3. Implement custom rate limiting. -4. Build your own Docker image from the included Dockerfile. -5. Deploy your custom image on your infrastructure of choice, such as a container hosting service ($25-50/month minimum). +3. Configure your rate limits +4. Deploy your custom image on your infrastructure of choice, such as a container hosting service ($25-50/month minimum). #### Additional recommendations