Getting Started — AEGIS ExamLab Docs

System Requirements

Runtime

✓ Node.js 18.x or higher
✓ npm 9.x or pnpm 8.x
✓ TypeScript 5.x (dev dependency)

Database

✓ MongoDB 6.x+ (local or Atlas)
○ Firebase (optional — for apphosting)

Clone & Install

1

Clone the repository and move into the project directory.

git clone https://github.com/ERROR-SIDDH/AEGIS.git
cd AEGIS

2

Install all project dependencies. This includes Next.js, all Radix UI components, MongoDB driver, Genkit AI, and Zod.

npm install

Environment Variables

Copy the example file and populate it with your credentials. AEGIS will fail to start if MONGODB_URI is not defined.

cp .env.example .env

Variable	Required	Description
`MONGODB_URI`	Yes	Full MongoDB connection string. Accepts both local and Atlas URIs.
`GEMINI_API_KEY`	Yes	Google Gemini API key for AI-assisted question classification via Genkit.
`DEFAULT_ADMIN_USERNAME`	Optional	Username for the seeded default admin. Defaults to `admin`.
`DEFAULT_ADMIN_PASSWORD`	Optional	Password for the seeded default admin. Change this immediately in production.

Database Setup

AEGIS uses MongoDB and creates all collections lazily on first write. However, you must be aware of a critical index requirement for the pcs collection:

Important: Sparse MAC Address Index

The pcs collection requires a sparse unique index on the macAddress field. A non-sparse unique index will cause PC approval to fail whenever macAddress is null (which is the default in browser environments). Run the fix script if encountering this issue.

          // database-fix.js — Run in a MongoDB shell to resolve the index
            conflict

          db.pcs.dropIndex("macAddress_1");

          db.pcs.createIndex(

            { "macAddress": 1 },

            { unique: true, sparse: true, name: "macAddress_unique_sparse" }

          );

Seeding Default Admin Credentials

On a fresh deployment, the admins collection is empty. No one can log into the dashboard. The seed-db.js script creates the first superadmin account from your .env credentials. It is idempotent — running it multiple times is safe.

node scripts/seed-db.js

Expected output: Success: Default administrative user 'admin' has been created.

After seeding, navigate to http://localhost:9002/login and log in with the credentials defined in your .env file.

Running the Application

npm run dev
# App starts at
            http://localhost:9002

The development server is configured to run on port 9002 (defined in package.json as "dev": "next dev -p 9002"). This avoids conflicts with other common services on ports 3000 or 8000.

Route	Description	Auth Required
/	PC Registration portal	None
/login	Admin login page	None
/dashboard/*	All admin panels	Admin cookie
/exam/:examId	Student exam interface	localStorage token

Docker Deployment

A multi-stage Dockerfile is included. Stage 1 (builder) compiles the Next.js application. Stage 2 (runner) is a minimal production image.

          # Build the Docker image

          docker build -t aegis-examlab .

          # Run, mapping container port 3000 to host port 4000

          docker run -p 4000:3000 --env-file .env aegis-examlab

Note: The Dockerfile copies your .env file directly into the image at build time (COPY --from=builder /app/.env ./.env). For secure production deployments, use Docker secrets or inject environment variables at runtime using the --env-file flag or a secrets manager.

Troubleshooting

Error: Please define the MONGODB_URI environment variable

Your .env file is missing or MONGODB_URI is not set. Ensure you ran cp .env.example .env and populated the value. Restart the dev server after editing .env.

PC approval fails with a MongoDB duplicate key error

The pcs collection has a non-sparse unique index on macAddress. Run the database-fix.js script to recreate it as a sparse index. See the Database Setup section.

Cannot log into /dashboard — cookie not being set

Ensure the admins collection is not empty. Run node scripts/seed-db.js to create a default admin, or manually insert a document with username, password, and role: 'admin'.

Installation & Setup