Deploy and Host

A secure, real-time chat application with advanced features and elite cybersecurity standards.

Video Guide: https://pub-43cda9e3bc1549aabbf03636b3384795.r2.dev/chatui_deployment_guide.mp4

About Hosting

Deploy your own instance to Railway with a single click:

Why Deploy

✅ Application (Docker image from GHCR)
✅ PostgreSQL database (auto-configured)
✅ Persistent storage at /data
✅ Auto-generated secure credentials (check logs after deployment)

Common Use Cases

🔐 Secure Authentication - JWT-based auth with bcrypt password hashing
💬 Real-time Messaging - WebSocket-powered instant messaging with Socket.io
📁 Secure File Sharing - Protected file uploads with channel-based access control
👥 Channel Management - Create and manage chat channels
🔔 Notifications - Real-time notifications for messages and events
📊 Admin Dashboard - System monitoring and user management
🎨 Modern UI - Built with React, Tailwind CSS, and Radix UI
🔒 PIN Protection - Optional PIN lock for added security
📱 PWA Support - Install as a Progressive Web App
🛡️ File Security - Authenticated and authorized file access only
🚂 Railway Ready - Optimized for Railway deployment with mounted storage

Dependencies for

Deployment Dependencies

📖 Complete Setup Guide: See docs/setup.md for detailed instructions.

⚠️ IMPORTANT: After forking, you must enable GitHub Actions workflow permissions:

Go to Settings → Actions → General
Under Workflow permissions, select "Read and write permissions"
Click Save

This is required for automatic Docker image builds to work.

Quick Setup

# Clone your fork
git clone https://github.com//chat-blackonion.git
cd chat-blackonion

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Edit .env with your database credentials and secrets
# See docs/setup.md for details

# Run database migrations
npm run db:migrate

# Seed database with initial admin user (optional)
npm run db:seed

# Start development server
npm run dev

Visit http://localhost:5000 to see the application.

🔐 Default Credentials (Development Only):

Username: admin
Password: admin123
App Passcode: admin1234

⚠️ IMPORTANT: For production, set ADMIN_PASSWORD and ADMIN_PASSCODE environment variables before deployment!

🛠️ Tech Stack

Frontend

React - UI library
TypeScript - Type-safe JavaScript
Vite - Fast build tool
Tailwind CSS - Utility-first CSS
Radix UI - Accessible component primitives
Socket.io Client - Real-time communication
React Query - Data fetching and caching
Wouter - Lightweight routing

Backend

Node.js - Runtime environment
Express - Web framework
Socket.io - WebSocket server
PostgreSQL - Database
Drizzle ORM - Type-safe database toolkit
Railway Storage - Persistent file storage (mounted volume)
JWT - Authentication tokens
Bcrypt - Password hashing

📦 Available Scripts

# Development
npm run dev          # Start development server with hot reload

# Production
npm run build        # Build for production
npm run start        # Start production server

# Database
npm run db:generate  # Generate migration files from schema
npm run db:migrate   # Run pending migrations
npm run db:push      # Push schema changes directly
npm run db:studio    # Open Drizzle Studio (database GUI)
npm run db:seed      # Seed database with initial data

# Utilities
npm run check        # Run TypeScript type checking
npm run setup:passcode  # Set up admin passcode

🐳 Docker Deployment

Using Pre-built Image

docker pull ghcr.io//chat-blackonion:latest

docker run -d \
  -p 5000:5000 \
  -v $(pwd)/public:/public \
  -e DATABASE_URL="postgresql://..." \
  -e SESSION_SECRET="your-secret" \
  --name chat-blackonion \
  ghcr.io//chat-blackonion:latest

Building Locally

docker build -t chat-blackonion .
docker run -d -p 5000:5000 -v $(pwd)/public:/public --env-file .env chat-blackonion

� Railway Deployment

📖 Railway Guide: See docs/RAILWAY.md for complete Railway deployment instructions.

Railway provides:

✅ Automatic deployments from GitHub
✅ Managed PostgreSQL database
✅ Persistent storage mounted at /public
✅ Zero configuration file uploads

Quick start:

Connect your GitHub repository to Railway
Add PostgreSQL database
Mount volume at /public
Set environment variables
Deploy! 🚀

🔧 Environment Variables

Create a .env file based on .env.example:

# Required
DATABASE_URL=postgresql://user:pass@host:port/database
SESSION_SECRET=your-random-secret-key

# Security (Highly Recommended for Production)
ADMIN_PASSWORD=your-secure-admin-password    # Default: admin123
ADMIN_PASSCODE=your-secure-app-passcode      # Default: admin1234

# Optional - Railway Storage
# RAILWAY_STORAGE_PATH=/public  # Auto-configured for Railway

# Optional - Development
NODE_ENV=development
PORT=5000
NODE_TLS_REJECT_UNAUTHORIZED=0  # For development only

🔐 Security Notes:

ADMIN_PASSWORD sets the initial admin account password (used during database seeding)
ADMIN_PASSCODE sets the app access code (calculator unlock sequence)
If not set, defaults will be used (NOT secure for production!)
These values are only used when creating a new database
Change credentials via Admin Dashboard after first login

Generate a secure session secret:

openssl rand -base64 32

📖 Complete Variable Reference: See docs/ENVIRONMENT-VARIABLES.md

📚 Documentation

Setup Guide - Complete installation and configuration instructions
Environment Variables - Complete variable reference
Railway Deployment - Deploy to Railway with persistent storage
Railway Migration Fix - Fix "relation does not exist" errors
File Security - Understanding protected file access
API Documentation - Swagger API docs (when running)

🏗️ Project Structure

chat-blackonion/
├── client/              # Frontend React application
│   ├── src/
│   │   ├── components/  # Reusable UI components
│   │   ├── pages/       # Page components
│   │   ├── contexts/    # React contexts
│   │   └── lib/         # Utilities and helpers
│   └── public/          # Static assets
├── server/              # Backend Express application
│   ├── routes/          # API route handlers
│   ├── services/        # Business logic
│   ├── lib/             # Server utilities
│   └── config/          # Configuration files
├── shared/              # Shared types and schemas
├── migrations/          # Database migrations
└── docs/                # Documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

🔒 Security

All passwords are hashed with bcrypt
JWT tokens for authentication
SQL injection protection via Drizzle ORM
CORS configuration for API security
SSL/TLS for database connections
Environment variable protection
Protected file access - Files require authentication and channel membership
Path traversal prevention
Channel-based authorization for all uploaded files

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

Hasan Shahriar - hasanshahriar32

🙏 Acknowledgments

The Black Onion team for cybersecurity excellence
Open source community for amazing tools and libraries

⭐ Star this repository if you find it helpful!