Skip to main content

​
Developer Installation Guide

This guide will walk you through setting up DeltaHacks Portal for local development. Whether you’re contributing to the project or customizing it for your own hackathon, follow these steps to get a complete development environment running.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version 18 or higherDownload from nodejs.org

pnpm

Package ManagerInstall with: npm install -g pnpm

Git

Version ControlDownload from git-scm.com

Docker

Container RuntimeRequired for local database
For macOS developers, we recommend OrbStack as a fast, lightweight alternative to Docker Desktop. It’s optimized for macOS and provides better performance. Alternatively, you can use:

​
Development Tools

We recommend using VSCode with these extensions:

​
Installation Steps

1

Clone the Repository

Clone the DeltaHacks Portal repository to your local machine:
git clone https://github.com/deltahacks/portal.git
cd portal
This will create a portal directory with the complete source code.
2

Install Dependencies

Install all required npm packages using pnpm:
pnpm install
This will install all dependencies defined in package.json, including:
  • Next.js and React
  • Prisma and database tools
  • tRPC for API routes
  • NextAuth.js for authentication
  • TailwindCSS for styling
  • And many other packages
The project uses pnpm as the primary package manager. While npm will work, pnpm is recommended for consistency with the development team.
3

Set Up Environment Variables

Create your local environment configuration:
cp .env.example .env
Edit the .env file and configure the required variables. At minimum, you’ll need:
.env
# Database (will be set up in next step)
DATABASE_URL="postgresql://root@localhost:26257/defaultdb?sslmode=disable"

# NextAuth - Generate a random secret
NEXTAUTH_SECRET="your-secret-here"  # Use: openssl rand -base64 32
NEXTAUTH_URL="http://localhost:3000"
NEXT_PUBLIC_URL="http://localhost:3000"

# OAuth Providers (optional for local development)
# Configure at least one provider for authentication
DISCORD_CLIENT_ID="your-discord-client-id"
DISCORD_CLIENT_SECRET="your-discord-client-secret"
Important: Complete this step before proceeding to database setup. The setup-db.sh script requires environment variables from .env to work properly.

​
Generating Your NextAuth Secret

openssl rand -base64 32
Copy the output and paste it as your NEXTAUTH_SECRET value.

​
OAuth Provider Setup (Optional)

For local development, you can set up OAuth providers:
  1. Go to Discord Developer Portal
  2. Create a new application
  3. Navigate to OAuth2 settings
  4. Add redirect URL: http://localhost:3000/api/auth/callback/discord
  5. Copy Client ID and Client Secret to your .env
  1. Go to Google Cloud Console
  2. Create a new project
  3. Enable Google+ API
  4. Create OAuth 2.0 credentials
  5. Add authorized redirect URI: http://localhost:3000/api/auth/callback/google
  6. Copy Client ID and Client Secret to your .env
  1. Go to GitHub Developer Settings
  2. Create a new OAuth App
  3. Set Homepage URL: http://localhost:3000
  4. Set Authorization callback URL: http://localhost:3000/api/auth/callback/github
  5. Copy Client ID and Client Secret to your .env
4

Set Up Local Database

Run the automated database setup script:
./setup-db.sh
This script will:
  • Check for Docker or Podman installation
  • Verify that port 26257 is available
  • Create a CockroachDB container named deltahacks-cockroach
  • Start the database on port 26257
  • Provide a web UI on port 8080

​
What the script does

The setup-db.sh script automates the setup of a local CockroachDB instance:
# Checks for Docker/Podman
# Creates container if it doesn't exist
# Starts existing container if already created
docker run -d \
  --name deltahacks-cockroach \
  -p 26257:26257 \
  -p 8080:8080 \
  cockroachdb/cockroach:latest start-single-node --insecure
The database runs in insecure mode for local development. Never use this configuration in production!

​
Accessing the Database UI

Once running, you can access the CockroachDB admin UI at:

​
Troubleshooting

Port already in use:
# Check what's using port 26257
lsof -i :26257

# Stop the process or change the port in your DATABASE_URL
Docker not running:
# Start Docker Desktop or OrbStack
# Then run the script again
./setup-db.sh
5

Initialize Database Schema

Generate the Prisma Client and push the schema to your database:
# Generate Prisma Client with TypeScript types
pnpm db:generate

# Push schema to database (creates tables)
pnpm db:push
This will:
  1. Generate the Prisma Client based on prisma/schema.prisma
  2. Create all database tables and relationships
  3. Set up indexes and constraints

​
Alternative: Using Migrations

For production or when working with existing databases, use migrations instead:
# Create a new migration
pnpm prisma migrate dev --name your_migration_name

# Deploy migrations to production
pnpm db:migrate
Use Prisma Studio to visually inspect and edit your database:
pnpm db:studio  # Opens at http://localhost:5555
6

Start Development Server

Launch the Next.js development server:
pnpm dev
The development server will:
  • Install any missing dependencies
  • Generate Prisma Client (if not already generated)
  • Start Next.js in development mode
  • Enable hot module replacement
  • Watch for file changes
Your application will be available at:
The pnpm dev command runs: pnpm i && prisma generate && next devThis ensures dependencies and Prisma Client are always up to date.
7

Verify Installation

Open your browser and navigate to http://localhost:3000You should see the DeltaHacks Portal homepage. Try:
  1. Sign in with one of your configured OAuth providers
  2. Create your first user (will have HACKER role by default)
  3. Explore the interface and features

​
First-Time Setup

To give yourself admin privileges:
  1. Sign in and note your user ID
  2. Open Prisma Studio: 
    pnpm db:studio
  3. Navigate to the User model
  4. Find your user and edit the role field
  5. Add ADMIN to the roles array
  6. Save changes and refresh your browser

​
Development Commands

Here’s a comprehensive list of available commands:

​
Server Commands

pnpm dev              # Start development server with hot reload
pnpm build            # Build optimized production bundle
pnpm start            # Start production server (run build first)

​
Database Commands

pnpm db:generate      # Generate Prisma Client
pnpm db:push          # Push schema changes to database
pnpm db:migrate       # Deploy migrations
pnpm db:studio        # Open Prisma Studio (database GUI)

​
Code Quality Commands

pnpm lint             # Run ESLint to check for issues
pnpm format           # Format code with Prettier
pnpm format:check     # Check if code is formatted correctly

​
Project Structure

Understanding the codebase structure will help you navigate and contribute effectively: 
portal/
├── prisma/
│   ├── schema.prisma          # Database schema definition
│   └── migrations/            # Database migrations
├── public/                    # Static assets
├── src/
│   ├── app/                   # Next.js App Router
│   │   └── api/               # API routes (REST endpoints)
│   ├── assets/                # Static assets (passes, images)
│   ├── components/            # Reusable React components
│   ├── data/                  # Static data and constants
│   ├── env/                   # Environment variable schemas
│   ├── pages/                 # Next.js pages (legacy structure)
│   ├── schemas/               # Zod validation schemas
│   ├── server/                # Server-side code
│   │   ├── db/                # Database client
│   │   └── trpc/              # tRPC configuration
│   │       └── router/        # tRPC API routers
│   ├── styles/                # Global styles and CSS
│   ├── types/                 # TypeScript type definitions
│   └── utils/                 # Utility functions
├── .env.example               # Environment variables template
├── setup-db.sh                # Database setup script
├── package.json               # Dependencies and scripts
└── tsconfig.json              # TypeScript configuration

​
Key Directories

Contains all tRPC API routers that define the backend logic:
  • application.ts - Hacker application management
  • auth.ts - Authentication logic
  • admin.ts - Admin operations
  • judging.ts - Judging system
  • equipment.ts - Equipment tracking
  • And more…
Reusable React components organized by feature:
  • Form components
  • Layout components
  • Dashboard components
  • QR code scanners
  • Admin tools
Zod schemas for input validation:
  • Ensures type safety
  • Validates user input
  • Shared between client and server
Database-related files:
  • schema.prisma - Database models and relationships
  • migrations/ - Version-controlled schema changes

​
Next Steps

Contributing Guide

Learn how to contribute to the project

Architecture Overview

Understand the system design and data flow

API Reference

Explore available tRPC endpoints

Database Schema

Detailed documentation of data models

​
Troubleshooting

​
Common Issues

Another application is using port 3000. Either:Option 1: Stop the other application
lsof -ti:3000 | xargs kill -9
Option 2: Use a different port
PORT=3001 pnpm dev
Ensure your database container is running:
# Check if container is running
docker ps | grep deltahacks-cockroach

# Start the container if stopped
docker start deltahacks-cockroach

# Or run the setup script again
./setup-db.sh
If you see “@prisma/client did not initialize yet”, run:
pnpm db:generate
  1. Verify your OAuth credentials in .env
  2. Check that redirect URLs match in provider settings
  3. Ensure NEXTAUTH_URL matches your local URL
  4. Clear browser cookies and try again
# Clean install dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Regenerate Prisma Client
pnpm db:generate

​
Development Best Practices

Before making changes, read through the Contributing Guide for:
  • Code style guidelines
  • Development workflows
  • Pull request process
  • Best practices for React, TypeScript, and state management

​
Quick Tips

  • Type Safety: Always use TypeScript, avoid any types
  • Database Changes: Create migrations for all schema changes
  • Code Formatting: Run pnpm format before committing
  • Testing: Test your changes thoroughly with different user roles
  • Commits: Use conventional commit messages

​
Getting Help

Need assistance?
When asking for help, please demonstrate what you’ve already tried. See the Technical VP Support Policy in the contributing guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us