Skip to content

QUICK_START.md

Latest commit

 

History

History
181 lines (140 loc) · 4.07 KB

QUICK_START.md

File metadata and controls

181 lines (140 loc) · 4.07 KB
Raw

Quick Start Guide - PostgreSQL Integration

🚀 5-Minute Setup

1. Install Dependencies

npm install

2. Configure Database

# Copy environment template
cp .env.example .env

# Edit .env and set your database credentials:
# DB_HOST=localhost
# DB_PORT=5432
# DB_USERNAME=postgres
# DB_PASSWORD=your_password
# DB_NAME=oddnet_matrix

3. Create Database

# Option A: Using psql
createdb oddnet_matrix

# Option B: Using SQL
psql -U postgres -c "CREATE DATABASE oddnet_matrix;"

4. Run Migrations

npm run migration:run

This creates three tables:

  • users - Stores Matrix user IDs
  • roles - Stores role definitions (admin, user, moderator)
  • user_roles - Links users to roles

5. Add Your First Admin

# Edit scripts/setup-db.sql with your Matrix ID
# Then run:
psql -U postgres -f scripts/setup-db.sql

Or manually:

psql -U postgres oddnet_matrix

INSERT INTO users ("matrixId", "displayName", "isActive") 
VALUES ('@yourname:matrix.org', 'Your Name', true);

INSERT INTO user_roles ("matrixId", "roleId") 
VALUES ('@yourname:matrix.org', 1);

6. Run the Bot

# Development
npm run dev

# Production
npm run build
npm start

📋 Essential Commands

Command Purpose
npm run migration:run Apply pending migrations
npm run migration:revert Undo last migration
npm run migration:show Show migration status
npm run migration:generate src/database/migrations/Name Auto-generate migration from entity changes
npm run migration:create src/database/migrations/Name Create empty migration file

🔐 Managing Users

Add a User

INSERT INTO users ("matrixId", "displayName", "isActive") 
VALUES ('@user:matrix.org', 'Display Name', true);

Assign Role to User

-- Admin role (id: 1)
INSERT INTO user_roles ("matrixId", "roleId") 
VALUES ('@user:matrix.org', 1);

-- User role (id: 2)
INSERT INTO user_roles ("matrixId", "roleId") 
VALUES ('@user:matrix.org', 2);

-- Moderator role (id: 3)
INSERT INTO user_roles ("matrixId", "roleId") 
VALUES ('@user:matrix.org', 3);

View All Users and Roles

SELECT 
  u."matrixId", 
  u."displayName", 
  u."isActive",
  r.name as role
FROM users u
LEFT JOIN user_roles ur ON u."matrixId" = ur."matrixId"
LEFT JOIN roles r ON ur."roleId" = r.id;

🎯 Command Authorization

In CommandController.ts, specify required roles:

this.commands.set('echo', { 
  handler: handleEcho,
  requiredRoles: ['user', 'admin'],  // Requires at least one role
  description: 'Echo back a message'
});

this.commands.set('ping', { 
  handler: handlePing,
  // No requiredRoles = accessible to everyone
  description: 'Check bot status'
});

📚 Documentation

🐛 Troubleshooting

"Cannot connect to database"

  • Check PostgreSQL is running: sudo systemctl status postgresql
  • Verify .env credentials
  • Test connection: psql -U postgres -d oddnet_matrix

"relation 'users' does not exist"

  • Run migrations: npm run migration:run

"Access denied" when running commands

  • Verify user exists in users table
  • Check user has required role in user_roles table
  • Ensure user's isActive is true

"Migration has already been executed"

  • Check status: npm run migration:show
  • The migration was already applied

💡 Next Steps

  1. Create custom commands - See examples in src/controllers/commands/
  2. Add custom roles - Insert into roles table
  3. Modify entities - Edit files in src/database/entities/
  4. Generate migrations - npm run migration:generate

🔄 Daily Workflow

# Pull latest code
git pull

# Install new dependencies
npm install

# Apply new migrations
npm run migration:run

# Start bot
npm run dev

That's it! Your bot now has database-backed user management with role-based command authorization.