Skip to main content

​
Prerequisites

Before starting, ensure you have the following installed:
  • Node.js 24 or later
  • pnpm 10.18.3 or later (package manager)
  • Docker and Docker Compose (for local PostgreSQL)
  • PostgreSQL 17 (can be run via Docker)
Vitaes uses pnpm as the package manager. The project is configured with packageManager: "[email protected]" in package.json.

​
Installation

1

Clone the repository

Clone the Vitaes repository to your local machine:
git clone <repository-url>
cd vitaes
2

Install dependencies

Install all dependencies using pnpm:
pnpm install
This will install dependencies for all packages in the monorepo, including:
  • Web application (React + TanStack Router)
  • Server application (Hono + oRPC)
  • Shared packages (auth, api, db)
3

Set up environment variables

Create environment files for both the server and web applications.Server environment (apps/server/.env):
DATABASE_URL=postgresql://postgres:password@localhost:5432/vitaes
BETTER_AUTH_SECRET=your-secret-key-here
BETTER_AUTH_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3001

# OAuth Providers (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# MinIO/S3 Storage (optional)
MINIO_ENDPOINT=
MINIO_PUBLIC_ENDPOINT=
MINIO_ACCESS_KEY=
MINIO_SECRET_KEY=
MINIO_BUCKET=
Web environment (apps/web/.env):
VITE_SERVER_URL=http://localhost:3000
VITE_APP_URL=http://localhost:3001
VITE_OPENPANEL_CLIENT_ID=
VITE_OPENPANEL_API_URL=
Never commit .env files to version control. Use .env.example files as templates.
4

Start PostgreSQL database

Use Docker Compose to start a local PostgreSQL instance:
pnpm db:start
This runs the Docker Compose configuration from packages/db/docker-compose.yml:
services:
  postgres:
    image: postgres:17
    container_name: vitaes-postgres
    environment:
      POSTGRES_DB: vitaes
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"
The database will be available at postgresql://postgres:password@localhost:5432/vitaes
5

Push database schema

Apply the database schema using Drizzle:
pnpm db:push
This creates all necessary tables including:
  • Authentication tables (user, session, account, verification)
  • Application tables (resume)
6

Start development servers

Start all development servers:
pnpm dev
This starts both the web and server applications in parallel using Turborepo.Alternatively, start them individually:
pnpm dev:server

​
Verify Installation

After completing the setup:
  1. Web Application: Open http://localhost:3001
  2. API Server: Available at http://localhost:3000
  3. Database Studio: Run pnpm db:studio to open Drizzle Studio

​
Available Development Scripts

The following scripts are available in the root package.json:
ScriptDescription
pnpm devStart all applications in development mode
pnpm buildBuild all applications for production
pnpm check-typesCheck TypeScript types across all packages
pnpm dev:webStart only the web application
pnpm dev:serverStart only the server application
pnpm db:pushPush schema changes to database
pnpm db:studioOpen Drizzle Studio (database UI)
pnpm db:generateGenerate database migrations
pnpm db:migrateRun database migrations
pnpm db:startStart PostgreSQL with Docker Compose
pnpm db:stopStop PostgreSQL container
pnpm db:downStop and remove PostgreSQL container

​
Troubleshooting

​
Database Connection Issues

If you encounter database connection errors:
  1. Verify PostgreSQL is running: docker ps
  2. Check the DATABASE_URL in apps/server/.env
  3. Ensure the database exists: pnpm db:start

​
Port Already in Use

If ports 3000 or 3001 are already in use:
  1. Stop the conflicting process
  2. Or modify the ports in:
    • apps/web/package.json (web port in dev script)
    • apps/server/src/index.ts (server port configuration)

​
Type Errors

Run type checking across all packages: 
pnpm check-types

​
Next Steps

Now that your development environment is set up:

Build docs developers (and LLMs) love

Get started for freeTalk to us