Installation

This guide will help you set up OpenAthlete for local development.

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js v22.14.0 (use .nvmrc for version management)
• pnpm v9.x
• PostgreSQL (for the database)
• Git

Step 1: Clone the Repository

git clone https://github.com/openathleteorg/openathlete.git
cd openathlete

Step 2: Install Dependencies

pnpm install

Step 3: Set Up Environment Variables

Frontend Configuration

Copy the example environment file:

cp apps/web/.env.example apps/web/.env

Update the .env file with your configuration. At minimum, you'll need:

VITE_API_URL=http://localhost:3000

Backend Configuration

Copy the example environment file:

cp apps/api/.env.example apps/api/.env

Update the .env file with your database connection and other settings:

DATABASE_URL="postgresql://user:password@localhost:5432/openathlete"
JWT_SECRET="your-secret-key"

Step 4: Build Shared Packages

pnpm shared build

Step 5: Set Up the Database

Run database migrations:

pnpm database run db:deploy

Or for development with migrations:

pnpm database run db:migrate dev

Step 6: Start Development Servers

Start both frontend and backend:

pnpm dev

This will start:

• Frontend at http://localhost:5173
• Backend API at http://localhost:3000

Verify Installation

1. Open your browser to http://localhost:5173
2. You should see the OpenAthlete login page
3. Create an account or log in

Troubleshooting

Database Connection Issues

Make sure PostgreSQL is running:

# macOS
brew services start postgresql

# Linux
sudo systemctl start postgresql

Port Already in Use

If ports 3000 or 5173 are already in use, you can change them:

• Frontend: Update vite.config.ts in apps/web
• Backend: Update the port in apps/api/src/main.ts

Type Errors

If you encounter TypeScript errors, make sure shared packages are built:

pnpm shared build

Next Steps

• First Steps - Create your first workout
• Development Setup - Set up for contributing
• Architecture Overview - Understand the codebase