Octogriffin Logo

Development Setup

To contribute to Octogriffin, you need to set up the project locally. Follow this guide to get up and running in minutes.

Prerequisites

Node.js 22+

Docker (for PostgreSQL)

1

Expose Localhost

GitHub Webhooks require a public URL to reach your machine. Since localhost is not accessible from the internet, we use a tunnel.

Set up Ngrok Tunnel

Required to receive webhook events locally.

View Guide
Alternatives
While we recommend Ngrok for stability, you are free to use alternatives like Smee or Localtunnel.
2

Create GitHub App

Go to Developer Settings > New GitHub App and fill in the details below.

1. General

GitHub App NameMy GitHub App
Homepage URLhttp://localhost:3000
Callback URL
http://localhost:3000/api/auth/callback/github
Callback URL (2)
<YOUR-NGROK-URL>/api/auth/callback/github
Setup URLhttp://localhost:3000/dashboard/settings
Webhook URL<YOUR-NGROK-URL>/api/v1/webhook
Webhook SecretLeave blank (we configure this later)

2. Permissions

Set the following Repository permissions to Read-only.

CategoryAccess
Actions Read-only
Contents Read-only
Discussions Read-only
Issues Read-only
Metadata (Mandatory)Read-only
Packages Read-only
Pull Requests Read-only

3. Subscribe to events

Next, scroll down to the Subscribe to events section and check the following boxes:

Meta
Commit comment
Create
Discussion
Discussion comment
Delete
Fork
Gollum
Issue comment
Issues
Label
Milestone
Pull request
Pull request review
Pull request review comment
Pull request review thread
Push
Registry package
Release
Repository
Star
Workflow dispatch
Workflow job
Workflow run
Sub Issues
Important
After clicking "Create GitHub App", locate the Client ID and generate a new Client Secret. You will need them for step 5.
3

Fork & Clone

If you plan to contribute, fork the repository first.

git clone https://github.com/YOUR_USERNAME/octogriffin.git
cd octogriffin
4

Install Dependencies

Install the project dependencies.

yarn install
5

Configure Environment

Copy Configuration Files

cp .env.example .env
cp apps/web/.env.local.example apps/web/.env.local
The root .env is only used by Docker for the database.

Fill apps/web/.env.local

Use the generator below to create secure keys. Copy the block into your local env file, then fill in the GitHub credentials from Step 2.

apps/web/.env.local
# Generated Security Keys
GITHUB_WEBHOOK_SECRET=""
NEXTAUTH_SECRET=""
ENCRYPTION_KEY=""
HEALTH_CHECK_SECRET=""

# Paste your GitHub App Credentials here
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""

# Paste your GitHub App URL here
NEXT_PUBLIC_GITHUB_APP_URL="https://github.com/apps/my-github-app"
6

Start Database

Start the PostgreSQL container from the project root.

docker compose up -d
If you changed the DB credentials in the root .env, remember to update DB_URL in apps/web/.env.local.
7

Initialize Database

Run the following commands to generate the client, apply migrations, and seed demo data.

# Switch to the web app directory
cd apps/web

# Generate Prisma Client
prisma generate

# Push schema to DB
prisma migrate deploy

# Run Seeder
prisma db seed
8

Launch Server

Everything is ready! Start the development server:

yarn dev

Open http://localhost:3000 to see your app.

Something went wrong?
Open an Issue on GitHub →