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.
• 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.

Copy the example environment file and update it with your values:

cd apps/api cp .env.example .env

Then edit apps/api/.env and fill in the required values:

# 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. You can copy from .env.example (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