Pomelo

A simple contest platform with a Next.js frontend (client), an Express backend (server), and Judge0 for code execution.

---

Development Setup (Local)

1. Copy environment files for each area:

   • Root: ./.env from ./.env.example
   • Server: ./server/.env from ./server/.env.example
   • Client: ./client/.env from ./client/.env.example

   Windows example:

   copy .env.example .env
   cd server
   copy .env.example .env
   cd client
   copy .env.example .env

   macOS / Linux example:

   cp .env.example .env
   cp server/.env.example server/.env
   cp client/.env.example client/.env

2. Edit the three .env files and set the values described below.

3. Start Judge0 + Mongo (from repository root):

   docker compose --project-name pomelo --env-file .env -f docker/app/docker-compose.dev.yaml -f docker/judge0/docker-compose.yaml --project-directory . up mongo judge0-server judge0-workers seed -d

4. Install dependencies and run the app (from repository root):

   pnpm install
   pnpm dev

---

Environment variables

• AUTH_SECRET

  • Where: root, server, client
  • What: secret string used for signing tokens or server-side auth
  • Suggested: a long random value (e.g., generated by openssl rand -hex 32)

• PORT

  • Where: root, server
  • What: port the backend listens on
  • Default: 8080

• MONGODB_URI

  • Where: root, server, client
  • What: MongoDB connection string
  • Local example: mongodb://localhost:27017/pomelo
  • Docker example: mongodb://mongo:27017/pomelo

• JUDGE0_URL

  • Where: root, server
  • What: URL where the Judge0 service is reachable
  • Local example: http://localhost:2358
  • Docker example: http://judge0-server:2358

• NEXT_PUBLIC_BACKEND_URL

  • Where: root, client
  • What: frontend environment variable used to call the backend
  • Example: http://localhost:8080 (or the host/IP of the running server)
  • Note: must be prefixed with NEXT_PUBLIC_ so Next.js exposes it to the browser

• POSTGRES_PASSWORD

  • Where: root
  • What: password used by Judge0's PostgreSQL service in the Docker-compose
  • Suggested: a secure password when running Judge0 with Docker

• REDIS_PASSWORD

  • Where: root
  • What: password used by Judge0's Redis service in Docker
  • Suggested: a secure password when running Judge0 with Docker

---

Docker setup (Quick)

• Edit the root ./.env (copy from ./.env.example) and set any required passwords and URLs.

Windows:

scripts/dev.bat

Linux / macOS:

scripts/dev

This script uses the docker/docker-compose stacks and will boot Mongo + Judge0 and the app in containers.

---

Stopping / Cleanup

• Bring containers down:

docker compose --project-name pomelo down

• To remove volumes and data (permanent):

docker compose --project-name pomelo down -v

---

Troubleshooting

• If the frontend cannot reach the backend, check NEXT_PUBLIC_BACKEND_URL and that the server is running on PORT.
• If Judge0 jobs fail, verify JUDGE0_URL and that the Judge0 containers are healthy.
• If Mongo connection fails, verify MONGODB_URI and that Mongo container is running.