Skip to main content

​
Installation

This guide will walk you through setting up Orquestra for local development or deploying it to Cloudflare’s edge network.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 18+ or Bun 1.0+
  • Cloudflare account (free tier works)
  • GitHub account (for OAuth authentication)
  • Git installed on your machine

​
Quick start

The fastest way to get started is using the automated setup script:
1

Clone the repository

git clone https://github.com/berkayoztunc/orquestra.git
cd orquestra
2

Run the quick start script

./scripts/quick-start.sh
This script will:
  • Install all dependencies
  • Set up environment variables
  • Create the local database
  • Start the development servers
3

Access the application

​
Manual setup

If you prefer to set up Orquestra manually:
1

Install dependencies

npm run install:all
2

Configure environment variables

Create a .env.local file in the root directory:
cp .env.example .env.local
Then edit .env.local with your credentials:
# Cloudflare
CLOUDFLARE_API_TOKEN=your_api_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id_here

# GitHub OAuth
GITHUB_OAUTH_ID=your_github_oauth_id
GITHUB_OAUTH_SECRET=your_github_oauth_secret

# JWT Secret (generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
JWT_SECRET=your_jwt_secret_here

# Solana RPC (optional, defaults to public endpoint)
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
  1. Go to Cloudflare Dashboard
  2. Navigate to My Profile → API Tokens
  3. Click Create Token
  4. Use the Edit Cloudflare Workers template
  5. Copy the API token
  6. Your Account ID is shown in the dashboard URL or under Account Settings
  1. Go to GitHub Developer Settings
  2. Click New OAuth App
  3. Fill in the details:
    • Application name: Orquestra (or your choice)
    • Homepage URL: http://localhost:5173 (for development)
    • Authorization callback URL: http://localhost:8787/auth/github/callback
  4. Click Register application
  5. Copy the Client ID
  6. Generate a Client Secret and copy it
Run this command to generate a secure JWT secret:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Copy the output and use it as your JWT_SECRET.
3

Set up the database

Run database migrations to create the necessary tables:
npm run db:migrate:dev
This creates the following tables:
  • users - User accounts from GitHub OAuth
  • projects - IDL projects
  • idl_versions - IDL version history
  • api_keys - API authentication keys
  • project_socials - Project social links
  • known_addresses - Labeled Solana addresses
4

Start the development servers

You can start both servers together or separately:
npm run dev
This starts:
5

Verify the setup

Open your browser and navigate to:You should see the Orquestra dashboard and a healthy API response.

​
Development workflow

​
Common commands

npm run dev                      # Start all dev servers
npm run dev:frontend             # Start frontend only
npm run dev:worker               # Start worker only

​
Project structure

Orquestra is organized as a monorepo: 
orquestra/
├── packages/
│   ├── frontend/          # React SPA
│   │   ├── src/
│   │   │   ├── pages/     # Route pages
│   │   │   ├── components/ # UI components
│   │   │   └── store/     # Zustand state
│   │   └── package.json
│   │
│   ├── worker/            # Hono API
│   │   ├── src/
│   │   │   ├── routes/    # API routes
│   │   │   ├── services/  # Business logic
│   │   │   └── middleware/ # Auth, caching
│   │   └── package.json
│   │
│   ├── cli/               # CLI tools
│   │   └── src/
│   │       └── commands/  # CLI commands
│   │
│   └── shared/            # Shared code
│       └── src/
│           └── types.ts   # TypeScript types
│
├── migrations/            # Database schema
└── scripts/               # Setup scripts
See Project Structure for a detailed breakdown of the codebase.

​
Deploying to production

Once you’re ready to deploy Orquestra to production:
1

Build all packages

npm run build
2

Deploy to Cloudflare

npm run deploy
This deploys:
  • Worker API to Cloudflare Workers
  • Frontend to Cloudflare Pages
3

Run production migrations

npm run db:migrate
4

Set production secrets

wrangler secret put GITHUB_OAUTH_SECRET
wrangler secret put JWT_SECRET
For detailed deployment instructions, see the Deployment Guide.

​
Troubleshooting

If you see an error about ports 5173 or 8787 being in use:
# Find the process using the port
lsof -i :5173
lsof -i :8787

# Kill the process
kill -9 <PID>
If dependencies fail to install:
# Clear cache and reinstall
npm run clean
npm run install:all
If migrations fail:
# Reset the database and try again
npm run db:reset
npm run db:migrate:dev
If you see TypeScript errors:
# Run type checking
npm run type-check

# Fix linting issues
npm run lint:fix

​
Next steps

Quickstart guide

Learn how to use Orquestra with a practical example

Core concepts

Understand how Orquestra works under the hood

Deployment

Deploy Orquestra to production

API reference

Explore the REST API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us