---
title: "Deploy theblackonion"
description: "Deploy and Host theblackonion chat with Railway"
category: "Other"
url: https://railway.com/deploy/theblackonion
---

# Deploy theblackonion

Deploy and Host theblackonion chat with Railway

**[Deploy theblackonion on Railway](https://railway.com/template/theblackonion)**

- **Category:** Other
- **Total deploys:** 2

## Template content

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:17

### chat-blackonion

- **Image:** ghcr.io/hasanshahriar32/chat-blackonion:latest
- **Public domain:** Yes

## Documentation

# 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/gJ90Bm?referralCode=NVp-pJ)

## 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](docs/setup.md) for detailed instructions.

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

1. Go to **Settings** → **Actions** → **General**
2. Under **Workflow permissions**, select **"Read and write permissions"**
3. Click **Save**

This is required for automatic Docker image builds to work.

### Quick Setup

```bash
# 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

```bash
# 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

```bash
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

```bash
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](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:
1. Connect your GitHub repository to Railway
2. Add PostgreSQL database
3. Mount volume at `/public`
4. Set environment variables
5. Deploy! 🚀

## 🔧 Environment Variables

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

```bash
# 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:
```bash
openssl rand -base64 32
```

**📖 Complete Variable Reference**: See [docs/ENVIRONMENT-VARIABLES.md](docs/ENVIRONMENT-VARIABLES.md)

## 📚 Documentation

- **[Setup Guide](docs/setup.md)** - Complete installation and configuration instructions
- **[Environment Variables](docs/ENVIRONMENT-VARIABLES.md)** - Complete variable reference
- **[Railway Deployment](docs/RAILWAY.md)** - Deploy to Railway with persistent storage
- **[Railway Migration Fix](docs/RAILWAY-MIGRATION-FIX.md)** - Fix "relation does not exist" errors
- **[File Security](docs/FILE-SECURITY.md)** - Understanding protected file access
- **[API Documentation](http://localhost:5000/api-docs)** - 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.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. 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](https://github.com/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!**


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/theblackonion