Version: 0.3.0 Last Updated: 2026-01-29

• General
• Installation & Setup
• Features & Functionality
• Development
• Deployment
• Troubleshooting
• Security & Privacy
• Performance
• Contributing

ɳChat is a production-ready, white-label team communication platform built with Next.js 15 and React 19. It provides Slack/Discord/Telegram-like functionality with complete customization options.

White-label means you can completely customize the branding, theme, features, and deployment. The 12-step setup wizard lets you configure everything without touching code.

Yes! ɳChat is open-source under the MIT License. You can use it freely for commercial or personal projects.

ɳChat is a demo project showcasing the ɳSelf CLI backend infrastructure. While fully functional, it's designed to demonstrate ɳSelf's capabilities.

ɳChat provides feature parity with major platforms:

• 78+ features across messaging, channels, files, users, and integrations
• Self-hosted - full control over your data
• White-label - complete branding customization
• Open source - modify anything you need

• Node.js: 20 or higher
• pnpm: 9 or higher
• RAM: 4GB minimum (8GB recommended)
• Disk: 2GB free space
• OS: macOS, Linux, or Windows (WSL2)

Initial setup takes under 5 minutes:

1. Clone repository (30 seconds)
2. Install dependencies (2-3 minutes)
3. Start dev server (30 seconds)
4. Complete setup wizard (1-2 minutes)

Docker is optional for development. The setup wizard can:

• Use Docker for backend services (recommended)
• Connect to existing services
• Skip backend for frontend-only development

Yes! Pre-configure via environment variables and set SKIP_WIZARD=true. The wizard auto-detects existing config and skips completed steps.

# Clear configuration
rm -f .env.local
localStorage.removeItem('app-config')  # In browser console

# Or via API
curl -X DELETE http://localhost:3000/api/config

78+ features including:

• Real-time messaging with threads and reactions
• Voice and video calls (WebRTC)
• File uploads with previews
• Search (messages, files, users)
• Bot SDK with slash commands
• Webhooks and integrations
• Multi-language support (6 languages)
• Offline mode with sync
• Full RBAC (role-based access control)

See Features-Complete.md for complete list.

Yes, ɳChat uses WebRTC for peer-to-peer calls. No third-party services required. For group calls with 4+ participants, you may want a TURN server.

Yes! Built-in integrations:

• Slack: Import channels, messages, and users
• Discord: Bot integration and webhooks
• API: Custom integrations via webhooks

Yes! Multiple deployment options:

• PWA: Progressive Web App (works on all mobile browsers)
• Capacitor: Native iOS and Android apps
• React Native: Full native mobile apps

Tested with:

• 100+ concurrent users (single server)
• 1,000+ total users (with proper infrastructure)
• Scales horizontally with load balancers

Frontend:

• Next.js 15.1.6 (App Router)
• React 19.0.0
• TypeScript 5.7.3
• Tailwind CSS 3.4.17
• Zustand (state management)
• Apollo Client (GraphQL)

Backend (via ɳSelf CLI):

• PostgreSQL 16
• Hasura GraphQL Engine
• Nhost Auth
• MinIO (S3-compatible storage)

1. Read CONTRIBUTING.md
2. Create feature branch: git checkout -b feature/my-feature
3. Implement with tests
4. Run checks: pnpm validate
5. Submit pull request

Yes! 8 test users with different roles:

• [email protected] - Full permissions
• [email protected] - User/channel management
• [email protected] - Content moderation
• [email protected] - Standard user
• [email protected] - Read-only
• Plus: alice, bob, charlie

All use password: password123

# Unit tests
pnpm test

# E2E tests
pnpm test:e2e

# With coverage
pnpm test:coverage

# Watch mode
pnpm test:watch

The project requires pnpm for:

• Faster installs (content-addressable storage)
• Strict dependency resolution
• Monorepo support
• Lock file consistency

Install: npm install -g pnpm

• Vercel (recommended for frontend)
• Docker (containerized deployment)
• Kubernetes (scalable clusters)
• Traditional VPS (Nginx + PM2)

See DEPLOYMENT.md for detailed guides.

Estimated monthly costs:

• Vercel Free Tier: $0 (frontend only)
• Vercel Pro: $20/month
• VPS (DigitalOcean): $12-50/month
• AWS/GCP: $30-100/month (depending on usage)
• Self-hosted: Hardware costs only

Yes, PostgreSQL 14+ is required. Options:

• Managed: AWS RDS, DigitalOcean, Supabase ($15-50/month)
• Self-hosted: On same VPS as app (free)
• Development: Docker container (free)

Free SSL (Let's Encrypt):

sudo certbot --nginx -d chat.yourdomain.com

Vercel: Automatic SSL for custom domains Cloudflare: Free SSL + CDN

Yes! Use:

• Vercel Edge Network (automatic global distribution)
• Kubernetes with multi-region clusters
• CDN (Cloudflare, Fastly) for static assets
• Database replication for read replicas

# Clear cache and reinstall
rm -rf .next node_modules pnpm-lock.yaml
pnpm install
pnpm build

# Find and kill process
lsof -ti:3000 | xargs kill -9

# Or use different port
PORT=3001 pnpm dev

# Regenerate types
pnpm db:types

# Clear TypeScript cache
rm -rf .next tsconfig.tsbuildinfo
pnpm type-check

Check backend services:

cd .backend
nself status

# Restart if needed
nself restart

Development mode:

# Ensure dev auth is enabled
echo "NEXT_PUBLIC_USE_DEV_AUTH=true" >> .env.local

Production mode:

# Check auth service
curl https://auth.yourdomain.com/healthz

# Check Next.js image optimization
# In next.config.js:
images: {
  domains: ['your-storage-domain.com'],
  formats: ['image/avif', 'image/webp'],
}

Check Nginx configuration for WebSocket upgrade:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';

Yes! Security features:

• JWT authentication with refresh tokens
• RBAC (role-based access control)
• HTTPS required in production
• XSS protection via React escaping
• SQL injection prevention via Hasura
• CSRF protection on all forms
• Rate limiting on API endpoints

You control data storage:

• Database: Your PostgreSQL instance
• Files: Your S3/MinIO bucket
• Sessions: Redis or database
• Logs: Your logging service

• In transit: TLS/SSL (HTTPS)
• At rest: PostgreSQL encryption (configurable)
• Passwords: bcrypt hashing
• Tokens: Signed JWT

E2E encryption is on the roadmap (v0.4.0). Current encryption:

• Transport layer (TLS/SSL)
• Database encryption at rest
• Password hashing

See SECURITY.md for responsible disclosure:

• Email: [email protected]
• DO NOT open public GitHub issues
• Response within 48 hours

Lighthouse scores:

• Performance: 90+
• Accessibility: 95+
• Best Practices: 90+
• SEO: 90+

Real-world metrics:

• First Contentful Paint: <1.5s
• Largest Contentful Paint: <2.5s
• Time to Interactive: <3s

• Shared baseline: 103 KB
• Largest page: 570 KB (channel page with all features)
• Average page: 200-300 KB

Optimizations:

• Code splitting with dynamic imports
• Tree shaking unused code
• Image optimization (AVIF/WebP)
• Lazy loading components

• Per channel: Millions (virtualized list)
• Displayed: 50-100 at a time (pagination)
• Search: Full-text search across all messages

Yes! Progressive Web App features:

• Service worker caching
• IndexedDB for message storage
• Queue for offline actions
• Background sync when online

Many ways to contribute:

• Code: Fix bugs, add features
• Documentation: Improve guides, add examples
• Design: UI/UX improvements
• Testing: Report bugs, test features
• Translation: Add language support
• Community: Help answer questions

See CONTRIBUTING.md for details.

No Contributor License Agreement required. By contributing, you agree to the MIT License terms.

1. Check existing issues
2. Create new issue with template
3. Include:
   • Steps to reproduce
   • Expected vs actual behavior
   • Screenshots if UI-related
   • Environment details

Yes! Use GitHub Discussions:

1. Check if already requested
2. Describe use case
3. Explain expected behavior
4. Community votes on priority

• Initial response: Within 3 business days
• Review: Within 7 business days
• Merge decision: Based on feedback

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and ideas
• Discord: Real-time chat with community
• Email: [email protected]
• Documentation: https://docs.nself.org

Can't find your question? Ask in GitHub Discussions!