CS2Inspect Documentation

Development Setup Getting Started ​

Overview ​

CS2Inspect consists of two components that work together:

  1. CS2Inspect Web Application (this repository) - The web interface for managing loadouts
  2. CS2Inspect Plugin (GitHub Repository) - The CounterStrikeSharp plugin that applies loadouts in-game

Plugin Required

The CS2Inspect web application requires the CS2Inspect Plugin to be installed on your CS2 server. Both components share the same database. The web application stores loadout configurations, and the plugin reads from the database to apply them in-game.

Prerequisites ​

Important

Before setting up the CS2Inspect development environment, ensure you have the following installed:

Required Software ​

  • Node.js: Version 20.x or higher Required

    bash
    node --version  # Should be v20.0.0 or higher

  • Bun: Version 1.x or higher (recommended package manager) Recommended

    bash
    bun --version
# Install from https://bun.sh

    Package Manager

    This project uses Bun as the primary package manager for faster installs and better performance. npm is also supported but Bun is recommended.

  • MariaDB: Version 11 or higher Required

    • Alternative: Docker (for containerized database)

  • Git: Latest version Required

    bash
    git --version

Optional Software ​

  • Docker & Docker Compose: For containerized development Recommended
  • Visual Studio Code: Recommended IDE with extensions:
    • Volar (Vue Language Features)
    • ESLint
    • Tailwind CSS IntelliSense
    • TypeScript Vue Plugin

Installation Steps ​

1. Clone the Repository ​

bash
git clone https://github.com/sak0a/cs2inspect-web.git
cd cs2inspect-web

2. Install Dependencies ​

Using Bun (Recommended):

bash
bun install

Using npm (Alternative):

bash
npm install
What gets installed?

This will install all required packages including:

  • Nuxt 4 framework
  • Vue 3 and TypeScript
  • Naive UI components
  • Tailwind CSS
  • Database drivers
  • Testing frameworks
  • And more...

3. Database Setup ​

bash
# Start MariaDB container for local development
docker run -d --name cs2inspect-db \
  -e MYSQL_ROOT_PASSWORD=rootpassword \
  -e MYSQL_DATABASE=cs2inspect \
  -e MYSQL_USER=cs2inspect \
  -e MYSQL_PASSWORD=password \
  -p 3306:3306 \
  mariadb:11

Option B: Using Local MariaDB/MySQL ​

  1. Install MariaDB:

    bash
    # Ubuntu/Debian
sudo apt-get install mariadb-server

# macOS
brew install mariadb

# Windows
# Download from https://mariadb.org/download/

  2. Start MariaDB:

    bash
    sudo systemctl start mariadb

  3. Create Database:

    bash
    mysql -u root -p
    sql
    CREATE DATABASE csinspect CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'csinspect'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON csinspect.* TO 'csinspect'@'localhost';
FLUSH PRIVILEGES;
EXIT;

  4. Database Schema:

    Automatic Migrations

    The application uses Drizzle ORM for database migrations. The schema is applied automatically when you start the server for the first time. You can also push the schema manually with bun run db:push.

    The migration system will:

    • Create all required tables automatically
    • Track applied migrations in the __drizzle_migrations table
    • Run any new migrations on subsequent starts
    • Skip already-applied migrations

4. Install CS2Inspect Plugin (Required) ​

Plugin Installation Required

The CS2Inspect web application requires the CS2Inspect Plugin to be installed on your CS2 server. The plugin reads loadout configurations from the shared database and applies them in-game.

Plugin Repository: https://github.com/sak0a/CS2Inspect-Plugin

Plugin Installation Steps ​

  1. Clone the Plugin Repository:

    bash
    git clone https://github.com/sak0a/CS2Inspect-Plugin.git
cd CS2Inspect-Plugin

  2. Build the Plugin:

    bash
    dotnet build -c Release

  3. Install to CS2 Server:

    • Copy bin/Release/net8.0/CS2Inspect.dll to your CS2 server:
      game/csgo/addons/counterstrikesharp/plugins/CS2Inspect/
    • Copy configuration files to the plugin directory

  4. Configure Plugin Database Connection:

    The plugin must use the same database as the web application. Update the plugin's config.json:

    json
    {
  "DatabaseHost": "localhost",
  "DatabasePort": 3306,
  "DatabaseUser": "csinspect",
  "DatabasePassword": "your_database_password",
  "DatabaseName": "csinspect",
  "Website": "https://your-website.com"
}

  5. Verify Plugin Installation:

    • Restart your CS2 server
    • Check server logs for plugin initialization
    • Connect to the server and test plugin commands (e.g., !cs2inspect)

Plugin Documentation

For detailed plugin installation, configuration, and usage instructions, see the CS2Inspect Plugin README.

5. Environment Configuration ​

  1. Copy the example environment file:

    bash
    cp .env.example .env

  2. Edit .env file with your configuration:

    Security Notice

    Make sure to generate a secure JWT token and use strong passwords for production!

    env
    ########## Server Configuration ##########
PORT=3210
HOST=127.0.0.1

########## JWT API Configuration ##########
# Generate a random secret key
JWT_TOKEN=your_random_secret_key_here_min_32_characters
JWT_EXPIRY=7d

########## Database Configuration ##########
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=csinspect
DATABASE_PASSWORD=your_database_password
DATABASE_NAME=csinspect
DATABASE_CONNECTION_LIMIT=5

########## Steam API Configuration ##########
# Get your Steam API key: https://steamcommunity.com/dev/apikey
STEAM_API_KEY=your_steam_api_key_here

########## Steam Account Configuration (Optional) ##########
# Required for unmasked inspect URLs
# Use a separate Steam account (Steam Guard not currently supported)
STEAM_USERNAME=your_steam_username
STEAM_PASSWORD=your_steam_password

########## Logging (Optional) ##########
LOG_API_REQUESTS=true

  3. Generate a secure JWT token:

    bash
    # Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Or using OpenSSL
openssl rand -hex 32

6. Verify Configuration ​

Check that your configuration is correct:

bash
# Push schema to database (verifies connection)
bun run db:push

# Or manually test the connection:
mysql -h 127.0.0.1 -u csinspect -p csinspect -e "SHOW TABLES;"

System Integration ​

The web application and plugin work together through a shared database:

  • Web Application: Players configure loadouts through the web interface, which saves to the database
  • Plugin: When players join the server, the plugin reads their loadout from the database and applies it in-game
  • Real-Time Sync: Changes made on the web are immediately available to the plugin

Database Configuration

Both components must use the same database (same host, port, name, user, and password). The database schema is created automatically by the web application migrations. The plugin reads from these tables:

  • wp_player_loadouts - Loadout configurations
  • wp_player_rifles, wp_player_pistols, wp_player_smgs, wp_player_heavys - Weapon configurations
  • wp_player_knifes - Knife configurations
  • wp_player_gloves - Glove configurations
  • wp_player_agents - Agent selections
  • wp_player_pins - Pin collections

Running the Application ​

Development Mode ​

Start the development server with hot-reload:

Using Bun (Recommended):

bash
bun run dev

Using npm (Alternative):

bash
npm run dev

The application will be available at:

First Startup:

  • Database migrations run automatically
  • Health check sampling starts automatically
  • Check console for migration progress
  • Monitor startup health at /api/health/details

Production Build ​

Build the application for production:

Using Bun:

bash
bun run build

Using npm:

bash
npm run build

Preview the production build:

bash
bun run preview
# or
npm run preview

Docker Development ​

Run the database container for local development:

bash
# Start database container
docker start cs2inspect-db

# View logs
docker logs -f cs2inspect-db

# Stop database container
docker stop cs2inspect-db

TIP

If you haven't created the container yet, see the Database Setup section above for the docker run command.

Database Management ​

Drizzle ORM Migrations ​

The project uses Drizzle ORM for database schema management and migrations.

Migration files are stored in server/database/drizzle/ (auto-generated by Drizzle Kit).

Available Commands:

bash
# Push schema directly to database (good for development)
bun run db:push

# Generate migration files from schema changes
bun run db:generate

# Run pending migrations
bun run db:migrate

How it works:

  1. Migrations run automatically on app startup via server/database/migrate.ts
  2. Tracked in the __drizzle_migrations table
  3. Skips already-applied migrations
  4. The auto-migration system handles both fresh databases and databases previously set up with db:push (it seeds the journal if needed)

Development Workflow

During development, bun run db:push is the fastest way to sync your schema to the database. Use bun run db:generate and bun run db:migrate when you need versioned migration files (e.g., for production deployments).

Backup database:

bash
mysqldump -u csinspect -p csinspect > backup_$(date +%Y%m%d).sql

Restore database:

bash
mysql -u csinspect -p csinspect < backup_20240101.sql

Database Schema ​

The main tables are:

# Core Application Tables
wp_player_loadouts      - User loadout configurations
wp_player_weapons       - Weapon customizations
wp_player_knifes        - Knife customizations
wp_player_gloves        - Glove customizations
wp_player_agents        - Agent selections
wp_player_pins          - Pin collections

# System Tables
__drizzle_migrations    - Migration tracking (Drizzle ORM)

View migration files in server/database/drizzle/ directory.

Testing ​

Run All Tests ​

Using Bun:

bash
bun test

Using npm:

bash
npm test

Run Tests in Watch Mode ​

bash
bun test --watch
# or
npm run test:watch

Run Tests with Coverage ​

bash
bun test --coverage
# or
npm run test:coverage

Test Structure ​

tests/
├── unit/           # Component and utility tests
├── integration/    # API integration tests
└── e2e/           # End-to-end tests

Linting and Code Quality ​

Run Linter ​

Using Bun:

bash
bun run lint

Using npm:

bash
npm run lint

Auto-fix Linting Issues ​

bash
bun run lint -- --fix
# or
npm run lint -- --fix

ESLint Configuration ​

The project uses ESLint with:

  • Nuxt recommended rules
  • TypeScript support
  • Vue 3 rules
  • Tailwind CSS rules

Configuration: eslint.config.mjs

Development Workflow ​

1. Feature Branch Workflow ​

bash
# Create feature branch
git checkout -b feature/my-new-feature

# Make changes
# ...

# Commit changes
git add .
git commit -m "Add new feature"

# Push to remote
git push origin feature/my-new-feature

# Create pull request on GitHub

2. Component Development ​

When creating a new component:

  1. Create component file in components/
  2. Use TypeScript for type safety
  3. Follow existing naming conventions
  4. Add to component documentation if major feature
  5. Write unit tests if applicable

Example:

vue
<script setup lang="ts">
import { ref } from 'vue'

interface Props {
  title: string
  active?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  active: false
})

const emit = defineEmits<{
  (e: 'click'): void
}>()
</script>

<template>
  <div>
    <!-- Component template -->
  </div>
</template>

3. API Development ​

When creating a new API endpoint:

  1. Create file in server/api/
  2. Use TypeScript interfaces
  3. Implement authentication if needed
  4. Add error handling
  5. Document in API reference
  6. Write integration tests

Example:

typescript
// server/api/myendpoint.ts
import { defineEventHandler, readBody } from 'h3'

export default defineEventHandler(async (event) => {
  try {
    const body = await readBody(event)
    
    // Your logic here
    
    return {
      success: true,
      data: result
    }
  } catch (error) {
    return {
      success: false,
      error: error.message
    }
  }
})

Troubleshooting ​

Common Issues ​

1. Database Connection Errors ​

Error: ECONNREFUSED 127.0.0.1:3306

Solution:

bash
# Check if MariaDB is running
sudo systemctl status mariadb

# Start MariaDB
sudo systemctl start mariadb

# Or with Docker
docker start cs2inspect-db

2. Steam Authentication Issues ​

Error: Steam API key invalid

Solution:

3. Port Already in Use ​

Error: Port 3210 is already in use

Solution:

bash
# Find process using port 3210
lsof -i :3210

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3212 npm run dev

4. Missing Dependencies ​

Error: Cannot find module 'xyz'

Solution:

bash
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

5. TypeScript Errors ​

Error: Type 'X' is not assignable to type 'Y'

Solution:

bash
# Regenerate type definitions
npm run postinstall

# Or restart TypeScript server in your IDE

6. Steam Client Connection Issues ​

Error: Steam client disconnected or GC timeout

Solution:

  • Check that STEAM_USERNAME and STEAM_PASSWORD are correct
  • Ensure Steam Guard is disabled on the account (not currently supported)
  • Wait a few minutes and retry (Steam may be rate limiting)
  • Check Steam server status: https://steamstat.us/

7. Inspect URL Processing Fails ​

Error: Invalid inspect URL format

Solution:

  • Verify the URL format (see API documentation)
  • For unmasked URLs, ensure Steam account is configured
  • Check that the item still exists (not deleted from inventory)

Development Tools ​

Useful Commands ​

bash
# Generate static site
npm run generate

# Analyze bundle size
npm run build -- --analyze

# Update dependencies
npm update

# Check for outdated packages
npm outdated

# Clean build artifacts
rm -rf .nuxt .output node_modules/.cache

CLI Tools ​

The project includes interactive CLI tools for common operations:

Project CLI ​

bash
bun run cli

File: scripts/project-cli.ts

Interactive menu-driven CLI with categorized commands:

  • Development: Start dev server, build, preview, generate
  • Database: Push schema, generate/run migrations, open Drizzle Studio
  • Testing & Quality: Run tests, watch mode, coverage, lint, typecheck
  • Deployment: Create releases, manage Docker images
  • Health: Check application health status

Setup Wizard ​

bash
bun run setup

File: scripts/setup-wizard.ts

Interactive first-time configuration wizard:

  • Prompts for server configuration (port, host, environment)
  • Generates secure JWT token automatically
  • Configures database connection and tests connectivity
  • Sets up Steam API key
  • Writes .env file with all configured values

Environment Validator ​

bash
bun run validate-env

File: scripts/validate-env.ts

Validates your .env file against required variables:

  • Checks for missing required variables
  • Validates format and types with Zod schemas
  • Reports errors, warnings, and suggestions

VS Code Settings ​

Create .vscode/settings.json:

json
{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "files.associations": {
    "*.css": "tailwindcss"
  }
}
json
{
  "recommendations": [
    "Vue.volar",
    "dbaeumer.vscode-eslint",
    "bradlc.vscode-tailwindcss",
    "Vue.vscode-typescript-vue-plugin"
  ]
}

Next Steps ​

After setting up your development environment:

  1. Read the Architecture documentation
  2. Explore the Components guide
  3. Review the API Reference
  4. Check out How It Works

Production Deployment

For production environment variables and deployment configurations, see the Deployment Guide which includes complete environment variable references for all platforms.

Getting Help ​

  • Documentation: Check other docs in the docs/ directory
  • Issues: Report bugs on GitHub Issues
  • Discord: Join the community Discord (if available)
  • Stack Overflow: Tag questions with cs2inspect

Built with ❤️ by the CS2Inspect community

Copyright © 2026 CS2Inspect