# Quick Start Guide

## Prerequisites

Before you begin, ensure you have:

- **Node.js** (v18+ recommended) - Check with `node --version`
- **npm** or **yarn** - Package manager
- **Git** - For version control

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/alexpolo1/dwroller.git
cd dwroller
```

### 2. Install Dependencies

```bash
npm install
```

This will install all required packages for both frontend and backend.

### 3. Configure Environment

Create a `.env` file in the root directory:

```bash
cp .env.example .env
```

Edit `.env` with your configuration:

```env
# Backend server port
PORT=5000

# Session secret (random string recommended)
SESSION_SECRET=your-random-secret-here

# GM API secret for player management
X_GM_SECRET=your-gm-secret-key

# Database path (optional - defaults to server location)
DATABASE_PATH=./database/data.db
```

### 4. Start the Application

Run both servers:

```bash
# Terminal 1 - Backend API
npm run server

# Terminal 2 - Frontend
npm start
```

The application will be available at:
- **Frontend**: `http://localhost:3000`
- **API**: `http://localhost:5000`

## First Steps

1. Visit `http://localhost:3000` in your browser
2. Browse the shop or view the bestiary
3. If you're a GM, use the player management feature

## Production Deployment

For production builds:

```bash
# Build frontend
npm run build

# Start with PM2
npm run pm2:start
```

See [PM2 Configuration](./pm2.md) for details.

## Troubleshooting

### Port already in use

If port 3000 or 5000 is busy:

```bash
# Find what's using the port
lsof -i :3000
lsof -i :5000

# Kill the process or change the port in .env
```

### Database issues

The application creates the database automatically on first run. If you see errors:

```bash
# Check database exists
ls -la database/

# If database file is corrupted, remove it to recreate
rm database/data.db
```

### Clear cache

If the frontend shows old content:

```bash
rm -rf .next/
npm start
```

## Next Steps

- Read the [User Guide](./user-guide.md) to learn features
- Explore the [API Documentation](./api.md)
- See [Developer Guide](./developer-guide.md) for contribution guidelines