Aluna

Aluna is an open-source recruiter dashboard for managing jobs, candidates, and applications. It can integrate with any applicant tracking systems (ATS) supported by Merge.dev, and includes AI-powered candidate research.

Prerequisites

• Node.js 22 (recommend nvm)
• pnpm 10
• PostgreSQL 16 (or use the included Docker setup)

Quick Start

1. Clone and install dependencies

   git clone https://github.com/ssalka/aluna.git
   cd aluna
   pnpm install

2. Start PostgreSQL (skip if you already have a Postgres instance)

   docker compose up -d

3. Configure environment

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

   Edit packages/server/.env and fill in the required values (see Environment Variables).

4. Run database migrations and seed

   pnpm db migrate
   pnpm db seed

5. Start the development servers

   pnpm dev

6. Open localhost:5173 in your browser.

Environment Variables

Server (packages/server/.env)

Variable	Required	Description
PORT	Yes	Server port (default: 3001)
NODE_ENV	Yes	development, staging, or production
POSTGRES_CONNECTION_STR	Yes	PostgreSQL connection string
WORKOS_CLIENT_ID	Yes	WorkOS client ID
WORKOS_API_KEY	Yes	WorkOS API key
WORKOS_COOKIE_PASSWORD	Yes	32+ char secret for session cookies
CLIENT_URL	No	Override client URL (default: http://localhost:5173)
SERVER_URL	No	Override server URL (default: http://localhost:3001)
AUTHKIT_URL	No	WorkOS AuthKit URL
MARKETING_SITE_URL	No	Marketing site URL (default: http://localhost:3000)
MERGE_API_KEY	No	Merge.dev API key for ATS integration
GOOGLE_GENERATIVE_AI_API_KEY	No	Google Gemini API key for deep research
GH_TOKEN	No	GitHub token for candidate profile analysis
POSTHOG_API_KEY	No	PostHog API key for analytics

Client (packages/client/.env)

Variable	Required	Description
VITE_AUTHKIT_URL	No	WorkOS AuthKit URL
VITE_SERVER_URL	No	Override server URL
VITE_POSTHOG_API_KEY	No	PostHog API key

Marketing Site (packages/marketing-site/.env.local)

Variable	Required	Description
NEXT_PUBLIC_SERVER_URL	No	Override server URL
NEXT_PUBLIC_POSTHOG_KEY	No	PostHog API key

Database Setup

Option A: Docker (recommended for local development)

docker compose up -d

This starts PostgreSQL on localhost:5432 with the connection string:

postgresql://aluna:aluna_dev_password@localhost:5432/aluna

Option B: Neon (recommended for production)

1. Create a database at neon.tech
2. Copy the connection string to POSTGRES_CONNECTION_STR in your .env

Migrations & Seeding

pnpm db migrate    # Run pending migrations
pnpm db seed       # Insert sample data
pnpm db status     # Check migration status
pnpm db rollback   # Rollback last migration
pnpm db create     # Create a new migration file
pnpm db codegen    # Regenerate TypeScript types from DB schema

Service Setup Guides

WorkOS (Authentication) — Required

1. Create an account at workos.com
2. Go to API Keys in the dashboard
3. Copy Client ID and API Key to your .env
4. Set WORKOS_COOKIE_PASSWORD to a random 32+ character string
5. Configure your AuthKit redirect URI to http://localhost:5173

Merge.dev (ATS Integration) — Required

1. Create an account at merge.dev
2. Go to API Keys and copy your key to MERGE_API_KEY
3. ATS routes will only be available when this is configured

Google Generative AI (Deep Research) — Required

1. Get an API key from Google AI Studio
2. Set GOOGLE_GENERATIVE_AI_API_KEY in your .env

PostHog (Analytics) — Optional

1. Create an account at posthog.com
2. Copy your project API key to POSTHOG_API_KEY (server) and/or VITE_POSTHOG_API_KEY (client)

Development

Run all packages in development mode:

pnpm dev

Or run packages individually:

pnpm client dev          # React/Vite app on localhost:5173
pnpm server_ dev         # Express/tRPC server on localhost:3001
pnpm marketing-site dev  # Next.js marketing site on localhost:3000

Build

pnpm build    # Build all packages

Linting & Type Checking

pnpm checks      # Run format:check, lint, typecheck in parallel
pnpm lint         # ESLint only
pnpm format       # Prettier auto-fix
pnpm typecheck    # TypeScript type checking

Testing

Unit Tests (Vitest)

pnpm test              # Run all tests
pnpm client test       # Client tests only
pnpm server_ test      # Server tests only
pnpm test my-suite     # Run a specific test

E2E Tests (Playwright)

pnpm exec playwright install --with-deps  # Install browsers (first time)
pnpm client test:e2e                      # Run E2E tests
pnpm test:e2e:ui                          # Interactive Playwright UI

Architecture

This is a pnpm monorepo with the following packages:

Package	Description
client	React 19 + Vite frontend (recruiter dashboard)
server	Express + tRPC backend API
ui	Shared component library (Radix UI + Tailwind v4)
common	Shared types, config, and utilities
marketing-site	Next.js marketing website
scripts	Build and utility scripts

Tech Stack

Backend

• Express + tRPC — TypeScript-first API
• Kysely — Type-safe SQL query builder
• PostgreSQL — Database
• AI SDK — AI toolkit for deep research
• WorkOS — Authentication & SSO
• CASL — User permissions

Frontend

• React 19 + Vite — UI & bundler
• TanStack Router — Type-safe routing
• TanStack Query — Server state management
• Zustand — Client state management
• shadcn/ui + Tailwind CSS — Styling

Testing

• Vitest — Unit testing
• Playwright — E2E testing
• React Testing Library — Component testing

Deployment

Aluna is designed to deploy on Render with a Neon PostgreSQL database.

1. Push your repo to GitHub
2. Create a Neon database and note the connection string
3. Create Render services for server and client (static site)
4. Set the environment variables on each service
5. The server runs migrations automatically in development; for production, run pnpm db migrate before deploying

License

MIT