Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chamals3n4/OpenATS/llms.txt

Use this file to discover all available pages before exploring further.

Get your OpenATS development environment set up and create your first job posting in under 10 minutes.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (version 18 or higher) - Download here
  • Git - Download here
  • PostgreSQL database - We recommend Neon (free tier, no local install needed)
  • Code editor - VS Code recommended
Verify your installation: 
node --version
git --version

​
Installation

1

Clone the repository

Clone the OpenATS repository to your local machine:
git clone https://github.com/chamals3n4/OpenATS.git
cd OpenATS
Verify you’re in the OpenATS directory by running ls - you should see api and web folders
2

Install pnpm

OpenATS uses pnpm as its package manager. Install it globally:
npm install -g pnpm
Verify installation with pnpm --version
3

Install dependencies

Install dependencies for both the frontend and backend:Frontend (web):
cd web
pnpm install
Backend (api):
cd ../api
pnpm install
Wait for all dependencies to install - this may take a few minutes
4

Configure environment variables

Set up environment variables for both applications.Frontend environment:
cd web
cp .env.example .env
Edit web/.env and configure your authentication settings (WSO2 Asgardeo).Backend environment:
cd ../api
cp .env.example .env
Edit api/.env with your configuration:
.env
# Database (Required)
DATABASE_URL=postgresql://user:password@host:port/database

# Cloudflare R2 Storage (Optional - for file uploads)
R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=your_access_key_id
R2_SECRET_ACCESS_KEY=your_secret_access_key
R2_BUCKET_NAME=your_bucket_name
R2_PUBLIC_URL=https://your-public-url.com

# Email (Optional - for notifications)
RESEND_API_KEY=re_your_api_key
RESEND_FROM_EMAIL=noreply@yourdomain.com
Database URL Format:
  • For Neon: postgresql://user:password@host/database?sslmode=require
  • For local PostgreSQL: postgresql://localhost:5432/openats
Ensure your DATABASE_URL is correctly configured - this is required for the next steps
5

Set up the database

Run database migrations and seed data from the api directory:Generate and run migrations:
pnpm drizzle-kit generate
pnpm drizzle-kit migrate
Seed the database:
pnpm tsx src/db/seed.ts
This creates all necessary tables and inserts default hiring pipeline stages.
Verify migrations completed successfully - you should see confirmation messages
6

Start the development servers

Run both the frontend and backend servers in separate terminal windows.Terminal 1 - Backend API:
cd api
pnpm dev
The API will start on http://localhost:5000Terminal 2 - Frontend Web:
cd web
pnpm dev
The web app will start on http://localhost:3000
Open http://localhost:3000 in your browser - you should see the OpenATS interface

​
Creating Your First Job Posting

Now that OpenATS is running, let’s create your first job posting.
1

Access the application

Navigate to http://localhost:3000 in your browser and sign in with your configured authentication provider.
2

Navigate to Jobs

From the dashboard, click on the “Jobs” section in the navigation menu.
3

Create a new job

Click the “Create Job” or “New Job Posting” button.
4

Fill in job details

Enter the following information:
  • Job Title (e.g., “Senior Software Engineer”)
  • Department (e.g., “Engineering”)
  • Location (e.g., “Remote” or “San Francisco, CA”)
  • Employment Type (Full-time, Part-time, Contract)
  • Job Description (Responsibilities, requirements, etc.)
  • Salary Range (Optional)
Use the rich text editor to format your job description with bullet points and sections
5

Configure hiring pipeline

The default hiring pipeline stages are automatically applied:
  • Applied
  • Screening
  • Interview
  • Offer
  • Hired
You can customize these stages later in the settings.
6

Publish the job

Click “Save” or “Publish” to create your job posting. It will now be visible to applicants and your hiring team.
Your first job posting is live! You can now start receiving applications.

​
Verification Steps

Ensure everything is working correctly:
Visit http://localhost:5000 - you should see an API response or Swagger documentation.
Visit http://localhost:3000 - you should see the OpenATS login page or dashboard.
Check your terminal logs for the API server - there should be no database connection errors.
Navigate to the Jobs section and verify your newly created job posting is displayed.

​
Troubleshooting

Problem: Error connecting to PostgreSQL database.Solutions:
  • Verify your DATABASE_URL in api/.env is correct
  • Ensure your database server is running
  • For Neon, check that you’ve added ?sslmode=require to the connection string
  • Test the connection using a PostgreSQL client
Problem: Error: EADDRINUSE: address already in use :::3000 or :::5000Solutions:
  • Kill the process using the port: 
    # On macOS/Linux
lsof -ti:3000 | xargs kill -9
lsof -ti:5000 | xargs kill -9

# On Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F
  • Or change the port in your configuration
Problem: Error: Cannot find module 'X'Solutions:
  • Delete node_modules and reinstall: 
    rm -rf node_modules
pnpm install
  • Ensure you’re using the correct Node.js version (18+)
  • Clear pnpm cache: pnpm store prune
Problem: Database migration fails or tables not created.Solutions:
  • Ensure your database is empty or drop existing tables
  • Run migrations in order: 
    pnpm drizzle-kit generate
pnpm drizzle-kit migrate
  • Check database permissions - your user needs CREATE TABLE privileges
Problem: Cannot sign in or authentication redirects fail.Solutions:
  • Verify WSO2 Asgardeo configuration in web/.env
  • Check that callback URLs are correctly configured in your Asgardeo application
  • Ensure your client ID and client secret are correct
  • Clear browser cookies and try again
Problem: Cannot upload resumes or attachments.Solutions:
  • Verify R2 configuration in api/.env (if using Cloudflare R2)
  • Check that your R2 bucket exists and is accessible
  • Verify access key credentials are correct
  • Ensure your bucket has the correct CORS policy

​
Next Steps

Architecture

Understand the technical stack and system design

Creating Jobs

Learn how to create and manage job postings

API Reference

Explore the OpenATS API endpoints

Development Setup

Detailed development environment setup

​
Additional Resources

  • Tech Stack: Next.js, Express.js, PostgreSQL, Drizzle ORM, TypeScript
  • Authentication: WSO2 Asgardeo
  • Storage: Cloudflare R2 (optional)
  • Email: Resend (optional)
Join our community for support, feature requests, and to contribute to OpenATS development!

Build docs developers (and LLMs) love

Get started for freeTalk to us