getting-started.md

sidebar_position: 2

Getting Started

To integrate cMix with your application logic, each instance needs to be connected to the cMix network. This begins with creating a new client, then registering the client identity with the xx cMix network. The client session data is stored in an encrypted key-value (EKV) store containing client state and keys.

The rest of this document outlines the steps for building a simple messaging app. It covers the entire process of integrating the cMix Client API (xxDK) in your application, registering within the xxDK and setting up a connection with the cMix network, setting up listeners, as well as sending and receiving messages.

Set Up the Client Locally

The following sections show how to connect to the public xx cMix network. When building your application, it is recommended to test with a local instance of the cMix network.

Skip CLI setup

The command-line tool that comes with the client is useful for testing network functionality. It also comes in handy for acquiring an NDF, a JSON file that describes the Nodes, Gateways, and other servers on the network and how to communicate with them.

:::note The NDF is required for registering within the xxDK. It can be acquired via the command line or with the DownloadAndVerifySignedNdfWithUrl() function from the client API. :::

Here are the commands for cloning and compiling the client (assuming golang 1.13 or newer). You’ll want to make sure to compile the right binary for your specific OS architecture:

git clone https://gitlab.com/elixxir/client.git client
cd client
go mod vendor -v
go mod tidy
go test ./...

# Compile a binary for your specific OS architecture using one of the following commands 

# Linux 64 bit binary
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags '-w -s' -o client.linux64 main.go
# Windows 64 bit binary
GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -ldflags '-w -s' -o client.win64 main.go
# Windows 32 bit binary
GOOS=windows GOARCH=386 CGO_ENABLED=0 go build -ldflags '-w -s' -o client.win32 main.go
# Mac OSX 64 bit binary (intel)
GOOS=darwin GOARCH=amd64 CGO_ENABLED=0 go build -ldflags '-w -s' -o client.darwin64 main.go

You can pull up the complete usage guide for using the client CLI via the --help flag:

go run main.go --help

Download an NDF

As noted earlier, you can fetch the NDF either through the command line or using the DownloadAndVerifySignedNdfWithUrl() API access point. This section describes the steps involved when using the CLI.

Skip this step

The getndf CLI command enables you to download the NDF from a network gateway. This does not require a pre-established client connection, but you will need the IP address for the gateway, a port, and an SSL certificate.

First, download an SSL certificate from the gateway:

// Download an SSL certificate (assumes you are running a gateway locally)
openssl s_client -showcerts -connect localhost:8440 < /dev/null 2>&1 | openssl x509 -outform PEM > certfile.pem

Next, download the NDF from the gateway: