OrbisDB connects you to the GraphQL system that manages your Web3 data using the Ceramic network. It's a decentralized, open-source database built on top of web3 technologies, offering secure, efficient storage and query capabilities for your data.
Get up and running with web3.db-fileconnector in minutes:
- Node.js: v18.17.0 or later
- npm: v8.6.0 or later
- Docker: v20.10 or later (optional, for containerized setup)
# 1. Clone the repository
git clone https://github.com/jhead12/web3db-fileconnector/orbisdb.git
cd web3db-fileconnector
# 2. Create and configure environment variables
npm run create-env
# Edit the .env file with your values
# 3. Install dependencies
npm install
# 4. Start Ceramic network (in-memory mode for testing)
npx ceramic-one daemon --network inmemory
# 5. In a new terminal, start the development server
npm run devYour application is now running:
- Client: http://localhost:3000
- Server: http://localhost:7008
- GraphQL Playground: http://localhost:7008/graphql
# 1. Clone the repository
git clone https://github.com/jhead12/web3db-fileconnector/orbisdb.git
cd web3db-fileconnector
# 2. Create and configure environment variables
npm run create-env
# Edit the .env file with your values
# 3. Build and start all services
docker-compose up -d
# 4. Check that all services are running
docker-compose psYour containerized application is now running:
- Client: http://localhost:3000
- Server: http://localhost:7008
- Ceramic: http://localhost:3001
- PostgreSQL: localhost:5432
- Available Scripts
- Development Workflow
- Detailed Installation
- Docker Integration
- Environment Variables
- Troubleshooting
- License & Contact
| Script | Description |
|---|---|
npm run dev |
Start the development server |
npm run build |
Build the Next.js client application |
npm run start |
Run the application in production mode |
npm run dev:docker |
Start with Docker and run development server |
npm run dev:watch |
Start with auto-restart on file changes |
npm run dev:debug |
Start with debug logging enabled |
| Script | Description |
|---|---|
npm run create-env |
Create a .env file from template |
npm run ceramic:build |
Set up and manage Ceramic DB |
npm run system:check |
Verify server dependencies and configuration |
npm run clean |
Remove build cache and dependencies |
npm run clean:all |
Remove all build artifacts for a fresh start |
npm run format |
Format code using Prettier |
npm run lint |
Check code quality with ESLint |
| Script | Description |
|---|---|
npm run docker:build |
Build the Docker image |
npm run docker:start |
Start the Docker container |
npm run docker:stop |
Stop the Docker container |
npm run docker:restart |
Restart the Docker container |
npm run docker:remove |
Remove the Docker container |
npm run docker:status |
Show Docker container status |
| Script | Description |
|---|---|
npm run publish:npm |
Publish to npm with public access |
npm run publish:docker |
Build and push Docker image |
npm run publish:github |
Publish to npm and Docker |
npm run publish |
Build and restart Docker container |
Choose the development mode that best suits your needs:
# Standard development
npm run dev
# Auto-restart on changes
npm run dev:watch
# Debug mode with detailed logging
npm run dev:debug
# Development with Docker
npm run dev:docker# Build the client application
npm run build
# Start in production mode
npm run start# Format code
npm run format
# Lint code
npm run lintOur project includes an automated setup script to quickly configure and manage your Ceramic DB.
Prerequisites:
- Operating system: Linux, Mac, or Windows (with WSL2)
- Node.js v20 (use nvm to install if needed)
- npm v10 (installed automatically with Node.js v20)
- A running ceramic-one node (see below)
Setting up ceramic-one:
# MacOS (using Homebrew)
brew install ceramicnetwork/tap/ceramic-one
ceramic-one daemon --network in-memory
# For other networks:
# ceramic-one daemon --network testnet-clayRunning the Wheel Script:
cd server
./wheelDuring execution, you'll configure:
- Project name and directory
- Network selection (choose
inmemoryfor local testing) - Ceramic & ComposeDB integration options
- Sample application inclusion
- DID secret key path
After configuration, start Ceramic:
./ceramic daemon --config /path/to/project/ceramic-app/daemon_config.jsonOn MacOS:
brew install ceramicnetwork/tap/ceramic-one
ceramic-one daemon --network inmemoryOn Windows (with Node.js v18+):
npm install -g @ceramicnetwork/cli
ceramic did:generate # Optional: initialize your Ceramic identity
ceramic daemon --network inmemoryOnce Ceramic is running, connect it to OrbisDB:
# Get your Ceramic ID
ceramic id
# Initialize OrbisDB with your Ceramic ID
pnpm run init --ceramic-id <ceramic-id>- Docker v20.10+
- Docker Compose v1.29+
- Windows users: WSL2 enabled with Docker Desktop
The project uses multiple containers:
- js-client: Next.js frontend (port 3000)
- js-server: Main application server (port 7008)
- ts-ceramic-mcp-app: Ceramic integration (port 3001)
- postgres: PostgreSQL database with pgvector (port 5432)
# Start all services
docker-compose up -d
# View running containers
docker-compose ps
# View logs
docker-compose logs
# Stop all services
docker-compose down# Start the pgvector Docker container
npm run docker:start
# Check Docker status
npm run docker:status
# Stop Docker container
npm run docker:stopCreate a .env file at the project root (use npm run create-env to create from template):
# Ceramic Configuration
CERAMIC_URL='http://localhost:7007'
CERAMIC_INSTANCE='<YOUR_INSTANCE_URL>'
CERAMIC_APIKey='<YOUR_API_KEY>'
# OrbisDB Configuration
ORBISDB_API_URL=https://rpc.ankr.com/eth_holesky/
ORBISDB_API_KEY=https://rpc.ankr.com/multichain/
ORBISDB_CHAIN_ID=17000
ORBISDB_CONTRACT_ADDRESS=0xYourOrbisDBContractAddresc
# IPFS Configuration
IPFS_PATH='/ipfs'
IPFS_GATEWAY='https://ipfs.io/ipfs/'
IPFS_API_URL='https://ipfs.infura.io:5001/api/v0'
IPFS_API_KEY='<YOUR_INFURA_IPFS_API_KEY>'
IPFS_API_SECRET='<YOUR_INFURA_IPFS_API_SECRET>'
IPFS_PROJECT_ID='<YOUR_INFURA_IPFS_PROJECT_ID>'Problem: Cannot connect to Ceramic network Solution:
# Check if Ceramic is running
ceramic-one status
# Restart Ceramic daemon
ceramic-one daemon --network inmemoryProblem: Container fails to start Solution:
# Check logs
docker-compose logs
# Rebuild containers
docker-compose down
docker-compose build --no-cache
docker-compose up -dProblem: Port already in use Solution:
# Clear ports
npm run clear-port
# Or manually kill the process using the port
# For example, to free port 7008:
lsof -i :7008
kill -9 <PID>- Path Issues: Ensure Node.js, Ceramic CLI, and other tools are in your system PATH
- Permission Errors: Run PowerShell or Command Prompt as Administrator
- WSL Integration: For optimal performance, run Ceramic within WSL2:
wsl cd /path/to/your/project ceramic daemon --network inmemory - Docker Connection: Verify Docker Desktop is active with WSL2 integration enabled
- Homebrew Issues: Update Homebrew before installing Ceramic:
brew update brew upgrade
- Permission Issues: Check folder permissions:
chmod -R 755 ./server
This project is licensed under the MIT License.
Author:
Joshua Head (https://www.joshuahead.com)
Repository:
https://github.com/jhead12/web3db-fileconnector/orbisdb
Bugs:
https://github.com/jhead12/web3db-fileconnector/orbisdb/issues