This page is the fastest reliable path from a fresh clone to a working local Egroo environment.

For local development, Egroo runs as:

• a PostgreSQL database
• the API and SignalR backend from src/Egroo.Server
• the Blazor web host from src/Egroo/Egroo

Default development URLs:

• API: http://localhost:5175
• Swagger: http://localhost:5175/swagger
• Web app: http://localhost:5068

Install these first:

• .NET 10 SDK
• PostgreSQL
• Git

Optional but useful:

• Visual Studio 2022 or Visual Studio Code
• pgAdmin or another PostgreSQL client
• Docker Desktop if you want container-based database or deployment workflows

git clone https://github.com/jihadkhawaja/Egroo.git
cd Egroo

Example SQL:

CREATE DATABASE egroo_local;
CREATE USER egroo_local_user WITH PASSWORD 'change-me';
GRANT ALL PRIVILEGES ON DATABASE egroo_local TO egroo_local_user;

If you prefer Docker for the database only:

docker run --name egroo-postgres \
  -e POSTGRES_DB=egroo_local \
  -e POSTGRES_USER=egroo_local_user \
  -e POSTGRES_PASSWORD=change-me \
  -p 5432:5432 \
  -d postgres:16

Edit src/Egroo.Server/appsettings.Development.json.

Minimum example:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Port=5432;User Id=egroo_local_user;Password=change-me;Database=egroo_local;"
  },
  "Secrets": {
    "Jwt": "development-jwt-secret-at-least-32-characters"
  },
  "Encryption": {
    "Key": "12345678901234567890123456789012",
    "IV": "1234567890123456"
  }
}

Notes:

• Secrets:Jwt should be at least 32 characters.
• Encryption:Key must be exactly 32 characters.
• Encryption:IV must be exactly 16 characters.
• Migrations run automatically when the API starts.

dotnet watch --project src/Egroo.Server/Egroo.Server.csproj

What to expect:

• the API listens on http://localhost:5175
• Swagger is available in development
• the database is migrated automatically on startup

Open a second terminal:

dotnet watch --project src/Egroo/Egroo/Egroo.csproj

Open http://localhost:5068 in your browser.

The UI connects to the API base URL configured in src/Egroo.UI/Constants/Source.cs. In debug builds, that value is already http://localhost:5175/.

Create an account and sign in.

Current chat delivery can use per-recipient end-to-end encrypted payloads. On first sign-in, the client can generate a device key pair locally and publish the public key to the server. The private key stays on the device.

What happens next:

1. Your browser creates a local key pair.
2. The public key and keyId are published to the server for this device.
3. Senders encrypt message content for your published key.
4. Your device decrypts received ciphertext locally.
5. After delivery succeeds, the client acknowledges the pending message so the server can remove the stored ciphertext for that recipient.

If you sign in from another browser or device, that device can publish its own key too. Egroo supports multiple active device keys for one user so encrypted delivery can work across devices.

If you later clear browser storage or move to another device, you may need to regenerate or republish the device key from the app settings before encrypted messages can be decrypted on that device.

Use this quick checklist:

1. http://localhost:5175/swagger opens.
2. http://localhost:5068 loads the web app.
3. You can create an account and sign in.
4. You can create a channel and send a test message.
5. The API console shows no database connection errors.

• Database connection failure: the connection string or PostgreSQL credentials are wrong.
• API starts but crashes immediately: the JWT or encryption settings are missing.
• Web app loads but chat fails: the API is not running on http://localhost:5175.
• Messages arrive but cannot be decrypted: the device is missing the current private key.
• Docker compose confusion: the root docker-compose-egroo.yml is not the recommended first-run path for contributors.

For fixes, see Troubleshooting.

• Installation for full setup options and Docker caveats
• Configuration for all runtime settings
• Development Setup if you plan to contribute
• Deployment if you are preparing a hosted environment