import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem";
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.
- Operating system: Linux, Mac, or Windows (only WSL2)
- Node.js v20 - If you are using a different version, please use
nvmto install Node.js v20 for best results. - npm v10 - Installed automatically with NodeJS v20
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,pnpmandyarn.
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. :::
- Install the component using Homebrew:
brew install ceramicnetwork/tap/ceramic-one- Start the
ceramic-oneusing 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-oneWith ceramic-one binary up and running you can move on with the ComposeDB installation and configuration method of your choice.
| **When to use** | When you want to get up and running quickly with a basic ComposeDB application with one command. |
| **Time to install** | Less than 2 minutes |
Just run the command below and follow the instructions:
<Tabs defaultValue="npm" groupId="package-manager" values={[ {label: 'npm', value: 'npm'}, {label: 'pnpm', value: 'pnpm'}, {label: 'yarn', value: 'yarn'}, {label: 'bun', value: 'bun'}, ]}>
npx create-ceramic-apppnpx create-ceramic-app:::tip
You need at least yarn 2.x to use the yarn dlx command. If you have an older version, upgrade it by running yarn set version stable and yarn install.
Then you can run the following command to create a new Ceramic app using yarn 2.x :::
yarn dlx create-ceramic-appbunx create-ceramic-app| **When to use** | When you want to configure full working environment and start working on your own app. |
| **Time to install** | 5 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:
<iframe width="660" height="415" src="https://www.youtube.com/embed/r68FXBTCBZ4?si=FRolthOjecS9Ys2_" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>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
nvmto 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 postgresConfigure your database using the following commands:
CREATE DATABASE ceramic;
CREATE ROLE ceramic WITH PASSWORD 'password' LOGIN;
GRANT ALL PRIVILEGES ON DATABASE "ceramic" to ceramic;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 | bashOnce Wheel is downloaded, you are good to start configuring your project working directory. To kick it off, run the command below:
./wheelWheel 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 --helpFor 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.
| **When to use** | When you want more control and a manual way to configure your working environment. |
| **Time to install** | 5-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.
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
nvmto 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:
<Tabs defaultValue="pnpm" groupId="npm-or-pnpm-or-yarnr" values={[ {label: 'npm', value: 'npm'}, {label: 'pnpm', value: 'pnpm'}, {label: 'yarn', value: 'yarn'}, ]}>
npm install --location=global @ceramicnetwork/clipnpm install -g @ceramicnetwork/cli:::caution
Global packages are only supported for yarn 2.x and older. For yarn 3.x and newer, use yarn dlx to run composedb cli commands
:::
yarn global add @ceramicnetwork/cli→ ComposeDB
Next install the ComposeDB CLI, which enables you to interact with ComposeDB data from your terminal:
<Tabs defaultValue="pnpm" groupId="npm-or-pnpm-or-yarnr" values={[ {label: 'npm', value: 'npm'}, {label: 'pnpm', value: 'pnpm'}, {label: 'yarn', value: 'yarn'}, ]}>
npm install --location=global @composedb/clipnpm add -g @composedb/cli:::caution
Global packages are only supported for yarn 2.x and older. For yarn 3.x and newer, use yarn dlx to run composedb cli commands
:::
yarn global add @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:
- @composedb/devtools containing utilities related to managing composites
- @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:
<Tabs defaultValue="pnpm" groupId="package-manager" values={[ {label: 'npm', value: 'npm'}, {label: 'pnpm', value: 'pnpm'}, {label: 'yarn', value: 'yarn'}, ]}>
npm install -D @composedb/devtools @composedb/devtools-nodepnpm add -D @composedb/devtools @composedb/devtools-nodeyarn add -D @composedb/devtools@^0.5.0 @composedb/devtools-node@^0.5.0All 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:
<Tabs defaultValue="pnpm" groupId="package-manager" values={[ {label: 'npm', value: 'npm'}, {label: 'pnpm', value: 'pnpm'}, {label: 'yarn', value: 'yarn'}, ]}>
npx @ceramicnetwork/cli daemonpnpm dlx @ceramicnetwork/cli daemonyarn dlx @ceramicnetwork/cli daemonYou 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:7007Now, 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-keyYou 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!
5c7d2fa8ebc488f2fe008e5ed1db7f1f95c203434bbcbeb703491c405f6f31f0Copy 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-keyYou 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:z6MkoDgemAx51v8w692aZRLPdwP6UPKj3EgUhBTvbL7hCwLuThis 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.
:::
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 ~/.ceramicInside of this directory you should find the following files:
daemon.config.json- your Ceramic node configuration filestatestore- 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.
As a final test, spin up the Ceramic local node:
ceramic daemon --network=testnet-clayOnce again, you should see your local Ceramic node up and running as follows:
IMPORTANT: Ceramic API running on 0.0.0.0:7007By this point you should have your development environment and all configurations in place to get started working on your application.
Congratulations!
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?
Which Node.js version is preferred?
How long does it take to install the packages?
Where in the system do I run all of the commands?
Where can I find a Ceramic node configuration file, daemon.config.json?
How to restart a node after stopping it?
How do I interact with the data once Ceramic node is running?
Error when creating a composite: ✖ request to http://localhost:7007/(...) failed, reason: connect ECONNREFUSED ::1:7007
Error: npm ERR! code EACCESS
What if my question is not answered on this page?
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.