Talent-Acquisition-Platform

Setup Guide

This guide covers setting up the development environment, managing environment configurations, integrating PostgreSQL and Piston code execution engines via Docker, and securing our Docusaurus documentation site on Cloudflare.

🛠 Prerequisites

Ensure you have the following installed on your host system:

🐋 Option A: Docker Compose Development Stack

The development stack runs inside Docker Compose, configuring hot-reloading for the backend, running background arq tasks, and providing a sandboxed Piston runtime environment.

1. Clone Repositories

You need both the main platform repository and the Piston code execution fork:

# Clone the main recruitment platform repository
git clone https://github.com/p99softadmin/Talent-Acquisition-Platform.git
cd Talent-Acquisition-Platform

# Clone the piston execution engine repo as a sibling directory
cd ..
git clone https://github.com/p99softadmin/piston.git
cd Talent-Acquisition-Platform

2. Configure Environment Variables

Copy the example environment configuration to create your local environment:

cp backend/.env.example backend/.env

3. Understanding docker-compose.dev.yml

The dev docker-compose stack spins up the following services:

4. PostgreSQL in Docker Compose

Local PostgreSQL 16 is enabled by default in docker-compose.dev.yml (postgres service, postgres_data volume, and backend/worker depends_on). To use an external database instead, comment out those Compose entries and point DATABASE_URL in backend/.env at your host.

5. Start the Stack

Start all services in detached mode:

docker compose -f docker-compose.dev.yml up -d

Note: The first launch will bootstrap Piston and download runtimes (Node, Python, Go). This might take 3–5 minutes.

Verify runtimes are loaded successfully:

curl http://localhost:2000/api/v2/runtimes

💻 Option B: Local Host Development

If you prefer running components directly on your host machine (outside Docker) for debugging:

1. Backend Setup

cd backend

# Create virtualenv
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Bootstrap resume parser NLP models and download stopwords
python scripts/bootstrap_resume_parser.py
python -m nltk.downloader stopwords

# Setup configuration
cp .env.example .env
# Edit .env and customize DATABASE_URL, JWT_SECRET_KEY, ANTHROPIC_API_KEY

# Run migrations
alembic upgrade head

# Start FastAPI dev server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API Documentation will be interactive at: http://localhost:8000/docs

2. Frontend Setup

cd frontend

# Install package dependencies
npm install

# Setup local environment configurations
cp .env.example .env.local

# Run developer server
npm run dev

Frontend application will be running at: http://localhost:5173

🔑 Configuration & Environment Secrets

The platform reads settings from configuration files (.env).

What you get from .env.prod

📦 Object Storage Setup (MinIO & AWS S3)

The platform natively supports both local MinIO (for offline/local dev) and AWS S3 (for staging/production).

What you must configure yourself (Ask Colleagues for credentials)

For local development, you must create a .env file containing secrets. Do NOT commit this file. Obtain the current development API keys and testing tokens from your teammates or configure them manually:

Optional Live Camera Monitoring (defaults work for local Docker Compose):

Optional Safe Exam Browser lockdown (Desktop integrity mode / hardware_fingerprint):

📖 Docusaurus Documentation Setup & Deployment

We use Docusaurus to generate and maintain developer manuals, code explanations, and documentation files.

1. Local Docusaurus Setup

If you are initializing or running the Docusaurus documentation portal:

# Initialize a new Docusaurus project (if not already in the repository)
npx -y create-docusaurus@latest docs-site classic

# Start local server
cd docs-site
npm run start

The documentation portal is served locally at http://localhost:3000.

2. Cloudflare Pages Deployment

To host the Docusaurus site on Cloudflare Pages:

  1. Connect Cloudflare to your Git repository.
  2. Configure build settings in the Cloudflare Pages dashboard:
    • Framework preset: Docusaurus v2
    • Build command: npm run build
    • Build output directory: build
  3. Trigger the initial build deployment.

3. Restricting Documentation Access via Cloudflare Access (SSO)

To secure private engineering documentation so that only P99soft employees can view it:

  1. Go to the Cloudflare Zero Trust Dashboard (dash.teams.cloudflare.com).
  2. Navigate to Access -> Applications and click Add an Application.
  3. Choose Self-Hosted (or Pages if direct integration is enabled).
  4. Configure Application Settings:
    • Application Name: Talent Acquisition Platform Documentation
    • Session Duration: e.g., 24 Hours
    • Application Domain: Enter your pages URL (e.g. docs.p99soft.com or tap-docs.pages.dev).
  5. Configure Identity Providers:
    • Enable identity providers such as Google Workspace, Azure AD, Okta, or One-Time Pin (OTP) so that users can verify their identity.
  6. Create Access Policies:
    • Policy Name: Restrict to P99soft Staff
    • Action: Allow
    • Under Configure Rules, add an Include rule:
      • Selector: Emails ending in
      • Value: p99soft.com
  7. Click Save Application. Now, Cloudflare Access intercepts all requests to your Docusaurus deployment. Visitors must authenticate through SSO using their @p99soft.com email address; all other domains are securely denied access.

✍️ Commit Message Guidelines & Git Hooks (Husky + Commitlint)

To maintain a clean and automated collaborative environment, we enforce the Conventional Commits specification for all commit messages. This ensures that changes can be tracked, version tags can be automatically resolved, and CHANGELOGs can be built programmatically via semantic-release.

1. Commit Message Format

Commit messages must follow the format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Where <type> must be one of:

Example of a valid commit message:

git commit -m "feat(auth): integrate google sso endpoints"

2. How Git Hooks Enforce Rules

We use Husky combined with Commitlint to automatically run checks before any commit is processed:

3. Setup Hooks on Local Environment

If you cloned the repository fresh, run:

# Installs hook packages and configures git hooks automatically (via the prepare script)
npm install

If you need to manually re-link or troubleshoot the Git hooks:

npx husky

💾 Database Migrations (Alembic)

Always keep the database schema in sync with your models during development:

# Run all pending migrations
alembic upgrade head

# Autogenerate a new migration file after modifying SQLAlchemy models
alembic revision --autogenerate -m "describe_your_changes"

# Rollback the last migration
alembic downgrade -1

# View migration chain history
alembic history

🚦 Troubleshooting

Backend database connection fails

Verify PostgreSQL is healthy and accepting connections. If using Docker, inspect container health:

docker compose -f docker-compose.dev.yml logs postgres

Ensure your DATABASE_URL in .env matches the configuration of the database service.

Piston compilation / runtimes list is empty

If Piston API returns an empty list, the runtime bootstrap is likely still installing packages:

docker compose -f docker-compose.dev.yml logs -f piston_runtime_bootstrap

Check that no other system processes are running on port 2000.

Unauthorized/Expired Tokens in Local Frontend

Clear local storage in your browser console if authentication issues persist after database resets:

localStorage.clear();