Building 21st century open-source infrastructure
Learn more »

Introduction · Tech Stack · Contributing · Discord

Opensox AI is a platform designed to help developers quickly discover open-source projects based on their specific criteria so that you can start contributing in seconds, not in days.

• Next.js – framework
• TypeScript – language
• Tailwind – CSS
• Prisma – ORM
• NextAuth.js – auth
• Turborepo – monorepo
• Vercel – deployments
• Railway – deployments

We love our contributors! Here’s how you can contribute:

• Open an issue if you believe you’ve encountered a bug.
• EB95 Make a pull request to add new features, improve quality of life, or fix bugs.

Opensox AI's stack consists of the following elements:

• A backend API built with tRPC and Express.js
• A frontend written in Next.js and TypeScript
• A PostgreSQL database
• A Redis database (in process)
• What's for AI? Coming very soon…

Opensox needs TypeScript and Node.js >= 18 installations.

Create environment files for both the backend and the frontend before running the apps.

Create a file at apps/api/.env with:

# Required
DATABASE_URL="postgresql://USER:PASSWORD@localhost:5432/opensox?schema=public"
JWT_SECRET="replace-with-a-strong-random-secret"

# Optional (good defaults shown)
PORT=8080
CORS_ORIGINS=http://localhost:3000
NODE_ENV=development

# Optional but needed for GitHub queries to work
# Generate a classic token with "public_repo" access at https://github.com/settings/tokens
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Notes:

• DATABASE_URL: point this to your PostgreSQL instance. Example for local Postgres is shown above.
• JWT_SECRET: generate one, e.g. openssl rand -base64 32 or node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".
• CORS_ORIGINS: comma-separated list of allowed origins. Keep http://localhost:3000 for local web app.

Create a file at apps/web/.env.local with:

# Required
NEXT_PUBLIC_API_URL="http://localhost:8080"
GOOGLE_CLIENT_ID="your-google-oauth-client-id"
GOOGLE_CLIENT_SECRET="your-google-oauth-client-secret"
NEXTAUTH_SECRET="replace-with-a-strong-random-secret"

# Recommended for production (optional for local dev)
NEXTAUTH_URL="http://localhost:3000"

# Optional analytics (PostHog)
# If you don't use PostHog, you can omit these
# NEXT_PUBLIC_POSTHOG_KEY="phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# NEXT_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com" # or https://app.posthog.com

Notes:

• NEXT_PUBLIC_API_URL must point to the backend base URL; the frontend calls ${NEXT_PUBLIC_API_URL}/api/... for auth and data.
• Google OAuth: create credentials in Google Cloud Console (OAuth 2.0 Client ID), add Authorized redirect URIs for NextAuth (e.g., http://localhost:3000/api/auth/callback/google).
• NEXTAUTH_SECRET: generate one just like JWT_SECRET. It’s used by NextAuth; it can be different from the backend secret.

After creating these files, restart your dev servers so changes take effect.

Run these steps once your DATABASE_URL is set:

cd apps/api

# Generate Prisma client (optional if already generated)
npx prisma generate

# Apply migrations locally
npx prisma migrate dev --name init

Seed initial data so features relying on it work correctly:

• Option A (recommended): use Prisma Studio to insert the initial row

  npx prisma studio

  Then open the QueryCount model and create a row with:

  • id: 1
  • total_queries: 0

• Option B: insert directly via SQL (replace the connection string as needed)

  psql "postgresql://USER:PASSWORD@localhost:5432/opensox" \
    -c "INSERT INTO \"QueryCount\" (id, total_queries) VALUES (1, 0) ON CONFLICT (id) DO NOTHING;"

1. Fork and clone the opensox repo

git clone https://github.com/[your-github-username]/opensox.git

2. cd into opensox/apps/web and install dependencies

pnpm install

Now run the dev server:

pnpm run dev

Congrats! Your frontend is running on localhost:3000.

3. cd into opensox/apps/api and install dependencies

npm install

Now run the server:

pnpm run dev

Voila! Your API server is running on localhost:4000.

Now you can access your app at http://localhost:3000.

Alternatively, you can run the API server using Docker. A Dockerfile is provided in the root directory.

• Docker installed on your machine

1. Make sure you have your .env file set up in apps/api/.env (see Backend environment variables section above)

2. From the root directory, build the Docker image:

docker build -t opensox-api .

3. Run the container with your environment variables:

docker run -p 4000:4000 \
  --env-file apps/api/.env \
  opensox-api

Or if you prefer to pass environment variables individually:

docker run -p 4000:4000 \
  -e DATABASE_URL="postgresql://USER:PASSWORD@host.docker.internal:5432/opensox?schema=public" \
  -e JWT_SECRET="your-secret" \
  -e PORT=4000 \
  opensox-api

Note: When using Docker, if your database is running on your host machine (not in a container), use host.docker.internal instead of localhost in your DATABASE_URL.

Your API server will be available at http://localhost:4000.

For a complete setup with PostgreSQL, you can create a docker-compose.yml file:

version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: opensox
      POSTGRES_PASSWORD: opensox
      POSTGRES_DB: opensox
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  api:
    build: .
    ports:
      - "4000:4000"
    environment:
      DATABASE_URL: postgresql://opensox:opensox@postgres:5432/opensox?schema=public
      JWT_SECRET: your-secret-key
      PORT: 4000
      NODE_ENV: production
    depends_on:
      - postgres

volumes:
  postgres_data:

Then run:

docker-compose up -d

AGPL 3.0