Self-Hosting

OpenAthlete is designed to be self-hosted, giving you full control over your data and privacy.

Deployment Options

Docker Compose (Recommended)

The easiest way to deploy OpenAthlete is using Docker Compose.

1. Clone the repository:

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

2. Configure environment variables:

cp apps/api/.env.example .env

3. Update the .env files with your production settings

4. Start the services:

docker-compose up -d

Manual Deployment

Backend (NestJS)

1. Build the application:

cd apps/api
pnpm install
pnpm build

2. Set up environment variables in .env

3. Run database migrations:

pnpm database run db:deploy

4. Start the server:

pnpm start:prod

Frontend (React + Vite)

1. Build the application:

cd apps/web
pnpm install
pnpm build

2. Serve the built files using a web server (nginx, Apache, etc.)

Example nginx configuration:

server {
    listen 80;
    server_name your-domain.com;

    root /path/to/apps/web/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Environment Variables

Backend Required Variables

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

Frontend Required Variables

VITE_API_URL="https://api.your-domain.com"

Database Setup

1. Create a PostgreSQL database
2. Update DATABASE_URL in your backend .env
3. Run migrations:

pnpm database run db:deploy

SSL/TLS

For production, always use HTTPS. You can use:

• Let's Encrypt with Certbot
• Cloudflare for SSL termination
• Your hosting provider's SSL certificates

Monitoring

Consider setting up:

• Health checks for your API
• Log aggregation (e.g., with ELK stack)
• Error tracking (e.g., Sentry)
• Uptime monitoring (e.g., UptimeRobot)

Backup Strategy

Regularly backup:

• Database - Use PostgreSQL's pg_dump
• User uploads - If you store files locally
• Configuration - Keep your .env files secure

Security Best Practices

• Use strong passwords for database and JWT secret
• Keep dependencies updated
• Use environment variables for secrets
• Enable rate limiting
• Set up firewall rules
• Regular security audits

Troubleshooting

Database Connection

Ensure your database is accessible from your application server and firewall rules allow connections.

CORS Issues

Make sure your frontend URL is whitelisted in the backend CORS configuration.

Build Errors

Ensure you're using the correct Node.js version (v22.14.0) and all dependencies are installed.

Next Steps

• Architecture Overview - Understand the system
• API Reference - Integrate with your instance
• Contributing - Help improve OpenAthlete