Skip to main content

Installation

This guide will help you set up the DOTA Web Panel for local development or production build.

Quick Checklist​

Prerequisites​

Before you begin, ensure you have:

  • Node.js 18.18.0 (exact version required)
  • Corepack for package manager version management
  • pnpm 10.17.0+ (managed by Corepack)

Install Dependencies​

1. Clone the Repository​

git clone https://github.com/ds-horizon/delivr-web-panel.git
cd delivr-web-panel

2. Enable Corepack​

Corepack is required for proper pnpm version management:

# Install corepack globally (if not already installed)
npm install -g corepack

# Enable corepack
corepack enable

3. Install pnpm​

If pnpm is not already installed:

npm install -g pnpm

4. Install Dependencies​

pnpm install

5. Environment Configuration​

Create a .env file in the root directory:

cp .env.example .env

Edit the .env file with your configuration:

# Google OAuth Configuration
GOOGLE_CLIENT_ID=your-google-oauth-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-oauth-client-secret

# Backend API Configuration  
DELIVR_BACKEND_URL=http://localhost:3010
Environment configured

Your Web Panel is configured to talk to the backend.

Google OAuth Setup​

The dashboard uses Google OAuth for authentication. Follow these steps to configure it:

1. Create Google Cloud Project​

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one

2. Enable OAuth 2.0​

  1. Navigate to APIs & Services → Credentials
  2. Click Create Credentials → OAuth 2.0 Client ID
  3. Configure the OAuth consent screen if prompted
  4. Select Web application as application type

3. Configure OAuth Client​

Authorized JavaScript origins:

http://localhost:5173
https://your-production-domain.com

Authorized redirect URIs:

http://localhost:5173/auth/callback
https://your-production-domain.com/auth/callback

4. Copy Credentials​

After creating the OAuth client:

  1. Copy the Client ID
  2. Copy the Client Secret
  3. Add them to your .env file

Backend Server Setup​

The Web Panel requires the DOTA Backend server to be running.

Start Backend Locally​

Follow the Backend Installation Guide to set up and start the backend server.

Verify the backend is running:

curl http://localhost:3010/health

Update Backend URL​

In your .env file, ensure DELIVR_BACKEND_URL points to your backend:

# Local development
DELIVR_BACKEND_URL=http://localhost:3010

# Production
DELIVR_BACKEND_URL=https://api.your-domain.com

Run the Web Panel (Development)​

Start the development server:

pnpm dev

The application will be available at http://localhost:5173 🚀

Dev server running

Open http://localhost:5173 to access the Web Panel in development mode.

Development Features​

  • Hot Module Replacement (HMR): Instant updates on code changes
  • TypeScript checking: Real-time type validation
  • Fast refresh: Preserves component state during edits

Run the Web Panel (Production Build)​

Build for Production​

pnpm build

This generates optimized static files in the dist/ directory.

Start Production Server​

pnpm start

The production server will start on the configured port (default: 3000).

Preview Production Build Locally​

Before deploying, preview the production build:

# Build first
pnpm build

# Preview
pnpm preview

Verification​

After starting the application:

  1. Open Browser: Navigate to http://localhost:5173
  2. Sign In: Click "Sign in with Google"
  3. Authorize: Grant permissions to the app
  4. Dashboard: You should see the dashboard home page

Additional Commands (Optional)​

Run Tests​

Execute the unit test suite to validate functionality.

pnpm test

Run Linting​

Check code style and catch common issues.

pnpm lint

Type Checking​

Run TypeScript type checks for static correctness.

pnpm typecheck

Generate Routes and Config​

Regenerate typed routes and configuration artifacts after changes.

pnpm gen:routes && pnpm gen:config

Troubleshooting​

OAuth Error: redirect_uri_mismatch​

Problem: The redirect URI doesn't match the configured one.

Solution:

  1. Check your Google Cloud Console OAuth settings
  2. Ensure the redirect URI exactly matches: http://localhost:5173/auth/callback
  3. Include both development and production URIs

Cannot Connect to Backend​

Problem: Dashboard can't reach the backend API.

Solution:

  1. Verify backend is running: curl http://localhost:3010/health
  2. Check DELIVR_BACKEND_URL in .env
  3. Ensure no firewall blocking the connection

pnpm Command Not Found​

Problem: pnpm is not installed or not in PATH.

Solution:

# Enable corepack
corepack enable

# Install pnpm
npm install -g pnpm

Wrong Node Version​

Problem: Node version mismatch.

Solution:

# Using nvm
nvm install 18.18.0
nvm use 18.18.0

# Using n
n 18.18.0

Build Fails​

Problem: Production build fails.

Solution:

# Clear cache and rebuild
rm -rf node_modules dist
pnpm install
pnpm build