OrbisDB connects you to the GraphQL system that manages your Web3 data using the Ceramic network.

• Available Scripts
  • Script Descriptions
• Development Workflow
  • Local Development
  • Building and Deployment
  • Maintenance Tasks
• Getting Started
  • Setting Up Ceramic DB
  • Configuration Process
  • Database Connection
  • Configuration Files
  • Dependency Installation
• Docker-Based Development
  • Using Docker Scripts
  • Windows Docker Commands
• Prerequisites
  • Windows-Specific Requirements
• Build and Run Instructions
• Ceramic Installation
  • MacOS
  • Windows
• Exposed Ports
• Starting the Server
  • Expected Output
  • Connecting to Ceramic
• Connecting to the Ceramic Network
  • Troubleshooting Windows Installation

{
  "build": "cd client && next build",
  "start": "cross-env NODE_ENV=production node index.js",
  "dev": "node index.js",
  "clean": "rm -rf client/.next",
  "clear-port": ".bin/clear_ports.sh",
  "publish:npm": "npm publish --access public",
  "publish:docker": "docker buildx build --platform linux/arm64,linux/amd64 -t orbisdb-fileconnector:latest . && docker push orbisdb-fileconnector:latest",
  "lint": "eslint .",
  "clean:all": "rm -rf client/.next client/node_modules",
  "publish": "npm run build && npm run docker:restart",
  "test": "echo \"Error: no test specified\" && exit 1",
  "dev:docker": "npm run docker:start && node index.js",
  "dev:debug": "cross-env LOG_LEVEL=debug node index.js",
  "dev:watch": "nodemon --ignore '*.json' index.js",
  "format": "prettier . --write",
  "docker:start": "docker start orbisdb-pgvector || docker run -d --name orbisdb-pgvector -e POSTGRES_PASSWORD=postgres -p 5432:5431 pgvector/pgvector:0.7.4-pg16",
  "docker:stop": "docker stop orbisdb-pgvector",
  "docker:restart": "npm run docker:stop && npm run docker:start || npm run docker:start",
  "docker:remove": "docker rm orbisdb-pgvector || docker stop orbisdb-pgvector && docker rm orbisdb-pgvector",
  "docker:status": "docker ps"
}

• build: Builds the Next.js client application
• start: Runs the application in production mode
• dev: Starts the development server
• clean: Removes the Next.js build cache
• clear-port: Executes a script to free up ports used by the application
• publish:npm: Publishes the package to npm with public access
• publish:docker: Builds and publishes a multi-architecture Docker image
• lint: Runs ESLint to check code quality
• clean:all: Removes both the Next.js build cache and node_modules
• publish: Builds the application and restarts the Docker container
• test: Placeholder for running tests (currently not implemented)
• dev:docker: Starts the Docker container and runs the development server
• dev:debug: Runs the development server with debug logging enabled
• dev:watch: Runs the development server with file watching (auto-restart)
• format: Formats code using Prettier
• docker:start: Starts the pgvector Docker container or creates it if it doesn't exist
• docker:stop: Stops the pgvector Docker container
• docker:restart: Restarts the pgvector Docker container
• docker:remove: Removes the pgvector Docker container
• docker:status: Shows the status of Docker containers

cd server
./wheel

This command executes the wheel script which is a utility for setting up and managing a Ceramic-based application.

When running the setup script, you'll be prompted to confirm several configuration settings:

1. Project Name: Confirm or change the default project name (default: "ceramic-app")
2. Project Directory: Confirm if the directory exists or create it
3. Network: Choose whether to use the InMemory network for testing
4. Ceramic Integration: Confirm if Ceramic should be included in the setup
5. ComposeDB Integration: Confirm if ComposeDB should be included
6. Sample Application: Choose whether to include a ComposeDB sample application
7. DID Secret Key Path: Provide a path to save the DID secret key
8. Configuration Review: Final confirmation of all settings

The script verifies the connection to the SQLite database:

Verifying database connection using connection string sqlite:///path/to/project/ceramic-app/ceramic-indexing/ceramic.db

Configuration files are saved to your project directory:

Saving config to /path/to/project/ceramic-app/ceramic.json
Saving daemon file to /path/to/project/ceramic-app/daemon_config.json

The script installs required dependencies:

+ Installing dependencies for @ceramicnetwork/cli

After installation, you can run Ceramic with:

./ceramic daemon --config /path/to/project/ceramic-app/daemon_config.json

Run this from the project directory (e.g., /path/to/project/ceramic-app).

cd server
./wheel

This command executes the wheel script which is a utility for setting up and managing a Ceramic-based application.

When running the setup script, you'll be prompted to confirm several configuration settings:

1. Project Name: Confirm or change the default project name (default: "ceramic-app")
2. Project Directory: Confirm if the directory exists or create it
3. Network: Choose whether to use the InMemory network for testing
4. Ceramic Integration: Confirm if Ceramic should be included in the setup
5. ComposeDB Integration: Confirm if ComposeDB should be included
6. Sample Application: Choose whether to include a ComposeDB sample application
7. DID Secret Key Path: Provide a path to save the DID secret key
8. Configuration Review: Final confirmation of all settings

The script verifies the connection to the SQLite database:

Verifying database connection using connection string sqlite:///path/to/project/ceramic-app/ceramic-indexing/ceramic.db

Configuration files are saved to your project directory:

Saving config to /path/to/project/ceramic-app/ceramic.json
Saving daemon file to /path/to/project/ceramic-app/daemon_config.json

The script installs required dependencies:

+ Installing dependencies for @ceramicnetwork/cli

After installation, you can run Ceramic with:

./ceramic daemon --config /path/to/project/ceramic-app/daemon_config.json

Run this from the project directory (e.g., /path/to/project/ceramic-app).

The OrbisDB project uses Next.js for the client application and supports various development workflows.

1. Standard development:

   npm run dev

   This starts the server in development mode.

2. Development with auto-restart:

   npm run dev:watch

   This uses nodemon to watch for file changes and restart the server automatically.

3. Debug mode:

   npm run dev:debug

   This enables detailed logging for troubleshooting.

1. Build the client application:

   npm run build

2. Start in production mode:

   npm run start

3. Publish to npm:

   npm run publish:npm

4. Build and publish Docker image:

   npm run publish:docker

   This builds a multi-architecture Docker image (arm64 and amd64) and pushes it to your Docker repository.

1. Clean Next.js build cache:

   npm run clean

2. Clean all build artifacts and dependencies:

   npm run clean:all

3. Format code:

   npm run format

4. Lint code:

   npm run lint

5. Clear ports:

   npm run clear-port

   This runs a script to free up ports that might be in use.

Set the following in a .env file or export in your shell:

• POSTGRES_USER: Database username (default: user)
• POSTGRES_PASSWORD: Database password (default: password)

Ensure you have installed:

• Docker version 20.10 or later
• Docker Compose version 1.29 or later
• Node.js version 18.0.0 or later

• Windows 10/11 with WSL2 (Windows Subsystem for Linux) enabled
• Docker Desktop for Windows with WSL2 backend
• Git Bash or PowerShell for running commands

1. Clone the repository and navigate to the project directory:

   Linux/MacOS:

   git clone https://github.com/your-repo/project.git
   cd project

   Windows (PowerShell):

   git clone https://github.com/your-repo/project.git
   cd project

   Windows (Command Prompt):

   git clone https://github.com/your-repo/project.git
   cd project

brew install ceramicnetwork/tap/ceramic-one
ceramic-one daemon --network in-memory

1. Install Node.js and npm: Download and install from Node.js official website (version 18.0.0 or later)

2. Install Ceramic CLI:

   npm install -g @ceramicnetwork/cli

3. Generate a DID (Decentralized Identifier):

   ceramic did:generate

4. Start the Ceramic daemon:

   ceramic daemon --network inmemory

   For persistent storage, configure a state store:

   ceramic daemon --network mainnet --state-store=<path-to-state-store>

• Application: 7008
• Database: Not externally exposed

Navigate to the project directory and run:

cd docker/core/
docker-compose up -d

This starts the services in detached mode.

[INFO] Starting ceramic-one daemon...
[INFO] Ceramic Node started: /path/to/project/ceramic/node-12700
[INFO] Listening for incoming connections on port 3001...

Access the Ceramic container shell:

cd docker/core/
docker-compose exec -it ceramic-one /bin/bash

1. Install ceramic-cli: Follow the installation instructions

2. Generate a Ceramic ID:

   Linux/MacOS:

   ceramic id

   Windows:

   ceramic id

3. Initialize OrbisDB:

   Linux/MacOS:

   pnpm run init --ceramic-id <ceramic-id>

   Windows:

   pnpm run init --ceramic-id <ceramic-id>

   If you don't have pnpm installed, you can install it first:

   npm install -g pnpm

4. Start the Application: Follow the server startup instructions above

1. Path Issues: If you encounter "command not found" errors, ensure the installation directory is in your PATH environment variable.

2. Permission Errors: Run PowerShell or Command Prompt as Administrator if you encounter permission issues.

3. WSL Integration: For optimal performance on Windows, consider running Ceramic within WSL2:

   wsl
   cd /path/to/project
   ceramic daemon --network inmemory

4. Docker Connection Issues: Ensure Docker Desktop is running with WSL2 integration enabled in settings.