Repository files navigation

Before you begin, ensure you have the following installed on your system:

• Node.js: Version 22.13.1 is recommended. Usingnvm is advised:

  nvm install 22.13.1nvm use 22.13.1

• pnpm: Install globally using npm:

  npm install -g pnpm

• PostgreSQL Client (psql): Required for importing the database dump. Install the command-line tools from theofficial PostgreSQL website.
• MySQL Client (mysql): Required for importing the legacy authorization dump before migration. Install the command-line tools from theofficial MySQL website.
• Docker: The latest version of Docker Desktop or Docker Engine is needed to run the databases and Redis. Download from theofficial Docker website.

This service uses two separate PostgreSQL databases running in Docker:

• common_oltp_db: Contains existing tables and data (from an imported dump).
• authorization_db: New database for tables migrated from MySQL (managed by Prisma Migrate).

Additionally, a temporary MySQL database is used during the legacy data migration process.

Follow these steps to set up and run the application locally:

1. Install Dependencies:Clone the repository and install the necessary Node.js packages using pnpm.

   pnpm install

   (This command also runspnpm run prisma:generate automatically via thepostinstall script to generate Prisma clients for both databases.)

2. Configure Environment:Copy the example environment file and update the necessary variables.

   cp .env.sample .env

   • Crucially, updateAUTH_SECRET to a strong, unique secret key for local HS256 JWT generation. Do not use the default placeholder.
   • Crucially, updateAUTH0_CLIENT_SECRET as provided in the forum.
   • Verify database connection URLs (COMMON_OLTP_DB_URL,AUTHORIZATION_DB_URL), database names (COMMON_OLTP_DB_NAME,AUTHORIZATION_DB_NAME), ports (DB_PORT,MYSQL_PORT), and credentials (DB_USERNAME,DB_PASSWORD). The defaults in.env.sample usually work with the provideddocker-compose.yml.
   • EnsureJWT_VALIDATION_MODE is set toHS256 for local development (this is the default in.env.sample).

3. Start Services:Launch the PostgreSQL databases, MySQL database (for migration), and Redis using Docker Compose.

   docker compose up -d

   • Wait a few moments for the databases to initialize completely.

4. Import Common OLTP Data:Import thecommon_oltp database dump into thecommon_oltp_db PostgreSQL database.

   # Replace ~/Downloads/common_oltp with the actual path to your dump file. (Download it from forum, and extract from zip) - Use password from DB_PASSWORD of .env file# Ensure DB_HOST, DB_PORT, DB_USERNAME, and COMMON_OLTP_DB_NAME match your .env values.psql -h${DB_HOST:-127.0.0.1} -p${DB_PORT:-5432} -U${DB_USERNAME:-topcoderuser} \     -d${COMMON_OLTP_DB_NAME:-common_oltp_db} \     -f~/Downloads/common_oltp -v ON_ERROR_STOP=0

5. Initialize Authorization Database Schema:Apply the Prisma migrations to create the necessary tables in theauthorization_db PostgreSQL database.

   pnpm prisma migrate dev --name init  --schema prisma/authorization/schema.prisma

6. Migrate Legacy Authorization Data:This step involves importing data from a legacy MySQL dump into the temporary MySQL container and then migrating it to the newauthorization_db PostgreSQL database.

   • Import MySQL Dump:

     # Replace ~/Downloads/Authorization with the actual path to your MySQL dump file (Download it from forum, and extract from zip)# Ensure MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, and MYSQL_DATABASE match your .env values.  Use the password from .env when asked.mysql -h${MYSQL_HOST:-127.0.0.1} -P${MYSQL_PORT:-3306} -u${MYSQL_USER:-root} -p${MYSQL_PASSWORD:-mysql-user-root-password}${MYSQL_DATABASE:-authorization_db}<~/Downloads/Authorization

   • Run Migration Script:

     pnpm run db:migrate-legacy

7. Run Unit Tests:You can run the unit tests to verify the setup.

   pnpm runtesttc-identity-service@1.0.0test> jestPASS  src/api/role/role.service.spec.ts (5.636 s)PASS  src/api/user/user.service.spec.ts (5.657 s)PASS  src/api/role/role.controller.spec.ts (5.674 s)PASS  src/api/user/user.controller.spec.ts (6.036 s)Test Suites: 4 passed, 4 totalTests:       83 passed, 83 totalSnapshots:   0 totalTime:        6.715 sRan alltest suites.

8. Generate an Admin Token:For interacting with the API locally (e.g., via Postman), generate a test JWT using the provided script. This requiresJWT_VALIDATION_MODE=HS256 and a definedAUTH_SECRET in your.env file.

   # Generate a default admin token (expires in 8 hours)node scripts/generate-local-token.js

   Copy the generated token (the long string starting witheyJ...). See the "Generating Local HS256 Tokens" section below for more options.

9. Update Postman Environment fileYou'll need to update the Authorization Bearer token in thedoc/postman_environment.json with the one generated in the previous step.

10. Start the Application:Run the NestJS application in development mode (with hot-reloading).

    pnpm run start:dev

    The API should now be available, athttp://localhost:3000.

11. Run Postman/Newman Tests:After starting the application, you can run the individual Postman collection tests using Newman. Ensure your Postman environment (doc/postman_environment.json) is configured, especially thebaseUrl andaccessToken.

    • Roles API Tests:

      pnpm run test:postman:roles

    • Users API Tests:
    • Importdoc/postman_environment andusers.postman_collection.json to your postman app. These tests cannot be fully automated because it requires getting tokens from emails.
    • Follow the videousers-endpoint.mp4 to test all endpoints provided with a sample email.

    Use below command to generate a user token

    node scripts/generate-local-token.js"100000157""Topcoder User""user100000147handle""user100000147@example.com""""1h"

Prisma is configured to manage both databases separately.

1. For theauthorization_db Database:

   • This database schema is managed by Prisma Migrate.
   • To create the database and apply migrations during development:

     pnpm run prisma:migrate:authorization

   • To apply migrations in production-like environments:

     pnpm run prisma:deploy:authorization

   • Generate the client if needed:

     pnpm run prisma:generate:authorization

2. For thecommon_oltp_db Database:

   • This database uses an imported dump. If the dump changes, or for initial setup verification, you can update the Prisma schema to match the database:

     pnpm run prisma:pull:common_oltp

   • After pulling, regenerate the client if needed (thoughpnpm install should handle it):

     pnpm run prisma:generate:common_oltp

3. Prisma Studio (for browsing data):

   • Open Studio forcommon_oltp_db (runs on port 5555):

     pnpm run prisma:studio:common_oltp

   • Open Studio forauthorization_db (runs on port 5556):

     pnpm run prisma:studio:authorization

   • Open both studios concurrently:

     pnpm run prisma:studio

Thepnpm run db:migrate-legacy script handles the migration from a temporary MySQL database (populated from a dump) to theauthorization_db PostgreSQL database.

1. Ensure MySQL Container is Running: Thedocker-compose up -d command should start a MySQL service (checkdocker-compose.yml).
2. Import the MySQL Dump: Use themysql command-line tool to import your legacyAuthorization dump into the running MySQL container. See Step 6 in the "Local Development Setup" for the command. Ensure connection details match your.env configuration (MYSQL_HOST,MYSQL_PORT, etc.).
3. Run the Migration Script: Execute the script to transfer and transform the data.

   pnpm run db:migrate-legacy

The following table summarizes the environment variables used by the application. Copy.env.sample to.env and customize these values as needed.

The application supports two JWT validation modes, configured viaJWT_VALIDATION_MODE:

1. Local Development (HS256 Mode - Recommended)

Use this mode for local testing, allowing you to generate tokens easily without needing an external IdP.

• SetJWT_VALIDATION_MODE=HS256
• SetAUTH_SECRET to a strong, unique secret key.Do not use the default placeholder.
• Optionally, setJWT_ISSUER_URL andJWT_AUDIENCE to match the values you intend to put in your generated tokens (defaults are provided).
• Comment out or removeJWT_JWKS_URI.

2. Production/Staging (RS256 Mode - Default)

Use this mode when deploying, validating tokens against a real identity provider (like Auth0).

• SetJWT_VALIDATION_MODE=RS256 or omit the variable.
• SetJWT_ISSUER_URL to your IdP's issuer URL.
• SetJWT_AUDIENCE to your API's audience identifier registered with the IdP.
• SetJWT_JWKS_URI to the JWKS endpoint of your IdP.
• Comment out or removeAUTH_SECRET.

# development$ pnpm run start# watch mode$ pnpm run start:dev# production mode$ pnpm run start:prod

# unit tests$ pnpm runtest# e2e tests$ pnpm run test:e2e# test coverage$ pnpm run test:cov

# Install dependenciespnpm install# Run database migrations (if applicable)# Example: pnpm prisma migrate dev --schema=./prisma/authorization.prisma# Example: pnpm prisma migrate dev --schema=./prisma/common_oltp.prisma# Start the application in development mode (with hot-reloading)pnpm run start:dev

When running inHS256 mode locally, you can generate valid JWTs using the provided script:

1. Ensure.env is configured:

   • JWT_VALIDATION_MODE=HS256
   • AUTH_SECRET is set to your chosen secret key.
   • JWT_ISSUER_URL,JWT_AUDIENCE are set (optional, defaults used if not).

2. Run the script:

   node scripts/generate-local-token.js [userId] [roles] [handle] [email] [expiresIn]

   • Arguments are optional and default to values similar to theADMIN_TOKEN.
   • roles: Comma-separated list (no spaces around commas), e.g.,administrator,Topcoder\ User
   • expiresIn: Time string like1h,8h,1d.

3. Examples:

   # Generate default admin token (expires in 8h)node scripts/generate-local-token.js# Generate token for a regular user (ID 12345, handle 'testuser')node scripts/generate-local-token.js 12345"Topcoder User" testuser test@example.com# Generate admin token expiring in 1 hournode scripts/generate-local-token.js 8547899 administrator"TonyJ""tjefths+fix@topcoder.com" 1h

4. Use the Output: Copy the generated token and use it in theAuthorization: Bearer <token> header of your API requests (e.g., in Postman).

# unit testspnpm runtest# Run Postman collection via Newman (requires app running)pnpm run test:postman# e2e tests (currently placeholder/not fully configured)# pnpm run test:e2e# test coveragepnpm run test:cov