System Requirements Before installing RealtimeChat, ensure your system meets these requirements:
Required
.NET 9.0 SDK or laterPostgreSQL 12+ with pg_trgm extension support4GB RAM minimum (8GB recommended for development)Operating System : Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+, Debian 10+)
Optional
Docker and Docker Compose for containerized deploymentGit for source controlIDE : Visual Studio 2022, JetBrains Rider, or VS Code with C# extension
Installing .NET 9 SDK RealtimeChat targets .NET 9.0, which requires the .NET 9 SDK.
Using Winget winget install Microsoft.DotNet.SDK.9
Using Installer
Download the .NET 9 SDK installer
Run the installer
Verify installation:
Using Homebrew Using Installer
Download the .NET 9 SDK installer
Open the .pkg file and follow the installation wizard
Verify installation:
Ubuntu/Debian # Add Microsoft package repository wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb rm packages-microsoft-prod.deb # Install .NET SDK sudo apt-get update sudo apt-get install -y dotnet-sdk-9.0
Fedora sudo dnf install dotnet-sdk-9.0
Verify installation Installing PostgreSQL RealtimeChat uses PostgreSQL for data persistence with the pg_trgm extension for full-text search.
Using Installer
Download PostgreSQL installer
Run the installer and follow the wizard
Remember the password you set for the postgres user
Ensure PostgreSQL service is running
Using Chocolatey Verify installation Using Homebrew brew install postgresql@16 brew services start postgresql@16
Using Postgres.app
Download Postgres.app
Move to Applications folder
Open and initialize
Verify installation Ubuntu/Debian sudo apt-get update sudo apt-get install postgresql postgresql-contrib sudo systemctl start postgresql sudo systemctl enable postgresql
Fedora sudo dnf install postgresql-server postgresql-contrib sudo postgresql-setup --initdb sudo systemctl start postgresql sudo systemctl enable postgresql
Verify installation Database Setup Create Database Create the database for RealtimeChat:
# Connect to PostgreSQL psql -U postgres # Create database CREATE DATABASE realtime_chat_db ; # Enable pg_trgm extension (required for message search) \c realtime_chat_db CREATE EXTENSION IF NOT EXISTS pg_trgm ; # Exit \q
The pg_trgm extension enables trigram-based text search, which is used for the message filtering feature.
For production, create a dedicated database user:
-- Create user CREATE USER realtimechat WITH PASSWORD 'your_secure_password' ; -- Grant privileges GRANT ALL PRIVILEGES ON DATABASE realtime_chat_db TO realtimechat; -- Grant schema privileges \c realtime_chat_db GRANT ALL ON SCHEMA public TO realtimechat;
Clone and Build Clone Repository git clone < repository-ur l > cd RealtimeChat
Restore Dependencies Build the Solution Configuration Connection String Edit Applications/RealtimeChat.API/appsettings.json to configure your database connection:
{ "ConnectionStrings" : { "DefaultConnectionString" : "Server=localhost;Port=5432;Username=postgres;Password=postgres;Database=realtime_chat_db;Include Error Detail=true;MaxPoolSize=10;MinPoolSize=2;" } }
Connection String Parameters:
Server: PostgreSQL host (default: localhost)Port: PostgreSQL port (default: 5432)Username: Database userPassword: User passwordDatabase: Database name (realtime_chat_db)Include Error Detail: Shows detailed errors (use true for development only)MaxPoolSize: Maximum connection pool size (default: 10)MinPoolSize: Minimum connection pool size (default: 2)
Never commit sensitive credentials to source control. Use environment variables or user secrets for production.
CORS Configuration Configure allowed origins for CORS:
{ "AllowCorsAddress" : "http://localhost:5173" }
For multiple origins, you’ll need to modify the CORS configuration in the source code.
Logging Configuration { "Logging" : { "LogLevel" : { "Default" : "Information" , "Microsoft.AspNetCore" : "Warning" } } }
Log levels: Trace, Debug, Information, Warning, Error, Critical, None
Environment-Specific Configuration Create appsettings.Development.json for development overrides:
{ "ConnectionStrings" : { "DefaultConnectionString" : "Server=localhost;Port=5432;Username=postgres;Password=postgres;Database=realtime_chat_db;Include Error Detail=true;" }, "AllowCorsAddress" : "http://localhost:5173" }
appsettings.Development.json overrides appsettings.json when ASPNETCORE_ENVIRONMENT=Development.
Using User Secrets (Recommended) For local development, use .NET user secrets to store sensitive data:
cd Applications/RealtimeChat.API # Initialize user secrets dotnet user-secrets init # Set connection string dotnet user-secrets set "ConnectionStrings:DefaultConnectionString" "Server=localhost;Port=5432;Username=postgres;Password=YOUR_PASSWORD;Database=realtime_chat_db"
User secrets are stored outside the project directory and never committed to source control.
Database Migrations Apply Migrations Run Entity Framework migrations to create the database schema:
cd Applications/RealtimeChat.API dotnet ef database update --project ../../Infrastructure/RealtimeChat.Infrastructure.DB
This creates:
Chat room tables
Message tables with JSON content support
User and authentication tables
Trigram indexes for full-text search
Create New Migration (For Development) If you modify entity models:
dotnet ef migrations add MigrationName --project ../../Infrastructure/RealtimeChat.Infrastructure.DB
View Migration History dotnet ef migrations list --project ../../Infrastructure/RealtimeChat.Infrastructure.DB
Roll Back Migration # Roll back to specific migration dotnet ef database update PreviousMigrationName --project ../../Infrastructure/RealtimeChat.Infrastructure.DB # Roll back all migrations dotnet ef database update 0 --project ../../Infrastructure/RealtimeChat.Infrastructure.DB
Running the Application Development Mode cd Applications/RealtimeChat.API dotnet run
The API will be available at:
HTTPS: https://localhost:5001
HTTP: http://localhost:5000
GraphQL endpoint: https://localhost:5001/graphql
Production Mode dotnet run --configuration Release
Custom Port dotnet run --urls "https://localhost:7001;http://localhost:7000"
Using Docker Build and run with Docker Compose:
docker-compose up --build
The Docker setup uses the ASPNETCORE_ENVIRONMENT=Docker configuration.
Verify Installation Check Application Health
Open your browser to https://localhost:5001/graphql
You should see the Banana Cake Pop GraphQL IDE
Test Database Connection Execute a simple query:
query { chatRooms { id } }
A successful response (even if empty) confirms the database connection.
Test WebSocket Connection Subscriptions use WebSockets. Test with:
subscription { onMessageUpdated { eventType } }
If the subscription starts without errors, WebSocket support is working.
Next Steps
Quick Start Run your first queries and mutations
Authentication Setup Configure Google OAuth authentication
Configuration Guide Advanced configuration options
Docker Deployment Deploy with Docker and Docker Compose
Troubleshooting .NET SDK Not Found # Verify installation dotnet --list-sdks # Should show: 9.0.x
If not listed, reinstall the .NET 9 SDK.
PostgreSQL Connection Failed # Check if PostgreSQL is running pg_isready -h localhost -p 5432 # Test connection psql -U postgres -h localhost -d realtime_chat_db
Common issues:
Wrong username/password in connection string
PostgreSQL not running
Firewall blocking port 5432
Database doesn’t exist
Install EF Core tools globally:
dotnet tool install --global dotnet-ef # Verify dotnet ef --version
Migration Errors If migrations fail:
# Check database exists psql -U postgres -c "\l" | grep realtime_chat_db # Check connection string in appsettings.json # Try dropping and recreating dotnet ef database drop --project ../../Infrastructure/RealtimeChat.Infrastructure.DB dotnet ef database update --project ../../Infrastructure/RealtimeChat.Infrastructure.DB
Port Already in Use # Find process using port 5001 lsof -i :5001 # macOS/Linux netstat -ano | findstr :5001 # Windows # Use different port dotnet run --urls "https://localhost:6001"