Own Your Conversations.
An open-source, self-hosted real-time communication platform.
FreedomTalk is a Discord-style communication platform you can run on your own infrastructure. It ships a Fastify + Socket.io backend and a Next.js web app organized as an npm-workspaces monorepo, backed by PostgreSQL, Redis, and RabbitMQ. Core community features are implemented end to end — accounts and authentication, servers with roles and permissions, channels, direct messages, friends, real-time messaging with reactions and attachments, search, and WebRTC-based voice — with automated test coverage at both the API and end-to-end levels.
- Accounts & Authentication — registration with email verification, login with sessions, JWT access/refresh tokens, password reset, multi-factor authentication (TOTP), and session invalidation.
- Servers (Communities) — create and manage servers with channels, roles, and a permission system; server discovery and invite links.
- Real-Time Messaging — instant chat over Socket.io with Markdown formatting, emoji reactions, embeds, and file attachments.
- Direct Messages & Friends — one-on-one DMs, friend requests, and presence.
- Search — message and server search.
- Voice — WebRTC voice backed by a mediasoup SFU (experimental).
- Platform Plumbing — webhooks, audit logs, and Prometheus-style metrics endpoints.
- Self-Hosted — everything runs in Docker Compose on your hardware. Your data, your rules.
| Technology | Purpose |
|---|---|
| Fastify 5.x | High-performance HTTP framework (Helmet, CORS, rate limiting, Swagger) |
| Socket.io 4.x | Real-time WebSocket communication (Redis adapter for scaling) |
| PostgreSQL + Knex | Persistence with migrations and seeds |
| Redis | Caching, pub/sub, rate limiting |
| RabbitMQ | Message queue for background work |
| mediasoup | WebRTC SFU for voice |
| TypeScript + Zod | Type-safe development and schema validation |
| Technology | Purpose |
|---|---|
| Next.js 16 (App Router) | React framework |
| React 19 | UI |
| Tailwind CSS | Styling |
| Socket.io Client | Real-time updates |
- Docker / Docker Compose — containerized development environment
- npm Workspaces — monorepo management
- Node.js 20+
- npm 10+
- Docker & Docker Compose
-
Clone the repository
git clone https://github.com/notdezzi/freedomtalk.git cd freedomtalk -
Install dependencies
npm install
-
Start infrastructure services
npm run docker:up
-
Configure environment variables
cp packages/api/.env.example packages/api/.env cp packages/web/.env.example packages/web/.env.local
Update the
.envfiles with your specific configuration before proceeding. -
Run database migrations
npm run migrate:latest --workspace=@freedomtalk/api
-
Launch development servers
npm run dev
Your FreedomTalk instance is now running.
npm run dev # Start all packages in development mode
npm run build # Build all packages for production
npm run start # Start production servers
npm run lint # Run ESLint across all packages
npm run format # Format code with Prettier
npm run type-check # TypeScript type checking
npm run clean # Remove build artifactsnpm run docker:up # Start PostgreSQL, Redis, RabbitMQ
npm run docker:down # Stop all services
npm run docker:logs # View service logsnpm run dev --workspace=@freedomtalk/api # Development server
npm run migrate:latest --workspace=@freedomtalk/api # Run migrations
npm run migrate:make --workspace=@freedomtalk/api # Create a migration
npm run test --workspace=@freedomtalk/api # Run Vitest unit testsnpm run dev --workspace=@freedomtalk/web # Development with Turbopack
npm run build --workspace=@freedomtalk/web # Production build
npm run start --workspace=@freedomtalk/web # Production serverThe project uses Playwright for end-to-end and API-level tests, with unit tests (Vitest) inside the API package:
npm test # Full Playwright suite (API + e2e)
npm run test:api # API integration tests only
npm run test:e2e # End-to-end tests (Chromium)
npm run test:ui # Interactive Playwright UI modefreedomtalk/
├── packages/
│ ├── api/ # Backend API server (Fastify + Socket.io + mediasoup)
│ ├── web/ # Web application (Next.js)
│ ├── shared/ # Shared types, permissions, and utilities
│ ├── desktop/ # Desktop app (Electron) — experimental
│ ├── mobile/ # Mobile app (React Native) — experimental
│ └── scripts/ # DB backup/restore and maintenance scripts
├── tests/ # Playwright e2e tests
├── docs/ # Setup, architecture, product, and roadmap docs
├── docker-compose.yml
├── playwright.config.ts
└── package.json
| Service | Port | Purpose |
|---|---|---|
| PostgreSQL | 5432 | Primary database |
| Redis | 6379 | Caching, pub/sub, rate limiting |
| RabbitMQ | 5672 | Message queue |
| RabbitMQ Management | 15672 | Admin UI at http://localhost:15672 |
- Monorepo architecture with npm workspaces
- Backend API with Fastify + Socket.io
- Frontend application with Next.js
- Authentication: sessions, JWT refresh, email verification, password reset, MFA
- Servers, channels, roles, and permissions
- Real-time messaging with reactions, embeds, and attachments
- Direct messages and friends
- Search
- Webhooks, audit logs, and metrics
- API (Vitest) and end-to-end (Playwright) test suites
- Voice calling (mediasoup SFU) — experimental
- Desktop application (Electron)
- Mobile application (React Native)
- Plugin/extension system
- Self-hosting deployment guides
Documentation is organized under docs/:
- Quickstart:
docs/QUICKSTART.md - Setup and environment guides:
docs/setup - Architecture and tech stack:
docs/architecture - Product features and roadmap:
docs/productanddocs/roadmap
- Create a feature branch from
main - Implement your changes
- Run quality checks:
npm run lint && npm run type-check - Build all packages:
npm run build
- Test your changes:
npm test - Commit, push, and open a pull request
FreedomTalk — Because your conversations deserve freedom.