Skip to main content

Running Locally

Run a ComposeDB server on your local server, e.g. your laptop.

Things to Know

  • ComposeDB requires running a Ceramic node for decentralized data and a SQL instance for your index database.
  • ComposeDB requires a running ceramic-one node which is responsible for storing the data and coordinating with network participants. Make sure to configure and run the ceramic-one node first. You can find the steps of how to install and start the ceramic-one instance here.
  • ComposeDB server can also be run locally using Docker.

If you want to serve a live application in production, see Running in the Cloud.

Using Wheel

The easiest way to to run ComposeDB server on your local machine is using Wheel.


  • Node.js
  • jq
  • PostgreSQL (optional dependent on the network)

Head to Setup Your Environment section for more detailed dependency installation instructions.

Supported Operating Systems

  • Linux
  • Mac
  • Windows (only WSL2)


First, download the Wheel:

curl --proto '=https' --tlsv1.2 -sSf | bash

Once downloaded, start the Wheel and follow the setup prompt:


When following the prompt, make sure to accept the Include Caramic? and Include ComposeDB? option to start a local Ceramic node enabled with CompoeDB.

For detailed prompt reference and advanced Ceramic configurations head to Wheel Reference.

Using npm

Alternative way to run ComposeDB Server locally is using npm. This option includes more manual configurations.



  • Node.js Version 16

Package Manager

  • npm Version 6

Supported Operating Systems

  • Linux
  • Mac
  • Windows

For Windows, Windows Subsystem for Linux 2 (WSL2) is strongly recommended. Using the Windows command line is not portable and can cause compatibility issue when running the same configuration on a different operating system (e.g. in a Linux-based cloud deployment).


Install the Ceramic CLI and ComposeDB CLI using npm:

npm install -g @ceramicnetwork/cli @composedb/cli

Basic Setup

Admin account

If you don’t already have one, you’ll need to create an admin account (DID) to handle restricted changes and admin operations on your node. To do so, follow the steps in Set up your environment to generate a key & account. Once you’ve added your admin DID to the config file, return here.

Start the daemon

Using a command line utility or terminal, start the Ceramic daemon:

ceramic daemon


You now have a server running with the default configuration and a preconfigured IPFS node that can be used by the ComposeDB Client.

Next Steps

Edit your Server Configurations for your use case.

Check out our other guides for running a node: