v1.0.9 LIMITATION — Voice/Video calls require bring your own LiveKit + coturn

nChat's livekit plugin is an API wrapper around an externally-hosted LiveKit Server cluster. To enable real-time voice/video calls in v1.0.9, you must run livekit/livekit-server and coturn separately — nself does not yet ship compose templates for these (planned for v1.1.0). Without these, audio/video calls will fail to connect behind NAT. See the Self-Hosted Deployment Guide for copy-pasteable docker run snippets covering livekit-server + coturn.

Core messaging (text, files, channels, DMs) works without LiveKit.

Get nchat up and running in under 5 minutes with this quick start guide.

Before you begin, ensure you have:

git clone https://github.com/nself/nself-chat.git
cd nself-chat

npm install

The backend uses the nself CLI to provide PostgreSQL, Hasura, and authentication services.

# Install nself CLI (if not already installed)
curl -fsSL https://nself.io/install.sh | bash

# Initialize the backend
cd .backend
nself init --demo
nself build
nself start

# Return to project root
cd ..

Create your local environment file:

cp .env.example .env.local

The default configuration enables development mode with test users:

# Backend URLs (via nself CLI)
NEXT_PUBLIC_GRAPHQL_URL=http://api.localhost/v1/graphql
NEXT_PUBLIC_AUTH_URL=http://auth.localhost/v1/auth
NEXT_PUBLIC_STORAGE_URL=http://storage.localhost/v1/storage

# Development Mode
NEXT_PUBLIC_USE_DEV_AUTH=true
NEXT_PUBLIC_ENV=development

# App Configuration
NEXT_PUBLIC_APP_NAME=nchat
NEXT_PUBLIC_PRIMARY_COLOR=#6366f1

npm run dev

Visit http://localhost:3000 to see nchat running.

When NEXT_PUBLIC_USE_DEV_AUTH=true, you get:

Eight pre-configured users are available for testing:

Development mode automatically logs in as [email protected] for faster iteration.

Test different roles by switching users:

import { useAuth } from '@/contexts/auth-context'

function MyComponent() {
  const { switchUser } = useAuth()

  // Switch to admin role
  await switchUser('[email protected]')

  // Switch to guest role
  await switchUser('[email protected]')
}

On first launch, nchat presents a 9-step setup wizard:

1. Welcome - Introduction to nchat
2. Owner Info - Your name, email, company
3. Auth Methods - Choose authentication providers
4. Access Permissions - Set access control mode
5. Features - Enable/disable features
6. Landing Page - Configure landing page
7. Branding - App name, logo, colors
8. Theme - Choose from 8+ theme presets
9. Review - Confirm and save settings

nself-chat/
├── src/
│   ├── app/              # Next.js app router
│   ├── components/       # React components
│   ├── contexts/         # React contexts
│   ├── config/           # Configuration
│   ├── graphql/          # GraphQL queries
│   ├── hooks/            # Custom hooks
│   ├── lib/              # Utilities
│   └── services/         # Service classes
├── .backend/             # nself CLI backend (gitignored)
├── public/               # Static assets
├── docs/                 # Documentation
└── package.json

• Installation Guide - Detailed installation options
• Configuration - All configuration options
• Features Overview - Explore all features
• Authentication - Set up auth providers
• White Labeling - Customize branding

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

# Format code
npm run format

# Navigate to backend
cd .backend

# Start services
nself start

# Stop services
nself stop

# View logs
nself logs

# Check status
nself status

# View service URLs
nself urls

cd .backend && nself start

# Find process using port 3000
lsof -i :3000

# Or start on different port
PORT=3001 npm run dev

Ensure Docker Desktop is running, then:

docker ps

Check PostgreSQL is running:

cd .backend && nself status

See the full Installation Guide for detailed troubleshooting.