likwid/docs/admin/configuration.md

# Configuration

Likwid is configured through environment variables and database settings.

## Environment Variables

### Backend

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `DATABASE_URL` | Yes | - | PostgreSQL connection string |
| `JWT_SECRET` | Yes | - | Secret for signing JWT tokens |
| `SERVER_HOST` | No | `127.0.0.1` | Bind address |
| `SERVER_PORT` | No | `3000` | HTTP port |
| `DEMO_MODE` | No | `false` | Enable demo features |
| `CORS_ALLOWED_ORIGINS` | No | - | Comma-separated allowlist of CORS origins for browsers (recommended in production) |
| `TRUSTED_PROXY_IPS` | No | - | Comma-separated allowlist of reverse proxy IPs whose `X-Forwarded-For` / `X-Real-IP` headers should be trusted |
| `RATE_LIMIT_ENABLED` | No | `true` | Enable API rate limiting |
| `RATE_LIMIT_IP_RPM` | No | `300` | Requests per minute per IP |
| `RATE_LIMIT_USER_RPM` | No | `1200` | Requests per minute per authenticated user |
| `RATE_LIMIT_AUTH_RPM` | No | `30` | Requests per minute per IP for auth endpoints (`/api/auth/login`, `/api/auth/register`) |
| `RUST_LOG` | No | `info` | Log level (trace, debug, info, warn, error) |

### Frontend

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `API_BASE` | No | `http://localhost:3000` | Backend API URL |
| `PUBLIC_API_BASE` | No | Same as API_BASE | Public-facing API URL |
| `INTERNAL_API_BASE` | No | - | Server-side API URL (e.g. `http://backend:3000` in container deployments) |

## Instance Settings

Managed via the Admin panel or API:

### General

- **Instance Name** - Display name for your Likwid instance
- **Instance Description** - Brief description
- **Registration** - Open, invite-only, or closed
- **Approval workflows** - Registration and community creation can be open, invite-only, or require admin approval

### Features

- **Community Creation** - Who can create communities
- **Public Read Access** - Allow anonymous browsing
- **Federation** - Enable cross-instance communication

### Plugins

- **Active Voting Methods** - Which methods are available
- **Default Voting Method** - Instance-wide default
- **Active Integrations** - GitLab, Matrix, etc.

## Community Settings

Each community can configure:

```json
{
  "voting_method": "schulze",
  "delegation_enabled": true,
  "require_read_before_vote": true,
  "min_discussion_days": 3,
  "quorum_percentage": 25,
  "transparency_level": "full"
}
```

### Voting Method Options

- `approval` - Approval voting
- `ranked_choice` - Instant runoff
- `schulze` - Condorcet method
- `star` - Score then automatic runoff
- `quadratic` - Voice credit allocation

### Transparency Levels

- `full` - All votes visible after closing
- `anonymous` - Only totals visible
- `private` - Results only, no breakdown

## API Configuration

### Rate Limiting

Rate limiting is configured via backend environment variables.

Behavior:

- **Window**: fixed 60s windows (counters reset every minute).
- **Scope**: applied as global Axum middleware for all routes.
- **Bypasses**:
  - `/` and `/health` (any method)
  - all `OPTIONS` requests (CORS preflight)
- **Buckets**:
  - **Auth endpoints**: `RATE_LIMIT_AUTH_RPM` is applied *per IP* for (and replaces other limiters on these routes):
    - `/api/auth/login`
    - `/api/auth/register`
  - **Per-IP**: `RATE_LIMIT_IP_RPM` is applied per IP for all other endpoints.
  - **Per-user (authenticated)**: `RATE_LIMIT_USER_RPM` is additionally applied per user *when* a valid `Authorization: Bearer <jwt>` header is present.

IP detection order:

- If the TCP peer is a trusted proxy (loopback by default, plus `TRUSTED_PROXY_IPS`):
  - `x-forwarded-for` (first IP in list)
  - `x-real-ip`
  - TCP peer address (Axum `ConnectInfo`)
- Otherwise:
  - TCP peer address (Axum `ConnectInfo`)

Responses when limited:

- **HTTP**: `429 Too Many Requests`
- **Header**: `Retry-After: <seconds>`
- **Body**: JSON `{ "error": "Rate limit exceeded" }`

Disabling:

- Set `RATE_LIMIT_ENABLED=false` to disable all rate limiting.
- Set any `*_RPM` value to `0` to disable that specific limiter.

### CORS

By default, CORS allows any origin (development-friendly). In production, set `CORS_ALLOWED_ORIGINS` to a comma-separated allowlist.

```bash
CORS_ALLOWED_ORIGINS=https://likwid.example.org
```

Multiple origins:

```bash
CORS_ALLOWED_ORIGINS=https://openlikwid.org,https://staging.openlikwid.org
```

## Logging

### Log Levels

- `trace` - Very detailed debugging
- `debug` - Debugging information
- `info` - Normal operation
- `warn` - Warning conditions
- `error` - Error conditions

### Log Format

Logs are output in JSON format for easy parsing:

```json
{"timestamp":"2026-01-27T12:00:00Z","level":"INFO","message":"Server started","port":3000}
```