Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 27 additions & 21 deletions docs/pages/fund-agents-apps/run-gateway.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -94,20 +94,9 @@ 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:
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

**Option 1: Basic Docker image** (No Go knowledge required)

- 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

Expand Down Expand Up @@ -275,7 +264,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

Expand Down Expand Up @@ -393,7 +382,7 @@ func main() {

```

```go [Rate Limiting]
```go [Rate limiting]
package main

import (
Expand Down Expand Up @@ -478,22 +467,39 @@ 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]

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.
You can start with the [example gateway service repository](https://github.com/xmtp/gateway-service-example).

```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.
1. Fork or clone the repository.
2. Add your own authentication logic.
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

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.

## Test your XMTP Gateway Service

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
```

:::warning

This pre-built image authorizes all requests without authentication. Never use it in production.

:::

### Test scenarios

Here are some high priority scenarios to test:

- Deploy and test XMTP Gateway Service
Expand Down