Skip to main content

Quickstart

The first step to build with ComposeDB is setting up your development environment. This Quickstart guide will walk you through the process of setting up your local development environment from scratch.

By the end of this guide you'll have a good understanding of how to get started building with ComposeDB.

1. Prerequisites​

  • Operating system: Linux, Mac, or Windows (only WSL2)
  • Node.js v20 - If you are using a different version, please use nvm to install Node.js v20 for best results.
  • npm v10 - Installed automatically with NodeJS v20

2. Installation​

There are a few ways to set up your environment. Choose the one that best fits your needs:

  • Using create-ceramic-app - get up and running quickly with a basic ComposeDB application with one command. Good for the first quick experience with Ceramic and ComposeDB.
  • Using the Wheel - the recommended and the easiest way to configure your full working environment and install the necessary dependencies.
  • Using JavaScript package managers - an alternative, more manual, way to configure your working environment which supports npm, pnpm and yarn.

Install and start the ceramic-one binary

All of the configuration options listed above require a ceramic-one binary up and running, which provides a data network access. You can run ceramic-one on your local machine using two simple steps listed below.

note

The instructions below cover the steps for the MacOS-based systems. If you are running on a Linux-based system, you can find the instructions here.

  1. Install the component using Homebrew:
brew install ceramicnetwork/tap/ceramic-one
  1. Start the ceramic-one using the following command:
ceramic-one daemon
note

By default, the command above will spin off a node which connects to a testnet-clay network. You can change this behaviour by providing a --network flag and specifying a network of your choice. For example:

ceramic-one daemon --network testnet-clay

By default ceramic-one will store its data in the current directory. You can configure this behaviour by specifying the --store-dirand --p2p-key-dir arguments. For example:

ceramic-one daemon --store-dir ~/.ceramic-one --p2p-key-dir ~/.ceramic-one

With ceramic-one binary up and running you can move on with the ComposeDB installation and configuration method of your choice.

2a. Installation using create-ceramic-app​

When to useWhen you want to get up and running quickly with a basic ComposeDB application with one command.
Time to installLess than 2 minutes

Just run the command below and follow the instructions:

npx create-ceramic-app

2b. Installation using Wheel​

When to useWhen you want to configure full working environment and start working on your own app.
Time to install5 minutes

The easiest and recommended way to configure your full 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. The installation instructions below are also covered in a video tutorial that you can follow:

Install the dependencies​

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

→ Node.js

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

  • NodeJS v20 - If you are using a different version, please use nvm to install Node.js v20 for best results.
  • npm v10 - Installed automatically with NodeJS v20.

Make sure you have the correct versions installed.

node -v
npm -v

→ jq

jq is a lightweight and flexible command-line JSON processor. The installation method depends on your operating system. Install it using one of the methods defined in the official tutorial here.

→ PostgreSQL (optional)

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. You will need Postgres installed on your machine to store indexed data.

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​

Make sure you have the ceramic-one binary up and running. To do that, follow the steps listed here.

Now you can 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, 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

Wheel will ask you a few questions, 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 the default options. This will install the Ceramic and ComposeDB dependencies and spin up a local node running InMemory.

At the end of configuration, this option will also give you an option to set up an example web3 social app for you to interact with and test ComposeDB features.

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.

2c. Installation using JavaScript package managers​

When to useWhen you want more control and a manual way to configure your working environment.
Time to install5-10 minutes

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. If you have followed the Wheel installation guide above, you can skip this section.

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 v20 and a package manager. We primarily use pnpm, but npm and yarn are supported as well.

  • NodeJS v20 - If you are using a different version, please use nvm to install Node.js v20 for best results.
  • pnpm v10

Make sure you have the correct versions installed.

node -v
pnpm -v

→ ceramic-one

Make sure you have the ceramic-one binary up and running. To do that, follow the steps listed here.

→ 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 one of the guides here.

Ceramic CLI provides a set of commands that make it easier to run and manage Ceramic nodes. 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:

pnpm add -g @composedb/cli
tip

The command above will install the latest version of the ComposeDB CLI. If you need to install a specific version, you can specify it by adding @version-number at the end of this command. You can also prefix the version number with ^ to install the latest patch. For example, if you'd like to install the latest patched version of ComposeDB 0.6.x you can run the command:

npm install --location=global @composedb/cli@^0.6.x

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​

All dependencies are installed. Now you can start setting up your project. The first step is to run a local Ceramic node.

→ 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

You should see the following output in your terminal. This means you have successfully started a local node and connected to Clay testnet 🚀

IMPORTANT: Ceramic API running on 0.0.0.0:7007

Developer Account​

Now, that you have installed everything successfully and are able to run the node, let's create a developer account. You can stop the node for now by using the keyboard combination Control+C.

→ 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:

composedb did:generate-private-key

You should see the output similar to the one below. Keep in mind that the key generated for your will be unique and will different from the example shown below:

✔ Generating random private key... Done!
5c7d2fa8ebc488f2fe008e5ed1db7f1f95c203434bbcbeb703491c405f6f31f0

Copy and save this key securely for later use.

important

Store your private key securely - the key allows changes to be made to your 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 instead of the placeholder variable your-private-key:

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

You should see the output similar to the one below. Here again, the DID created for you will be unique and will differ from the one shown below:

✔ Creating DID... Done!
did:key:z6MkoDgemAx51v8w692aZRLPdwP6UPKj3EgUhBTvbL7hCwLu

This key will be used to configure your node in the later steps of this guide.

important

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​

The very first time you spin up a Ceramic node, a node configuration file is automatically created for you where you can configure how your node is operated. Here you have to provide the DID key which is authorised to interact with the Admin API. The Ceramic node configuration file will be created inside of the automatically created directory ./ceramic in your home directory (usually /home/USERNAME/ on Linux or /Users/USERNAME/ on Mac). This directory can be accessed using the following command:

cd ~/.ceramic

Inside of this directory you should find the following files:

  • daemon.config.json - your Ceramic node configuration file
  • statestore - a local directory for persisting the data

Open the daemon.config.json file using your preferred code editor and provide the authenticated DID, generated in the generate your account step of this guide, in the admin-dids section of the file as shown in the example below:

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

Save this file and start your Ceramic node again by following the steps in the Confirmation section of this guide.

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

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

Congratulations!

3. Frequently Asked Questions​

Some questions and issues come up more often than others. We've compiled a list of the most common ones here.

Which setup method is better: Wheel or JavaScript package managers?

create-ceramic-app is the fastest. Good for your first interaction with ComposeDB.

Wheel is the recommended and the easiest way to configure your working environment and install all the necessary dependencies. We highly recommended going with Wheel if you are just starting out with Ceramic. Everything will be taken care of for you.

You might consider using JavaScript package managers if you are already familiar with Ceramic and need more manual configuration and control over your working environment.

Which operating systems are supported?

It's best to run Ceramic and ComposeDB on Linux or a Mac. You can also run it on Windows but you'll have to use WSL2 (Windows Subsystem for Linux). See the supported operating systems section at the top.

Which Node.js version is preferred?

We have seen the best results using Node.js v20. Earlier versions are no longer supported, later versions can cause issues for some users. While we're working on eliminating the issues, it's best to use Node v20 for now.

How long does it take to install the packages?

Installing everything (either with Wheel or JavaScript packages) takes usually between 2 and 10 minutes. Throughout the guide above you can find what kind of output you should be looking for to know that everything was installed correctly.

Where in the system do I run all of the commands?

Sometimes, especially when using JavaScript package managers to install Ceramic and ComposeDB, it's easy to forget that you need to run all of the commands in the app's directory. This directory is either automatically created for you when using Wheel, or you create it manually when using JavaScript package managers.

When installing with JavaScript package managers you need to open 2-3 terminal windows and run different commands, so it's easy to miss that you can be in a wrong directory. Please make sure you run all the commands where they're supposed to run.

Where can I find a Ceramic node configuration file, daemon.config.json?

When installing ComposeDB with JavaScript package managers, at some point you need to edit your Ceramic node config file. By default, it's in your home directory, in .ceramic folder (not in the app directory). It's easy to miss this detail so please check the path. This command should take you to the right directory: cd ~/.ceramic

How to restart a node after stopping it?

When you use Wheel to install Ceramic and ComposeDB, it takes care of the whole installation process. But please note that Wheel is just an installer, not a node launcher. If you want to launch Ceramic and ComposeDB again, after you have stopped it, you need to launch Ceramic daemon again and then launch ComposeDB.

You can launch Ceramic daemon by running the following command: ceramic daeomn --network=InMemory
You can launch ComposeDB by running the command: composedb

More on all of the composedb command options can be found in "2. Create your composite" section of this Getting Started guide.

How do I interact with the data once Ceramic node is running?

The easiest way to interact with data is through a GraphQL Server. You can find all the details on how to set it up, launch, and interact with your data in section of this guide, "3. Interact with data"

Error when creating a composite: ✖ request to http://localhost:7007/(...) failed, reason: connect ECONNREFUSED ::1:7007

The most likely cause is using Node.js v18. Please try using Node.js v20.
Error: npm ERR! code EACCESS
The most likely cause is read/write access on your system. Try running the command with sudo privileges.
What if my question is not answered on this page?

If your question is not answered in this guide, we recommend visiting our Community Forum (see the link in the footer). There, you can ask your question and get help from our community of developers and users. It's great to ask anything: from beginner to expert questions. The community and our developers are there to help you.

4. Next Steps​

In this Quickstart guide, you have learned how to get started with ComposeDB. You have set up your development environment and are ready to start building your application. The next steps are:

  • Create your composite - Learn how to create your first composite, a reusable data model that can be used across different applications.
  • Interact with data - Learn how to interact with data in ComposeDB, from creating, reading, updating, and deleting data to running complex queries.
  • Core ComposeDB concepts - Learn about the core concepts of ComposeDB, such as composites, schemas, and queries.
  • Running in the cloud - Ready to upgrade from a local node to production? Learn how to deploy your app.