Set up your environment
The first step to build with ComposeDB is setting up your development environment. Currently, there are two ways of how you can configure your working environment:
- Using the Wheel - the recommended and the easiest way to configure your 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
andyarn
.
Supported operating systems:
- Linux
- Mac
- Windows (only WSL2 )
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)
Node.js We've seen best results with Node.js v16. If you are using a different version (e.g. v18+), you may run into issues. Please use nvm
to install Node.js v16 for best results.
PostgreSQL: 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
You most likely don't need PostgreSQL when starting out, so you can safely skip this section, but 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
.
Moreover, this option will 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.
Interact with the example web3 social app
One of the easiest ways to get familiar with ComposeDB is through an actual example application built using ComposeDB on Ceramic.
This application is a simple implementation of Web3 social application and comes with the following features:
- Sign-in using DID Key or your Ethereum wallet.
- Create your user profile
- Create a post
- See posts created by other users in the Explore section of the app
- Follow other users
Developers can use this application to easily test ComposeDB features, see example implementation or even use this application as a basis of their own unique project.
Setting up
This application is set up by selecting Include ComposeDB Sample Application
when following the Wheel setup.
At the very end of the Wheel prompt you will see the output similar to the one below. It means that the Ceramic node is up and running and that the example
app is accessible following the specified path:
Application demo is available at
/Users/user/ceramic-getting-started/wheel/ceramic-test-app/ceramic-test-app-app. To run the demo application:
cd /Users/user/ceramic-getting-started/wheel/ceramic-test-app/ceramic-test-app-app
npm run nextDev
The output above also provides the instructions on how to spin up the app. Open a new terminal and run the suggested commands.
Navigate to the example app project directory:
cd /Users/user/ceramic-getting-started/wheel/ceramic-test-app/ceramic-test-app-app
Spin up the app:
npm run nextDev
This will launch the example app on a local server. The output of the command above should look similar to the following:
> demo@0.1.0 nextDev
> next dev
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
Copy the provided url http://localhost:3000
and open it in your browser. This will launch the example application
in your browser for you to interact with.
Interact with the application
Once your app is up and running you will be greeted with the following user interface:
From now on you can interact with the application:
- Authenticate using one of the provided methods:
- Key DID - it's a simple authentication method that encodes public key into a DID string
- Ethereum DID PKH - an authentication metod which uses and Ethereum wallet (e.g. Metamask) to authenticate users
- Create your account in the
Profile
section of the app - Create your first post in
Home
section of the app - See currently available posts in the
Explore
section of the app
After you interact with the application you can dive deeper into the underlying application files which you can find in the directory of your app.
Familiarise yourself with the actual implementations of specific features, e.g. - check out the composites
directory to see the implementation
of data models used for this application.
Check out this video tutorial for a more advanced explanations on how you can interact with this example app.
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. 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 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
Node.js We've seen best results with Node.js v16. If you are using a different version (e.g. v18+), you may run into issues. Please use nvm
to install Node.js v16 for best results.
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:
- npm
- pnpm
- yarn
npm install --location=global @ceramicnetwork/cli
pnpm install -g @ceramicnetwork/cli
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. Install ComposeDB CLI using the following command:
- npm
- pnpm
- yarn
npm install --location=global @composedb/cli@^0.5.0
pnpm add -g @composedb/cli@^0.5.0
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@^0.5.0
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:
- npm
- pnpm
- yarn
npm install -D @composedb/devtools@^0.5.0 @composedb/devtools-node@^0.5.0
pnpm add -D @composedb/devtools@^0.5.0 @composedb/devtools-node@^0.5.0
yarn add -D @composedb/devtools@^0.5.0 @composedb/devtools-node@^0.5.0
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:
- npm
- pnpm
- yarn
npx @ceramicnetwork/cli daemon
pnpm dlx @ceramicnetwork/cli daemon
yarn 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
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
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
The generated DID key will have the following format:
did: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
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 see 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 below:
{
...
"http-api": {
...
"admin-dids": ["did:key:..."]
},
"indexing": {
...
"allow-queries-before-historical-sync": true
}
}
Save this file and restart your Ceramic node for the changes to be applied. To do that, simply stop the process that is running the Ceramic node by hitting ctrl+C
on your keyboard
and spin up the node once 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.
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?
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?
Next Steps
After setting up your environment, the next step is to Create your composite →
Related Guides
Ready to upgrade from a local node to production? Learn how to deploy your app: Server configuration.