Skip to main content

Running Locally

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

Things to Know​

  • ComposeDB requires running a Ceramic node (which uses IPFS) for decentralized data and a SQL instance for your index database.
  • ComposeDB server can also be run locally using Docker.
tip

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.

Requirements​

  • 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)

Setup​

First, download the Wheel:

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

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

./wheel

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.

Requirements​

Runtime

  • Node.js Version 16

Package Manager

  • npm Version 6

Supported Operating Systems

  • Linux
  • Mac
  • Windows
note

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).

Installation​

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

Configurations​

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: