RedWizardsLab/EchoHub
1
0
Fork 0
mirror of https://github.com/RedWizardsLab/EchoHub.git synced 2026-09-04 08:36:11 +02:00
Code Issues 2 Packages Projects Releases 10 Wiki Activity

docs: add configuration guide and update related documentation

Browse Source
This commit is contained in:
HueByte
2026-02-24 23:07:41 +01:00
parent ae342381e0
commit 5d61266fd7
12 changed files with 163 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/articles/configuration.md
+152
View File
@@ -0,0 +1,152 @@
# Configuration
EchoHub Server generates an `appsettings.json` with sensible defaults on first run (including a random JWT secret), so you can launch and start chatting immediately. Tweak things later when you feel like it.
> [!NOTE]
> Under the hood, EchoHub Server is built on ASP.NET Core, so it inherits the standard .NET configuration system. If you're familiar with that, everything works exactly as you'd expect. If not — no worries, this page covers everything you need.
## How It Works
EchoHub Server loads settings from multiple sources. Each source **overrides** the previous one, so you can layer defaults with environment-specific values:
```text
1. appsettings.json (base defaults)
2. appsettings.{Environment}.json (e.g. appsettings.Production.json)
3. Environment variables (great for Docker / CI)
4. Command-line arguments (highest priority)
```
The last one wins. If `appsettings.json` says `"Irc:Port": 6667` but you pass `--Irc:Port=7000` on the command line, port 7000 is what you get.
In practice this means you can leave `appsettings.json` alone and override just the settings you care about using environment variables or CLI flags — no need to edit JSON files if that's not your thing.
### Environment Variable Mapping
Environment variables use **double underscores** (`__`) in place of the JSON nesting. The rule is simple — replace every `:` (or each level of JSON nesting) with `__`:
| appsettings.json path | Environment variable |
| --- | --- |
| `Server:Name` | `Server__Name` |
| `Irc:Enabled` | `Irc__Enabled` |
| `Jwt:Secret` | `Jwt__Secret` |
| `Serilog:MinimumLevel:Default` | `Serilog__MinimumLevel__Default` |
| `ConnectionStrings:DefaultConnection` | `ConnectionStrings__DefaultConnection` |
Arrays use numeric indices: `Server:Admins:0` becomes `Server__Admins__0`, `Server:Admins:1` becomes `Server__Admins__1`, and so on.
This is why the Docker `.env` file uses `Server__Name=My Server` instead of JSON — Docker passes these as environment variables, and the server picks them up automatically.
### Examples
All three of these achieve the same thing — use whichever fits your setup.
**appsettings.json** (direct editing):
```json
{
"Server": {
"Name": "My EchoHub Server",
"PublicServer": true
}
}
```
**Environment variables** (Docker, systemd, shell export):
```bash
export Server__Name="My EchoHub Server"
export Server__PublicServer=true
```
**Command-line arguments** (quick overrides, highest priority):
```bash
./EchoHub.Server --Server:Name="My EchoHub Server" --Irc:Enabled=true
```
## Configuration Reference
The full `appsettings.json` is auto-generated on first run from the [example config](https://github.com/HueByte/EchoHub/blob/master/src/EchoHub.Server/appsettings.example.json). Here's every option:
### General
| Key | Default | Description |
| --- | --- | --- |
| `Urls` | `http://0.0.0.0:5000` | Listen address and port |
| `AllowedHosts` | `*` | Allowed host headers (leave `*` unless you need host filtering) |
### Database
| Key | Default | Description |
| --- | --- | --- |
| `ConnectionStrings:DefaultConnection` | *(empty)* | SQLite connection string. Empty = `echohub.db` in the app directory |
### Authentication
| Key | Default | Description |
| --- | --- | --- |
| `Jwt:Secret` | *(auto-generated)* | Signing key (min 32 chars). Auto-generated on first run |
| `Jwt:Issuer` | `EchoHub.Server` | JWT issuer claim |
| `Jwt:Audience` | `EchoHub.Client` | JWT audience claim |
Access tokens expire after 15 minutes, refresh tokens after 30 days with rotation on each use.
### Server Identity
| Key | Default | Description |
| --- | --- | --- |
| `Server:Name` | `My EchoHub Server` | Display name shown to clients |
| `Server:Description` | `A self-hosted EchoHub chat server` | Server description |
| `Server:PublicServer` | `false` | Register on the [public directory](https://echohub.voidcube.cloud/servers) |
| `Server:PublicHost` | *(empty)* | Public hostname for the directory listing (e.g. `chat.example.com:5000`) |
| `Server:Admins` | `[]` | Array of admin usernames (e.g. `["alice", "bob"]`) |
### Encryption
| Key | Default | Description |
| --- | --- | --- |
| `Encryption:Key` | *(auto-generated)* | AES key for message encryption in transit |
| `Encryption:EncryptDatabase` | `false` | Also encrypt message content at rest in SQLite |
### Storage
| Key | Default | Description |
| --- | --- | --- |
| `Storage:CleanupIntervalHours` | `1` | How often the cleanup job runs (hours) |
| `Storage:RetentionDays` | `30` | Days to keep uploaded files before cleanup |
### IRC Gateway
| Key | Default | Description |
| --- | --- | --- |
| `Irc:Enabled` | `false` | Enable the IRC protocol gateway |
| `Irc:Port` | `6667` | IRC plain-text listen port |
| `Irc:TlsEnabled` | `false` | Enable TLS termination for IRC |
| `Irc:TlsPort` | `6697` | IRC TLS listen port |
| `Irc:TlsCertPath` | *(empty)* | Path to a PKCS#12 (`.pfx`) certificate |
| `Irc:TlsCertPassword` | *(empty)* | Password for the certificate file |
| `Irc:ServerName` | `echohub` | IRC server name in protocol messages |
| `Irc:Motd` | `Welcome to EchoHub IRC Gateway!` | Message of the day |
### Logging
EchoHub uses [Serilog](https://serilog.net/) for structured logging — console output + daily rolling files with 14-day retention by default.
| Key | Default | Description |
| --- | --- | --- |
| `Serilog:MinimumLevel:Default` | `Information` | Global log level (`Debug`, `Information`, `Warning`, `Error`) |
| `Serilog:MinimumLevel:Override:Microsoft` | `Warning` | Suppress noisy framework logs |
| `Serilog:MinimumLevel:Override:Microsoft.AspNetCore` | `Warning` | Suppress request pipeline logs |
| `Serilog:MinimumLevel:Override:Microsoft.EntityFrameworkCore` | `Warning` | Suppress database query logs |
Log files are written to `logs/echohub-server-YYYY-MM-DD.log`. To change the path or retention, edit the `Serilog:WriteTo` section in `appsettings.json`.
Want more verbose output for debugging? Set the minimum level to `Debug`:
```bash
# via environment variable
export Serilog__MinimumLevel__Default=Debug
# or command line
./EchoHub.Server --Serilog:MinimumLevel:Default=Debug
```
docs/articles/docker.md
+5 -14
View File
@@ -24,26 +24,17 @@ services:
## Configuration
All settings are configured through the `.env` file. These are ASP.NET Core environment variables that override `appsettings.json`.
All settings are configured through the `.env` file. These are environment variables that override `appsettings.json` — the `__` (double underscore) maps to JSON nesting levels. For example, `Server__Name` overrides the `Server:Name` key in `appsettings.json`.
See the [Configuration](configuration.md) guide for the full reference of all available settings and how the override hierarchy works.
Common Docker-relevant variables:
| Variable | Default | Description |
| --- | --- | --- |
| `Server__Name` | My EchoHub Server | Display name for your server |
| `Server__Description` | A self-hosted EchoHub chat server | Server description |
| `Server__PublicServer` | `false` | List on the [public directory](https://echohub.voidcube.cloud/servers) |
| `Server__PublicHost` | *(empty)* | Public address for the directory listing |
| `Server__Admins__0` | *(empty)* | Admin username (use `__1`, `__2` for more) |
| `Jwt__Secret` | *(auto-generated)* | JWT signing key. Auto-generated on first run |
| `Encryption__Key` | *(auto-generated)* | AES encryption key. Auto-generated on first run |
| `Encryption__EncryptDatabase` | `false` | Encrypt message content in the database |
| `Storage__CleanupIntervalHours` | `1` | How often to clean expired uploads |
| `Storage__RetentionDays` | `30` | Days to keep uploaded files |
| `Irc__Enabled` | `false` | Enable the IRC gateway |
| `Irc__Port` | `6667` | IRC plain-text port |
| `Irc__TlsEnabled` | `false` | Enable IRC over TLS |
| `Irc__TlsPort` | `6697` | IRC TLS port |
| `Irc__ServerName` | `echohub` | IRC server name shown to clients |
| `Irc__Motd` | Welcome to EchoHub IRC Gateway! | Message of the day |
| `Serilog__MinimumLevel__Default` | `Information` | Log level (`Debug`, `Warning`, etc.) |
## Persistent Data
docs/articles/getting-started.md
+2 -2
View File
@@ -84,9 +84,9 @@ See the [Architecture](architecture.md) page for details on how the IRC gateway
## Configuration
Server configuration is in `appsettings.json` (auto-generated on first run). See the [example config](https://github.com/HueByte/EchoHub/blob/master/src/EchoHub.Server/appsettings.example.json) for all available options.
Server configuration is in `appsettings.json` (auto-generated on first run). You can also use environment variables or command-line arguments to override settings.
To list your server on the [public directory](https://echohub.voidcube.cloud/servers), set `Server:PublicServer` to `true` and `Server:PublicHost` to your server's public address.
See the [Configuration](configuration.md) guide for the full reference and how it all works.
## Build from Source
docs/articles/toc.yml
+2
View File
@@ -6,6 +6,8 @@
href: docker.md
- name: Architecture
href: architecture.md
- name: Configuration
href: configuration.md
- name: Encryption
href: encryption.md
- name: Notification Sounds