Skip to main content
GatePass is a decentralized event ticketing platform that leverages blockchain technology (NFTs) to provide secure, verifiable, and transferable tickets.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:
  • Node.js (v18 or higher)
  • npm or pnpm package manager
  • Git for cloning the repository
1

Clone the Repository

First, clone the GatePass repository to your local machine:
git clone https://github.com/yourusername/gatepass.git
cd gatepass
2

Install Dependencies

Install all required dependencies for both frontend and backend:
npm install
This will install dependencies including:
  • Frontend: React, Vite, Tailwind CSS, Shadcn UI, Framer Motion
  • Backend: Express, Prisma, Ethers.js, Passport.js
  • Smart Contracts: Solidity, Foundry (Forge)
3

Setup Environment Variables

Copy the environment example files and configure them with your own values:
# Copy root environment file
cp .env.example .env

# Copy server environment file (if exists)
cp src/packages/server/.env.example src/packages/server/.env
Root .env file:
# Payment gateways (required for initiating fiat checkouts)
VITE_PAYSTACK_PUBLIC_KEY=pk_test_your_paystack_key
VITE_FLUTTERWAVE_PUBLIC_KEY=FLWPUBK_TEST-your_flutterwave_key

# Blockchain configuration
VITE_CHAIN_ID=137
VITE_RPC_URL=https://polygon-rpc.com

# Optional analytics
VITE_ANALYTICS_ID=your_analytics_id
Paystack and Flutterwave keys are required for fiat payments from the browser. For M-Pesa integration, additional server-side configuration is needed.
4

Database Setup

Initialize the database with Prisma and seed it with demo data:
cd src/packages/server
npx prisma migrate dev
This command will:
  • Create the database schema (Users, Events, Orders, Tickets, CheckIns, etc.)
  • Apply all migrations
  • Generate the Prisma Client
To populate your database with sample events for testing:
npx tsx src/scripts/seedEvents.ts
This creates demo events with various ticket tiers and categories.
5

Run the Application

Start both the backend API server and the frontend development server:Terminal 1 - Backend API:
cd src/packages/server
npm run dev
The backend server will start on http://localhost:8000Terminal 2 - Frontend (new terminal):
# From project root
npm run dev
The frontend will start on http://localhost:5173
# Backend
cd src/packages/server && npm run dev

# Frontend (new terminal)
npm run dev
6

Access the Application

Open your browser and navigate to:

Frontend App

Main application interface

Backend API

API server endpoint

Health Check

Server health status

API Documentation

Interactive API docs

​
Create Your First Event

Once the application is running, you can create your first event:
1

Sign Up or Login

Navigate to the login page and create an account using:
  • Email/Password
  • Google OAuth
  • Twitter OAuth
  • Web3 Wallet (MetaMask)
2

Access Organizer Dashboard

From the main navigation, click on “Organizer Dashboard” to access event management features.
3

Create New Event

Fill in the event creation form with:
  • Event title and description
  • Venue and location details
  • Event date and sale period
  • Ticket pricing and supply
  • Category and tags
  • Event image (optional)
{
  "title": "NFT Conference 2026",
  "venue": "Convention Center",
  "eventDate": "2026-06-15T09:00:00Z",
  "totalSupply": 500,
  "ticketPrice": 0.05,
  "currency": "ETH"
}
4

Configure Ticket Tiers

Set up multiple ticket tiers:
  • VIP: Premium access with perks
  • Regular: Standard admission
  • Early Bird: Discounted pricing for early buyers
5

Deploy Smart Contract

Once your event is configured, deploy the NFT ticket smart contract to Polygon:
  • Review gas estimates
  • Confirm deployment transaction
  • Contract address will be saved to your event
6

Publish Event

Make your event public and start selling tickets!

​
Running Tests

To verify your setup is working correctly: 
cd src/packages/server
npm test

{
  "test": "jest --passWithNoTests",
  "test:watch": "jest --watch",
  "test:e2e": "jest --config jest.e2e.config.js"
}

​
Troubleshooting

If you encounter database errors, try resetting the database:
cd src/packages/server
npx prisma migrate reset
This will drop the database, recreate it, and run all migrations.
If ports 8000 (backend) or 5173 (frontend) are already in use:Check for processes:
lsof -ti:8000  # Backend
lsof -ti:5173  # Frontend
Kill the process:
kill -9 $(lsof -ti:8000)
Or change the port in your configuration files.
If npm install fails:
# Remove existing installations
rm -rf node_modules package-lock.json

# Clear npm cache
npm cache clean --force

# Reinstall
npm install
If you get Prisma Client errors:
cd src/packages/database
npx prisma generate

​
Next Steps

Architecture

Understand the system architecture

API Reference

Explore the API endpoints

Smart Contracts

Learn about NFT ticketing contracts

Development Guide

Contribute to GatePass
Make sure to use test API keys (starting with pk_test_ or FLWPUBK_TEST) during development. Never commit production keys to version control.

Build docs developers (and LLMs) love

Get started for freeTalk to us