docs: add authentication and deployment guides, fix broken links

Author: edmondas

docs/configuration/api.md

@@ -15,6 +15,7 @@ API settings can be configured in the `config/settings.php` file under the `api`
 | `basic_auth_realm` | `Poweradmin API` | Realm name for HTTP Basic Authentication |
 | `log_requests` | `false` | Log all API requests |
 | `docs_enabled` | `false` | Enable API documentation at /api/docs endpoint |
+| `max_keys_per_user` | `5` | Maximum API keys per user (admin users unlimited) |
 
 ## Configuration Example
 
@@ -26,6 +27,7 @@ return [
         'basic_auth_realm' => 'DNS Management API',
         'log_requests' => true,
         'docs_enabled' => true,
+        'max_keys_per_user' => 5,  // Admin users have no limit
     ],
 ];
 ```
@@ -311,5 +313,5 @@ GET /api/v1/users?page=2&limit=25
 ## Related Documentation
 
 - [Security Policies](security-policies.md) - API authentication and authorization
-- [PowerDNS Integration](powerdns-integration.md) - PowerDNS API configuration
+- [PowerDNS API](powerdns-api.md) - PowerDNS API configuration
 - [Logging Configuration](logging.md) - API request logging setup

docs/configuration/avatars.md

@@ -0,0 +1,130 @@
+# Avatar System
+
+Poweradmin v4.0.0+ supports user avatars from OAuth providers and Gravatar.
+
+## Overview
+
+The avatar system displays user profile pictures in the interface. Avatars can be sourced from:
+
+- **OAuth providers**: Profile pictures from OIDC/SAML identity providers
+- **Gravatar**: Global avatar service based on email address
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `interface.avatar_oauth_enabled` | true | Enable avatars from OAuth providers |
+| `interface.avatar_gravatar_enabled` | true | Enable Gravatar integration |
+| `interface.avatar_priority` | oauth | Priority: oauth or gravatar |
+| `interface.avatar_size` | 40 | Avatar size in pixels |
+| `interface.avatar_cache_ttl` | 3600 | Cache TTL in seconds |
+
+## Modern Configuration
+
+```php
+return [
+    'interface' => [
+        'avatar_oauth_enabled' => true,
+        'avatar_gravatar_enabled' => true,
+        'avatar_priority' => 'oauth',  // 'oauth' or 'gravatar'
+        'avatar_size' => 40,
+        'avatar_cache_ttl' => 3600,    // 1 hour
+    ],
+];
+```
+
+## Docker Configuration
+
+```yaml
+environment:
+  PA_AVATAR_OAUTH_ENABLED: "true"
+  PA_AVATAR_GRAVATAR_ENABLED: "true"
+  PA_AVATAR_PRIORITY: "oauth"
+  PA_AVATAR_SIZE: "40"
+  PA_AVATAR_CACHE_TTL: "3600"
+```
+
+## Avatar Priority
+
+The `avatar_priority` setting determines which source is checked first:
+
+- **oauth**: Check OAuth provider first, fall back to Gravatar
+- **gravatar**: Check Gravatar first, fall back to OAuth
+
+If the primary source has no avatar, the secondary source is used.
+
+## OAuth Avatars
+
+OAuth avatars are retrieved from identity providers during login:
+
+- Azure AD, Google, Keycloak, etc. provide profile pictures
+- The `picture` claim is mapped automatically
+- Avatars are cached locally to reduce provider requests
+
+### OIDC Configuration
+
+Ensure user mapping includes the avatar claim:
+
+```php
+'user_mapping' => [
+    'avatar' => 'picture',
+    // ... other mappings
+],
+```
+
+## Gravatar Integration
+
+Gravatar avatars are based on the user's email address:
+
+1. Email is hashed using MD5
+2. Avatar is fetched from `gravatar.com`
+3. Default avatar shown if no Gravatar exists
+
+Users can set their Gravatar at [gravatar.com](https://gravatar.com).
+
+### Gravatar Defaults
+
+If a user has no Gravatar, a default image is displayed. Gravatar provides several default styles:
+
+- `mp` - Mystery person silhouette
+- `identicon` - Geometric pattern
+- `monsterid` - Monster avatar
+- `wavatar` - Face avatar
+- `retro` - 8-bit style
+
+## Caching
+
+Avatars are cached to improve performance:
+
+- **Cache TTL**: Default 1 hour (3600 seconds)
+- **Cache key**: Based on user ID and source
+- **Cache invalidation**: Automatic on logout
+
+Adjust `avatar_cache_ttl` based on your needs:
+- Lower values: More frequent updates, more requests
+- Higher values: Better performance, stale avatars
+
+## Disabling Avatars
+
+To disable avatars completely:
+
+```php
+'interface' => [
+    'avatar_oauth_enabled' => false,
+    'avatar_gravatar_enabled' => false,
+],
+```
+
+## Privacy Considerations
+
+1. **Gravatar**: Sends hashed email to external service
+2. **OAuth**: Avatar URLs may be stored in session
+3. **Caching**: Avatars may be cached on server
+
+For privacy-conscious deployments, consider disabling Gravatar and relying only on OAuth avatars (which users explicitly provide to their identity provider).
+
+## Related Documentation
+
+- [OIDC Authentication](oidc.md)
+- [SAML Authentication](saml.md)
+- [UI Customization](ui/overview.md)