Skip to main content

Installation

The Ceramic SDK enables user to interact with the Ceramic's primitive APIs for creating streams as well as producing events on streams, consuming events from streams, and aggregating stream state. Find it on GitHub at https://github.com/ceramicstudio/ceramic-sdk.

The SDK is written in TypeScript and published to NPM as @ceramic-sdk, with a handful of useful sub-packages:

  • @ceramic-sdk/events: Utilities for creating and signing events that comply to the Ceramic Event Log specifications
  • @ceramic-sdk/http-client: A simple client for ceramic-one's HTTP APIs.
  • @ceramic-sdk/identifiers: A handful of useful types for identifying streams and events.
  • @ceramic-sdk/model-client: A client that handles the creation and fetching of model stream types.
  • @ceramic-sdk/model-instance-client: A client that handles the creation and fetching of model instance document stream types.
While Ceramic will eventually support a wide array of different stream types, this guide will

focus on the use of models and model instance documents given they represent the predominant pattern developers currently use when interacting with the network. :::

The Ceramic SDK needs a ceramic-one daemon to connect to.

Let's get them all installed!

Install ceramic-one​

ceramic-one can run on macOS, Linux, or from within a docker container.

MacOS​

Install from Homebrew:

brew install ceramicnetwork/tap/ceramic-one

Linux (Debian-based distributions)​

Install a the latest release using dpkg:

# get deb.tar.gz
curl -LO https://github.com/ceramicnetwork/rust-ceramic/releases/download/latest/ceramic-one_x86_64-unknown-linux-gnu.tar.gz
# untar the Debian software package file
tar zxvf ceramic-one_x86_64-unknown-linux-gnu.tar.gz
# install with dpkg - package manager for Debian
dpkg -i ceramic-one.deb

Linux (from Source)​

# Install rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Install build tools
apt-get install -y build-essential pkg-config openssl libssl-dev unzip
# Update environment
source "$HOME/.cargo/env"
# Install protobuf
PROTOC_VERSION=3.20.1
PROTOC_ZIP=protoc-$PROTOC_VERSION-linux-x86_64.zip
curl --retry 3 --retry-max-time 90 -OL https://github.com/protocolbuffers/protobuf/releases/download/v$PROTOC_VERSION/$PROTOC_ZIP \
    && unzip -o $PROTOC_ZIP -d /usr/local bin/protoc \
    && unzip -o $PROTOC_ZIP -d /usr/local 'include/*' \
    && rm -f $PROTOC_ZIP
# Checkout rust-ceramic repo
git clone https://github.com/ceramicnetwork/rust-ceramic
# Enter repo and build
cd rust-ceramic
make build
cp ./target/release/ceramic-one /usr/local/bin/ceramic-one

Docker​

Start rust-ceramic using the host network:

docker run --network=host \
  public.ecr.aws/r5b3e0r5/3box/ceramic-one:latest

Docker-Compose​

  1. Create a testing directory, and enter it:
mkdir ceramic-recon
cd ceramic-recon
  1. Save the following docker-compose.yaml there:
version: '3.8'

services:
  ceramic-one:
    image: public.ecr.aws/r5b3e0r5/3box/ceramic-one:latest
    network_mode: "host"
    volumes:
      - ceramic-one-data:/root/.ceramic-one
volumes:
  ceramic-one-data:
    driver: local
  1. Run docker-compose up -d

Run the ceramic-one daemon​

# if necessary, include the path/to/the/binary e.g. /usr/local/bin/ceramic-one or ./target/release/ceramic-one
$ ceramic-one daemon

# There are many flags for the daemon CLI that can be passed directly or set as environment variables.
# See `DaemonOpts` in one/src/lib.rs for the complete list or pass the -h flag
$ ceramic-one daemon -h

# A few common options are overriding the log level:
$ RUST_LOG=warn,ceramic_one=info,ceramic_service=debug ceramic-one daemon
# Or modifying the network
$ ceramic-one daemon --network testnet-clay
$ ceramic-one daemon --network local --local-network-id 0
# Or changing where directory where all data is stored. This folder SHOULD be backed up in production
# and if you change the defaults, you MUST specify it every time you start the daemon.
$ ceramic-one daemon --store-dir ./custom-store-dir

Add client packages to your project​

npm install --save @ceramic-sdk/events @ceramic-sdk/identifiers @ceramic-sdk/http-client

Set up your client​

import { CeramicClient } from "@ceramic-sdk/http-client";

const client = new CeramicClient({ url: "http://localhost:5101" });

// Now some calls!
const response = await client.getVersion();

// Confirm it matches the version you just installed
console.log(response.version);