Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

.NET 9 SDK

Required for building and running the application

PostgreSQL

Database server for data persistence

Docker (Optional)

For containerized deployment
This guide will get you running locally in development mode. For production deployment, see the Docker Deployment Guide.

​
Getting Started

1

Clone the repository

Clone the RealtimeChat repository to your local machine:
git clone <repository-url>
cd RealtimeChat
2

Set up PostgreSQL

Ensure PostgreSQL is running on your system. The default configuration expects:
  • Host: localhost
  • Port: 5432
  • Username: postgres
  • Password: postgres
  • Database: realtime_chat_db
Create the database:
psql -U postgres -c "CREATE DATABASE realtime_chat_db;"
If your PostgreSQL setup differs, you’ll need to update the connection string in appsettings.json.
3

Configure the application

Navigate to the API project directory:
cd Applications/RealtimeChat.API
The default appsettings.json configuration:
{
  "ConnectionStrings": {
    "DefaultConnectionString": "Server=localhost;Port=5432;Username=postgres;Password=postgres;Database=realtime_chat_db;Include Error Detail=true;MaxPoolSize=10;MinPoolSize=2;"
  },
  "AllowCorsAddress": "http://localhost:5173"
}
For development, you can use appsettings.Development.json to override settings without modifying the base configuration.
4

Run database migrations

Apply the Entity Framework migrations to set up the database schema:
dotnet ef database update --project ../../Infrastructure/RealtimeChat.Infrastructure.DB
This creates all necessary tables including:
  • Chat rooms and participants
  • Messages with full-text search indexes
  • User authentication tables
5

Start the application

Run the API server:
dotnet run
The API will start on https://localhost:5001 (or the port specified in your launch settings).You should see output similar to:
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
6

Test the GraphQL endpoint

Open your browser and navigate to the GraphQL endpoint:
https://localhost:5001/graphql
You’ll see the Banana Cake Pop GraphQL IDE provided by HotChocolate.

​
Your First Query

Once the application is running, try executing your first GraphQL query:

​
Fetch All Chat Rooms

query GetChatRooms {
  chatRooms {
    id
    name
    createdAt
  }
}

​
Fetch Messages from a Chat Room

query GetMessages($chatRoomId: Int!) {
  messages(chatRoomId: $chatRoomId) {
    id
    content {
      text
    }
    senderId
    sentAt
  }
}
Variables: 
{
  "chatRoomId": 1
}

​
Send a Message

mutation SendMessage($chatRoomId: Int!, $senderId: String!, $text: String!) {
  sendMessage(chatRoomId: $chatRoomId, senderId: $senderId, text: $text) {
    id
    content {
      text
    }
    sentAt
  }
}
Variables: 
{
  "chatRoomId": 1,
  "senderId": "user123",
  "text": "Hello from RealtimeChat!"
}

​
Subscribe to Message Updates

To receive real-time updates when messages are added, edited, or deleted: 
subscription OnMessageUpdated {
  onMessageUpdated {
    eventType
    message {
      id
      content {
        text
      }
      senderId
      chatRoomId
      sentAt
    }
  }
}
The subscription will emit events with eventType values:
  • ADDED - New message sent
  • UPDATED - Message edited
  • DELETED - Message removed

​
Exploring the API

The GraphQL IDE provides:
  • Schema Explorer: Browse all available queries, mutations, and subscriptions
  • Documentation: Auto-generated docs for all types and operations
  • Query History: Access previously executed queries
  • Variables Panel: Test queries with different input values
Use the Schema tab in Banana Cake Pop to explore the complete API surface, including all available fields and their types.

​
Next Steps

Installation Guide

Learn about detailed configuration options and environment setup

Authentication

Set up Google OAuth and user authentication

API Reference

Explore the complete GraphQL API documentation

Docker Deployment

Deploy RealtimeChat using Docker containers

​
Troubleshooting

​
Database Connection Failed

If you see connection errors, verify:
  1. PostgreSQL is running: pg_isready
  2. Database exists: psql -U postgres -l | grep realtime_chat_db
  3. Connection string in appsettings.json matches your PostgreSQL setup

​
Migration Errors

If migrations fail: 
# Reset the database and reapply migrations
dotnet ef database drop --project ../../Infrastructure/RealtimeChat.Infrastructure.DB
dotnet ef database update --project ../../Infrastructure/RealtimeChat.Infrastructure.DB
This will delete all data in the database. Only use in development.

​
Port Already in Use

If the default port is occupied, specify a different port: 
dotnet run --urls "https://localhost:5002"

Build docs developers (and LLMs) love

Get started for freeTalk to us