Installation¶
Install a Ceramic client to perform writes and queries on the network.
Project status: Clay testnet is now live.Clay
is a decentralized public network ready for experimental application development and testing, but you still may encounter a few issues. It is the last major milestone before Fire
mainnet, which is under development and will launch in late Q1 2021. Documents published on Clay will not be portable to Fire. Please reach out on Discord or create an issue on Github to report any issues. Read the full announcement here.
Clients¶
Ceramic is available in a variety of clients suited for different use cases. For optimal performance, it is recommended that you use the HTTP Client when building an application.
Client | Description | Usage | Details |
---|---|---|---|
HTTP | An API for interacting with a remote Ceramic daemon over HTTP | Runtime | Learn |
Core | An API for running the entire Ceramic protocol in a local JavaScript environment, such as directly in-browser | Runtime | Learn |
CLI | A command line interface for interacting with a Ceramic node | Development | Learn |
Installation¶
Open your terminal and install a client using npm.
$ npm install @ceramicnetwork/http-client
$ npm install @ceramicnetwork/core
$ npm install -g @ceramicnetwork/cli
The CLI requires Node.js. Make sure to have an up-to-date version installed on your machine.
Setup¶
Setup your client within your project.
Import the HTTP client
import CeramicClient from '@ceramicnetwork/http-client'
Connect to a node
const API_URL = "http://yourceramicnode.com"
Node options
When using the HTTP API, you need to connect to a remote Ceramic node by passing its URL. Here are your options for nodes that run on the Clay testnet. Choose the option that best suits your use case:
- Community gateway
https://gateway-clay.ceramic.network
: Provides read-only access to the Clay testnet. (recommended) - Community dev node
https://ceramic-clay.3boxlabs.com
: Provides write and read access to the Clay testnet. This node is occasionally wiped and does not guarantee document persistence. (recommended) - Run your own node
https://yourEndpoint.com
: Provides write and read access to the Clay testnet. Running your own node allows you to persist documents and have full control, however this is process is not yet well documented. If you choose to run your own node, be sure to add your node to thepeerlist
by submitting a pull request. This allows other nodes to discover your node. - LocalHost
https://localhost:7007
: Provides read access to the Clay testnet. Writes made to this local node will only be available to nodes in thepeerlist
, but will not be available to other nodes on the network. Users need to first have a Ceramic daemon running locally using the CLI.
Create an instance
const ceramic = new CeramicClient(API_URL)
Import the Core client
import Ceramic from '@ceramicnetwork/core'
Import IPFS with dag-jose
Ceramic utilizes the dag-jose IPLD codec to store signed and encrypted data in IPFS. In order to create an instance of Ceramic core, you first need to create an instance of js-ipfs with dag-jose enabled.
import IPFS from 'ipfs'
import dagJose from 'dag-jose'
import basicsImport from 'multiformats/cjs/src/basics-import.js'
import legacy from 'multiformats/cjs/src/legacy.js'
basicsImport.multicodec.add(dagJose)
const format = legacy(basicsImport, dagJose.name)
Create an IPFS instance
const ipfs = Ipfs.create({
ipld: { formats: [format] },
})
Create a Ceramic instance
Create an instance of Ceramic by passing ipfs and an optional configuration object.
const ceramic = await Ceramic.create(ipfs, config)
Start the Ceramic daemon
This commands starts a local Ceramic node.
$ ceramic daemon
Connect to a remote Ceramic node
By default the Ceramic CLI communicates with the local node that you started with the ceramic daemon
command. However, it is possible to use the CLI to communicate with a remote node. To do this, use the config set
command to set the ceramicHost
variable to the URL of the node you wish to use.
$ ceramic config set ceramicHost 'https://yourceramicnode.com'
Node options
When using the CLI, you need to connect to a remote Ceramic node by passing its URL. Here are your options for nodes that run on the Clay testnet. Choose the option that best suits your use case:
- LocalHost
https://localhost:7007
: Enabled by default in the CLI. Provides read access to the Clay testnet. Writes made to this local node will only be available to nodes in thepeerlist
, but will not be available to other nodes on the network. - Community gateway
https://gateway-clay.ceramic.network
: Provides read-only access to the Clay testnet. - Community dev node
https://ceramic-clay.3boxlabs.com
: Provides write and read access to the Clay testnet. This node is occasionally wiped and does not guarantee document persistence. (recommended) - Run your own node
https://yourEndpoint.com
: Provides write and read access to the Clay testnet. Running your own node allows you to persist documents and have full control, however this is process is not yet well documented. If you choose to run your own node, be sure to add your node to thepeerlist
by submitting a pull request. This allows other nodes to discover your node.