You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**⚠️ Experimental:**This software is in early development. Expect frequent changes and unresolved issues.
3
+
**xmtpd (XMTP daemon)**is software that operators run to provide nodes in the decentralized XMTP network. The responsibilities of an xmtpd node include message storage and replication, censorship resistance, network resilience and recovery, and much more.
4
4
5
-
`xmtpd` (XMTP daemon) is an experimental version of XMTP node software. It is **not** the node software that currently forms the XMTP network.
5
+
This repository includes Helm charts that you can use to deploy xmtpd on Kubernetes. Charts are curated application definitions for Helm.
6
6
7
-
This repository includes Helm Charts that can be used to deploy XMTPD in Kubernetes. You may also contribute by submitting enhancement requests if you like. Charts are curated application definitions for Helm. For more information about installing and using Helm, see its
8
-
[README.md](https://github.com/helm/helm/tree/master/README.md). To get a quick introduction to Helm Charts see this [chart document](https://github.com/helm/helm/blob/master/docs/charts.md). For more information on using Helm, refer to the [Helm's documentation](https://github.com/kubernetes/helm#docs).
7
+
- To learn how to install Helm, see the Helm [README](https://github.com/helm/helm/tree/master/README.md).
9
8
10
-
## XMTPD Helm Chart Installation
9
+
- To learn how to use Helm, see the Helm [Quickstart Guide](https://helm.sh/docs/intro/quickstart/).
11
10
12
-
To add the XMTPD charts to your local helm repository, clone this repository locally.
11
+
-To learn more about Helm charts, see [Charts](https://helm.sh/docs/topics/charts/).
13
12
14
-
Eventually XMTP will provide a public Helm Charts release.
13
+
## What does the xmtpd Helm chart contain?
15
14
16
-
## 0) Alchemy Account
15
+
xmtpd is composed of two key deployments:
17
16
18
-
To run a node, you will need to have an [Alchemy Account](https://www.alchemy.com/).
19
-
You can follow their docs on the [API Key Creation](https://docs.alchemy.com/docs/alchemy-quickstart-guide#1key-create-an-alchemy-api-key).
17
+
1.**Synchronization service**
18
+
19
+
Handles data replication from other nodes to the local node, ensuring consistency across the network.
20
+
21
+
2.**API service**
22
+
23
+
Provides a client-facing gRPC endpoint for both nodes and client applications (like Converse) to interact with the system.
24
+
25
+
Both services support multiple replicas for high availability. However, adding replicas doesn't enhance the overall throughput of the service. As such, we recommend running exactly two replicas of each.
20
26
21
-
Once logged in, you can find and enable the [XMTP Chain](https://dashboard.alchemy.com/chains/xmtp).
22
-
Find and copy the XMTP app HTTP endpoint along with its API key. It should be in the format `https://xmtp-testnet.g.alchemy.com/v2/<apikey>`
27
+
## Prerequisites
23
28
24
-
## 1) Dependencies
29
+
Before diving into the installation process, ensure you have the following:
25
30
26
-
XMTPD needs a Postgres database to be running accessible from the cluster.
27
-
For example, you can use [Bitnami PG Helm Charts](https://bitnami.com/stack/postgresql/helm), or any other tooling to provision a Postgres database.
31
+
1.**Kubernetes cluster**: A running Kubernetes cluster with sufficient resources. To learn more, see [Kubernetes documentation](https://kubernetes.io/docs/home/). If you want to test the charts locally, you can use [Docker Desktop](https://www.docker.com/get-started/)
32
+
2.**Helm**: A package manager for Kubernetes. To learn more, see [Helm documentation](https://helm.sh/docs/).
33
+
```bash
34
+
brew install helm
35
+
```
36
+
3.**PostgreSQL database**: xmtpd relies on a PostgreSQL database. Tools like Bitnami’s [PostgreSQL Helm Charts](https://github.com/bitnami/charts/tree/main/bitnami/postgresql) can simplify database provisioning. xmtpd has been tested with Postgres versions 13 and newer. To learn more, see [PostgreSQL documentation](https://www.postgresql.org/docs/).
4. Clone the [xmtpd-infrastructure](https://github.com/xmtp/xmtpd-infrastructure) repo.
28
42
29
-
## 2) Installing MLS Validation Service
43
+
## Step 1. Get an Alchemy account
30
44
31
-
The XMTP MLS Validation Service does not have any external dependencies.
32
-
It is a stateless horizontally-scalable service.
45
+
To run xmtpd, you need an Alchemy account.
46
+
47
+
1. See [Create an Alchemy API Key](https://docs.alchemy.com/docs/alchemy-quickstart-guide#1key-create-an-alchemy-api-key) and log in to Alchemy.
48
+
49
+
2. Go to the [XMTP Chain page](https://dashboard.alchemy.com/chains/xmtp) and set the **Network Status** to ***Enabled***.
50
+
51
+
3. In the **API URL** column, click **Copy** to copy the XMTP app HTTPs endpoint along with its API key. It should use the format `https://xmtp-testnet.g.alchemy.com/v2/<apikey>`.
52
+
53
+
4. You will use this endpoint for the `XMTPD_CONTRACTS_RPC_URL` config option
54
+
55
+
## Step 2: Register your node
56
+
57
+
The xmtpd node software is open source, allowing anyone to run a node. However, only registered nodes can join the XMTP testnet.
58
+
59
+
To enable your node to join the XMTP testnet, register its public key and DNS address on the blockchain.
60
+
61
+
The node registration process is currently managed by [Ephemera](https://ephemerahq.com/), stewarding the development and adoption of XMTP. To learn more about the XMTP network node operator qualification criteria and selection process, see [XIP-54](https://community.xmtp.org/t/xip-54-xmtp-network-node-operator-qualification-criteria/868).
62
+
63
+
### **Step 2.1: Get all keys**
64
+
65
+
If you need a new private key, you can generate one using the xmtpd CLI Docker image.
66
+
67
+
```bash
68
+
docker run ghcr.io/xmtp/xmtpd-cli:latest generate-key | jq
> For your convenience while testing this flow, this command sets the PostgresSQL database password to `postgres`. Be sure to set a secure password before going live on the XMTP testnet.
129
+
130
+
You’ll use values in the response to update the `XMTPD_DB_WRITER_CONNECTION_STRING` value in your `xmtpd.yaml` configuration.
131
+
132
+
### Install the MLS validation service
133
+
134
+
The MLS validation service is a stateless, horizontally scalable service that xmtpd depends on.
- the MLS validation service running locally. XMTP Expects the format `http|https://<DNS|IP>[:port]`
44
-
- a blockchain with the [Nodes contract](https://github.com/xmtp/xmtpd)
45
-
- a private key
46
-
- the private key needs to be registered with the blockchain smart contract and a NodeID has to be issued. For more info see [Onboarding](https://github.com/xmtp/xmtpd/blob/main/doc/onboarding.md)
144
+
### Configure the xmtpd node
145
+
146
+
Before deploying xmtpd, create a configuration file (`xmtpd.yaml`) to specify the required environment variables.
147
+
148
+
Here is a sample configuration:
47
149
48
-
Create a `xmtpd.yaml` file and fill out all required variables:
Replace placeholder values with actual credentials and configurations:
168
+
169
+
- The `XMTPD_DB_WRITER_CONNECTION_STRING` is constructed as `postgres://<username>:<password>@<host-service>:<port>/<database>?sslmode=disable`
170
+
- Replace `<username>` with the username for pg-postgresql. The default value is usually `postgres`.
171
+
- Replace `<password>` with the password for pg-postgresql. If the password includes a special character, be sure to URL encode it.
172
+
- Replace `<host-service>` with `<helm-chart-name>-postgresql.<namespace>.svc.cluster.local`. The default value is usually `postgres-postgresql.default.svc.cluster.local`.
173
+
- Replace `<port>` with the port for pg-postgresql. The default value is usually `5432`.
174
+
175
+
If you are following the setup steps in this document, the full connection string will be: `postgres://postgres:[email protected]:5432/postgres?sslmode=disable`
176
+
- Replace `<apikey>` with your full Alchemy URL
177
+
- Replace `<private-key>` with the private key for your registered node.
178
+
- Ask the XMTP team to confirm the following address values:
179
+
- Nodes address
180
+
- Messages address
181
+
- Identity updates address
182
+
183
+
### Install xmtpd
184
+
185
+
Use Helm to deploy the xmtpd node. In the directory where you created your `xmtpd.yaml` configuration file, run:
186
+
67
187
```bash
68
188
helm install xmtpd xmtpd/ -f xmtpd.yaml
69
189
```
70
190
71
-
### Validating the installation
191
+
## Step 5: Validate the installation
192
+
193
+
After installation, verify that all the required pods are running:
194
+
195
+
```bash
196
+
kubectl get pods
197
+
```
198
+
199
+
Expected output:
72
200
73
-
Once you have successfully installed all charts, including a DB, you should see 4 pods running.
0 commit comments