Run a push notification server for an app built with XMTP

This guide supplements the core instructions provided in the example-notification-server-go repository. The guide aims to address some common setup misconceptions and issues.

This guide is for macOS users, but the steps should be similar for Linux users.

Useful resources

Install Docker

Install Docker Desktop:
- Mac
- Windows
- Linux
You must also have Docker and Docker Compose installed on your system. You can install them using Homebrew:
Bash
```
brew install docker docker-compose docker-credential-desktop
```
Make sure Docker Desktop is running by searching for Docker in Spotlight and opening the application. You don't need to interact with the Docker UI. We're going to use terminal commands only.

Install Go

If you need to upgrade Go on your system, you can do it via Homebrew:

Bash

brew install go

If you encounter an error like Error: go 1.17.2 is already installed, you already have Go installed on your system.

You can check the version of Go installed on your system using:

Bash

brew update
brew upgrade go

After following these steps, you can update Homebrew and upgrade Go without issues.

Set up the server

To start the XMTP service and database, navigate to the project terminal and run:
Bash
```
./dev/up
```
If you encounter an error like error getting credentials - err: docker-credential-desktop resolves to executable in current directory (./docker-credential-desktop), out:, it's likely because Docker is not running. Make sure Docker Desktop is running and try the command again.
Build the server using:
Bash
```
./dev/build
```
During the build, if you encounter any Go-related errors like missing go.sum entries, use the suggested go get or go mod download commands in the error messages to resolve them. For example, if you see missing go.sum entry; to add it: go mod download golang.org/x/sys, run:
Bash
```
go mod download golang.org/x/sys
```
If you encounter errors related to Go build comments like //go:build comment without // +build comment, you can ignore them as they are warnings about future deprecations and won't prevent your code from running.

Run the server

Run the server using the ./dev/run script with the --xmtp-listener and --api flags:

Bash

./dev/up

./dev/up in CLI

Bash

source .env
./dev/run --xmtp-listener --api

This starts both the worker and api services. The worker listens for new messages on the XMTP network and sends push notifications. The api service handles HTTP/GRPC requests.

./dev/run --xmtp-listener --api in CLI

You can now send notifications to your device using an XMTP push notification client.

dev/run in CLI

Troubleshooting

If Docker or Docker Compose commands aren't recognized, it might mean that they aren't installed or their executable paths aren't included in your system's PATH variable. Make sure Docker and Docker Compose are installed and their paths are included in your system's PATH.
If you encounter Go-related errors during the build, it's often due to missing packages or outdated versions. Make sure your Go is up to date and use the go get or go mod download commands to fetch the necessary dependencies.
If you encounter any error like ./dev/up: line 3: docker-compose: command not found, it's because you don't have Docker Compose installed on your system. Use the above command to install it.
If you see warnings about //go:build comment without // +build comment, these are warnings about future deprecations in Go. They won't prevent your code from running and can be ignored.
If brew update gives errors, it might be due to changes in Homebrew's repository. Homebrew switched to using main as its default branch. The steps provided in the "Upgrading Go" section should help resolve this issue.
If you encounter any errors during brew update, such as fatal: couldn't find remote ref refs/heads/master, Homebrew is having trouble updating its repositories. To fix this, run:
Bash
```
cd $(brew --repository)
git checkout main
git reset --hard origin/main
```

Here is a piece of code that points to the ports and network. Be sure to use TLS like this ./dev/run --xmtp-listener-tls --api.

static func envToUrl(env: XMTPEnvironment) -> String {
 switch env {
    case XMTPEnvironment.local: return "http://localhost:5556/"
    case XMTPEnvironment.dev: return "https://dev.xmtp.network:5556/"
    case XMTPEnvironment.production: return "https://production.xmtp.network:5556/"
 }
}

If you run into any other issues or questions, don't hesitate to ask for help in the XMTP Devs 💪 group chat, powered by XMTP.