Skip to content

Getting Started

Jump to bottom
mack42 edited this page Nov 26, 2025 · 1 revision

Getting Started with OpenChat

Welcome to OpenChat! This guide will walk you through setting up a local development environment from scratch.

What is OpenChat?

OpenChat is an open-source, self-hosted team collaboration platform built with:

  • Backend: Rust (Actix Web) with PostgreSQL and Redis
  • Frontend: Next.js 16 with React 19 and TypeScript
  • Authentication: TitaniumVault SSO

Prerequisites

Before you begin, install the following:

Tool Version Purpose
Rust 1.83+ Backend development
Node.js 20+ Frontend development
PostgreSQL 14+ Database
Redis 7+ Caching & Pub/Sub
Docker Latest Running dependencies
sqlx-cli Latest Database migrations

Install sqlx-cli

cargo install sqlx-cli --no-default-features --features postgres

1. Clone the Repository

# HTTPS
git clone https://github.com/ZerosAndOnesLLC/OpenChat.git
cd OpenChat

# Or SSH
git clone git@github.com:ZerosAndOnesLLC/OpenChat.git
cd OpenChat

2. Start Dependencies

Use Docker Compose to start PostgreSQL and Redis:

docker-compose up -d postgres redis

Or if you have PostgreSQL and Redis installed locally, ensure they're running.

3. Set Up the Backend (API)

Configure Environment

cd api
cp .env.example .env

Edit .env with your settings:

# Database
DATABASE_URL=postgres://username:password@localhost/openchat

# Redis
REDIS_URL=redis://localhost:6379

# TitaniumVault (for SSO)
TV_API_URL=https://api.titanium-vault.com
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_REDIRECT_URI=http://localhost:3000/sso/callback/

# Server
PORT=9876
HOST=0.0.0.0

# JWT
JWT_SECRET=your-development-secret-key

# Logging
RUST_LOG=info,openchat_api=debug

Create Database and Run Migrations

# Source .env for database connection
source .env

# Create the database
sqlx database create

# Run all migrations
sqlx migrate run

Start the API Server

cargo run

The API will be available at http://localhost:9876

Verify API is Running

curl http://localhost:9876/health
# Should return: {"status":"ok"}

4. Set Up the Frontend (UI)

Configure Environment

cd ../ui
cp .env.example .env.local

Edit .env.local:

NEXT_PUBLIC_API_URL=http://localhost:9876
NEXT_PUBLIC_WS_URL=ws://localhost:9876/api/ws
NEXT_PUBLIC_TV_API_URL=https://api.titanium-vault.com
NEXT_PUBLIC_OAUTH_CLIENT_ID=your-client-id

Install Dependencies and Start

npm install
npm run dev

The UI will be available at http://localhost:3000

5. Authentication with TitaniumVault

OpenChat uses TitaniumVault for authentication. To test locally:

  1. Register an OAuth client in TitaniumVault:

    • Client ID: openchat-local
    • Redirect URI: http://localhost:3000/sso/callback/
    • Grant types: authorization_code, refresh_token

  2. Access OpenChat through TitaniumVault:

This initiates the OAuth flow and authenticates you automatically.

6. Verify Everything Works

  1. Open the UI: http://localhost:3000
  2. Authenticate through TitaniumVault
  3. Create a channel and send a test message
  4. Check real-time updates by opening a second browser tab

Project Structure

openchat/
├── api/                    # Rust backend
│   ├── src/
│   │   ├── main.rs        # Entry point
│   │   ├── config.rs      # Configuration
│   │   ├── handlers/      # Request handlers
│   │   ├── models/        # Database models
│   │   ├── services/      # Business logic
│   │   └── websocket/     # WebSocket handlers
│   └── migrations/        # SQL migrations
│
├── ui/                     # Next.js frontend
│   ├── app/               # Pages (App Router)
│   ├── components/        # React components
│   └── lib/               # Utilities & API client
│
└── windows/               # Tauri desktop app (optional)

Common Commands

Backend (API)

cd api

# Run development server
cargo run

# Type checking
cargo check

# Run tests
cargo test

# Linting
cargo clippy -- -D warnings

# Format code
cargo fmt

# Create new migration
sqlx migrate add -r migration_name

Frontend (UI)

cd ui

# Development server
npm run dev

# Production build
npm run build

# Linting
npm run lint

# Start production build
npm start

Next Steps

Troubleshooting

Database connection fails

Ensure PostgreSQL is running and DATABASE_URL is correct:

source .env
psql $DATABASE_URL -c "SELECT 1"

Redis connection fails

Check Redis is running:

redis-cli ping
# Should return: PONG

WebSocket not connecting

  1. Verify the API is running on the correct port
  2. Check NEXT_PUBLIC_WS_URL matches your API URL
  3. Ensure no firewall is blocking WebSocket connections

Migrations fail

# Reset and recreate database
sqlx database drop
sqlx database create
sqlx migrate run

Getting Help

Clone this wiki locally