dwroller/docs/quick-start.md

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

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

2. Install Dependencies

npm install

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

3. Configure Environment

Create a .env file in the root directory:

cp .env.example .env

Edit .env with your configuration:

# 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:

# 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:

# Build frontend
npm run build

# Start with PM2
npm run pm2:start

See PM2 Configuration for details.

Troubleshooting

Port already in use

If port 3000 or 5000 is busy:

# 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:

# 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:

rm -rf .next/
npm start

Next Steps

• Read the User Guide to learn features
• Explore the API Documentation
• See Developer Guide for contribution guidelines