Skip to main content
Version: 0.4.x

Set up your environment

The first step to build with ComposeDB is setting up your development environment. This guide will show you how to install and configure relevant packages and tools.

Installation using Wheel​

The easiest and recommended way to configure your local development environment is by using Wheel - a CLI starter tool for Ceramic that makes it easy to install necessary dependencies and run a Ceramic node enabled with ComposeDB.

Install the dependencies​

In order to use Wheel, you’ll have to install a few necessary dependencies:

  • Node.js
  • jq
  • PostgreSQL (optional dependent on the network, see below)
caution

Important: PostgreSQL is only required for a production configuration on the Mainnet. If you are new to ComposeDB on Ceramic and would like to quickly test it out, you can skip the PostgreSQL installation and come back to it once you are ready to scale your project.

Node.js​

If you don’t already have them installed, you will need to install at least:

  • NodeJS v16
  • npm v8 (installed automatically with NodeJS v16)

Use this command to make sure you have the correct versions installed.

node -v
npm -v

jq​

You will likely need to install jq on your machine as well. The installation method will highly depend on your operating system. Install it using one of the methods defined in the official tutorial here.

PostgreSQL​

Once you are ready take your project to the next level and use more advanced configurations, you will need Postgres installed on your machine to store indexed data. Postgres is required for running your applications on the Mainnet and is optional for other networks.

To install Postgres, follow instructions provided on official Postgres documentation. Once installed, open Postgres in your command line:

psql postgres

Configure your database using the following commands:

CREATE DATABASE ceramic;

CREATE ROLE ceramic WITH PASSWORD 'password' LOGIN;

GRANT ALL PRIVILEGES ON DATABASE "ceramic" to ceramic;

Configure the development environment​

We will use Wheel to install all of the dependencies needed to run Ceramic and ComposeDB as well as configure the working environment for your project. To download Wheel, open your terminal and run the command below:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ceramicstudio/wheel/main/wheel.sh | bash

Once Wheel is downloaded you are good to start configuring your project working directory. To kick it off, run the command below:

./wheel

This command will start a prompt in your command line allowing you to configure your entire working environment - from what Ceramic dependencies you’d like to install to how your Ceramic node should be configured.

You can run the following command to learn more about available Wheel commands and options:

./wheel --help

For developers who are completely new to Ceramic, we highly recommend starting the configuration with all default parameters. Go through the prompt and press Enter on your keyboard for each step. This will install the Ceramic and ComposeDB dependencies and spin up a local node running InMemory. This option will allow to test all of the features of Ceramic and ComposeDB in a very lightweight way without requiring you configure authentication for Ceramic Anchor Service.

caution

Important: Ceramic Anchor Service (CAS) is used to anchor Ceramic streams on a blockchain. CAS is require for dev, testnet-clay and mainnet networks. Since InMemory option doesn’t use CAS, data generated for your project will not be persisted.

If you are ready to dive into a more advanced configuration, head to Wheel reference page→ to learn more details about each parameter you can configure.

Installation using JavaScript package managers​

Another way to install the dependencies and configure Ceramic is using JavaScript package managers. This option requires more manual steps. The guide below covers this process step-by-step.

Install the dependencies​

Start with creating the project directory. Here you’ll store all your app’s local files:

mkdir my-project #creates a new directory
cd my-project #targets the created directory

Node.js​

If you don’t already have them installed, you will need to install Node.js v16 and a package manager. We primarily use pnpm, but npm and yarn are supported as well.

Use this command to make sure you have the correct versions installed.

node -v
pnpm -v

Ceramic​

ComposeDB runs on Ceramic, so you will need to run a Ceramic node. To get started, we recommend running a local Ceramic node. If you're interested in running the production node, you can follow the tutorial here.

The Ceramic CLI provides a set of commands that make it easier to run and manage Ceramic nodes. We will start by installing the Ceramic CLI:

pnpm install -g @ceramicnetwork/cli

ComposeDB​

Next install the ComposeDB CLI, which enables you to interact with ComposeDB data from your terminal. Install ComposeDB CLI using the following command:

pnpm add -g @composedb/cli

ComposeDB provides two additional libraries that support development:

  1. @composedb/devtools containing utilities related to managing composites
  2. @composedb/devtools-node which contains utilities for interacting with the local file system and starting a local HTTP server.

To install the development packages, run:

pnpm add -D @composedb/devtools @composedb/devtools-node

Setup​

Run a Ceramic node​

You can check that everything was installed correctly by spinning up a Ceramic node. Running the command below will start the Ceramic node in local mode and connect to Clay testnet. Indexing is a key component of ComposeDB, which syncs data across nodes. Enable indexing by toggling:

pnpm dlx @ceramicnetwork/cli daemon

If you see the following output in your terminal, that means you have successfully started a local node and connected to Clay testnet 🚀

IMPORTANT: Ceramic API running on 0.0.0.0:7007'
note

After you start a node, a node configuration file is created. Later in this guide, you’ll be editing this file. You can find it at the following path: ~/.ceramic/daemon.config.json

Developer Account​

Generate your private key​

You will need a private key for authorizing ComposeDB CLI commands in the later stages of development. You can generate it using the command below. Save it for later use:

composedb did:generate-private-key
caution

Important: Store your private key securely - the key allows changes to be made to you app. In addition, you will need it throughout the app development process.

Generate your account​

Indexing is one of the key features of ComposeDB. In order to notify the Ceramic node which models have to be indexed, the ComposeDB tools have to interact with the restricted Admin API. Calling the API requires an authenticated Decentralized Identifier (DID) to be provided in the node configuration file. Create a DID by running the following command, using the private key generated previously:

composedb did:from-private-key your-private-key

⚠️ Copy this authenticated DID key and store it in a secure place, just like with your private key above. This DID key will have to be provided in your Ceramic node’s configuration file which will ensure that only authorized users can make changes to your application, e.g. deploy models on your Ceramic node.

Using your account​

Provide the authenticated DID by opening the node configuration file which defaults to ~/.ceramic/daemon.config.json and specifying it in the admin-dids section of the file as shown below:

{
  ...
  "http-api": {
    ...
    "admin-dids": ["did:key:..."]
  },
  "indexing": {
    ...
    "allow-queries-before-historical-sync": true
  }
}

Save this file. By this point you should have your development environment and all configurations in place to get started working on your application.

Confirmation​

As a final test, spin up the Ceramic local node:

ceramic daemon --network=testnet-clay

Once again, you should see your local Ceramic node up and running as follows:

IMPORTANT: Ceramic API running on 0.0.0.0:7007'

Next steps​

After setting up your environment, the next step is to Create your composite →