This document is a collection of resources that may be helpful to new ceramic developers. To get you up and running quickly, the following steps should address all major "gotchas" to get a vanilla dev machine up and running as quickly as possible.
Open the js-ceramic project. Set the Run/Debug configuration template (under Run..Edit Configuration..Edit Configuration Templates) as follows:
The Application parameters used in this example are:
daemon --port 7007 --hostname 0.0.0.0 --network dev-unstable --anchor-service-api https://cas-dev.3boxlabs.com --debug true --ethereum-rpc https://rinkeby.infura.io/v3/b6685df41e1647c4be0046dfa62a020b
This configuration will allow running the ceramic daemon from the debugger and setting breakpoints in the daemon.
Note that using --network dev-unstable will cause your node connecting to unstable development ceramic network. You can also make it connect to clay testnet with --network clay-testnet or, if you want your node to be completely isolated from any network, without the need to run a local CAS service, you can also use --network inmemory.
- Node
20 - npm
v8
-
Install XCode & Command Line tools:
xcode-select --install -
Install Brew
brew install npm
INFO: For switching between node versions one could use n, fnm or nvm
CLI helpers commands on how to start up environment and debug local code base.
Compile all packages/full library: npm run clean && npm install && npm run build
Run locally compiled ceramic code: cd ~/js-ceramic/packages/cli/bin; node ceramic.js daemon
INFO: this will invoke the daemon with the default configuration values found in ~/.ceramic/daemon.config.json
Run docker with local code base: docker build -t js-ceramic-debug::latest -f Dockerfile.daemon .
Run on Clayground (full environment containerized): docker run --rm --name ceramic -p 7007:7007 ceramicnetwork/js-ceramic:dev daemon --port "7007" --hostname 0.0.0.0 --network dev-unstable --anchor-service-api https://cas-dev.3boxlabs.com --debug true --ethereum-rpc https://rinkeby.infura.io/v3/b6685df41e1647c4be0046dfa62a020b
Import this Postman Collection of queries to see a sample of API calls that can be used to exercise and explore common endpoints.
By default the collection connects to the public dev network, but you can easily overwrite the local variables to point to your locally running daemon by updating ceramic_hostname to http://localhost:7007.
3id-did-resolver - 3Box ID
blockchain-utils-*
-
linking- client side app devs (that would like to auth ceramic using specific blockchains / cosmos, eth, etc.) -
validation- contract part - eth accounts, against blockchain
Responsible for creation and validation. Once we link an account you have to request the signature from your blockchain.
etherum.ts/createLink(did) -> sign
canary-integration - standalone test (capability, tile & tile update)
cli - package for the ceramic cli (mostly daemon) -> see examples at the beginning how to start it up
common - helper functions
core - code for ceramic node (invoked via ceramic daemon) // internal http and core API
store- pinning and level state store; snapshot of a stream statestate-management- stream is mutable; check on state progression. Some streams are better kept in memory vs. some street could be offloaded to storagepubsub- node to node communication - push based messaging; Mostly implemented as Observableanchor- anchoring or validating it inside the ceramic node
http-client - with any remote node - http endpoint -> connect to a node
ipfs-daemon - DEPRECATED
ipfs-topology - mechanism to safely bootstrap connections to other ceramic nodes on the network
pinning-* - all for pinning
-
powergate- 3BoxLabs integration with 3rd party SPI for $FILECOIN support (worked at some point but not sure anymore) -
crust- crust.network - alternative to filecoin -
aggregation-> allows one to pin data to multiple backends (IPFS, Arweave, Crust, Filecoin, etc.) simultaneously
stream-caip10-link & *-stream-tile - immutable ipfs record / creation
stream-tile - Tile Stream Type stores a mutable JSON document with schema validation, providing similar functionality as a NoSQL document
stream-tile-handler - verifies public commits (runs on backend)
streamid - pure reference to host stream
commitid - references particular state / IPFS record in the stream evolution
Error: Can't find Python executable "python", you can set the PYTHON env variable. when installing JS HTTP CLIENT
By default macOS does not ship with an alias for python which breaks the standard ceramic npm
package install. Install pyenv and add it to your local PATH prior to installation. You can skip this step if you are only working with the local codebase.
$ brew install pyenv
You will then need to install python2 and python3
pyenv install 3.11
pyenv install 2.7
You will then need to add them both to the global pyenv environment
pyenv global 3.11 2.7
optionally add additional useful aliases for grepping in the project directory:
alias ggrep='grep -r --exclude-dir node_modules --exclude package.json --exclude package-lock.json'
alias tgrep='grep -r --exclude-dir node_modules --include=\*.ts --exclude package.json --exclude package-lock.json'