How to Configure TREK Settings: UI and API Methods Explained

TREK settings are configured through the web interface's tabbed Settings page or programmatically via REST API endpoints defined in server/src/services/settingsService.ts, with all values validated against JSON schemas and persisted in the SQLite app_settings table.

Configuring TREK settings involves understanding both the frontend user interface and the backend persistence layer. This guide covers how to configure TREK settings using the built-in UI panels, direct API calls, and the plugin SDK, based on the implementation in the mauriceboe/TREK repository.

Understanding the Settings Architecture

TREK employs a multi-layered architecture for settings management that separates presentation, validation, and storage. The system consists of four core components working together to ensure type-safe configuration.

Component Breakdown

• User-Settings UI – Located in wiki/User-Settings.md, this provides the Settings page interface with tabs for Display, Map, Notifications, Integrations, Offline, Account, and About. Most changes save automatically, though the Map tab requires explicit confirmation.

• Settings Service – The server/src/services/settingsService.ts file contains the core service handling all read/write operations against the app_settings table and exposing the public /api/settings endpoints.

• JSON Schemas – Validation rules live in the shared/src/ directory:

  • Appearance: shared/src/appearance/appearance.schema.ts (color mode, language, time format)
  • Map: shared/src/map/map.schema.ts (provider selection, tokens, default view coordinates)
  • Notifications: shared/src/notifications/notifications.schema.ts (email, webhook, ntfy, in-app preferences)

• Database Layer – SQLite table app_settings stores key/value pairs, initialized via migration scripts referenced in server/tests/helpers/test-db.ts.

The Settings Configuration Flow

When you configure TREK settings, the system follows a precise persistence pipeline:

1. Client fetches current values via GET /api/settings, handled by settingsService.
2. UI renders controls dynamically by reading the appropriate schema files and generating form elements (radio buttons for color modes, dropdowns for map providers).
3. User modifications trigger saves – most fields send PATCH /api/settings/:key immediately, while the Map tab batches changes into a POST /api/settings/map request when clicking "Save map settings".
4. Backend executes persistence using INSERT OR REPLACE operations into app_settings; sensitive values undergo encryption at rest (see wiki/Encryption-Key-Rotation.md).
5. Real-time synchronization occurs via WebSocket events (settings:update) broadcasting changes to all active sessions.

Configuring Settings via the Web UI

The primary method to configure TREK settings is through the browser-based interface. After logging in, navigate to the Settings page to access seven distinct configuration tabs.

Automatic vs. Explicit Saving

• Display, Notifications, Integrations, Offline, Account, About: Changes apply immediately upon selection, triggering background API calls to PATCH /api/settings/:key.
• Map Settings: Requires clicking the explicit "Save map settings" button, which bundles all map-related fields into a single POST /api/settings/map payload to prevent partial configurations.

Handling Sensitive Configuration

When a schema marks a field with secret: true (such as webhook URLs or API tokens), the UI masks the value in input fields. The backend encrypts these settings before storage, and they remain decrypted only during active sessions or authorized API reads.

Configuring Settings via the REST API

For automation, scripting, or external integrations, you can configure TREK settings using standard HTTP requests against the API endpoints defined in settingsService.ts.

Fetching All Current Settings

Retrieve the complete configuration state using a valid bearer token:

curl -s -H "Authorization: Bearer $TOKEN" \
     https://your-trek.example.com/api/settings \
| jq .

The response includes all persisted keys such as color_mode, map_provider, and notification_email.

Updating Individual Settings

Modify a specific setting by sending a PATCH request with the new value:

curl -X PATCH -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{"value":"dark"}' \
     https://your-trek.example.com/api/settings/color_mode

This follows the auto-save pattern used by most UI tabs, immediately persisting the change to the app_settings table.

Saving Complex Map Configuration

Map settings require a POST request containing the complete configuration object:

curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
           "provider":"mapbox",
           "mapbox_token":"pk.ey...",
           "center_lat":37.7749,
           "center_lng":-122.4194,
           "zoom":12
         }' \
     https://your-trek.example.com/api/settings/map

This endpoint validates the payload against shared/src/map/map.schema.ts before persisting to the database.

Accessing Settings in Plugins

The Plugin SDK abstracts API calls for addon development:

import { getSettings } from '@trek/plugin-sdk';

export async function run() {
  const settings = await getSettings();
  console.log('Current map provider:', settings.map.provider);
}

The getSettings() function automatically decrypts secret fields and merges instance-wide defaults with user-specific overrides.

Key Configuration Concepts

Understanding these concepts ensures proper configuration across different deployment scenarios.

Setting Scopes

TREK distinguishes between two storage scopes in the app_settings table:

• Global (Instance-level): Keys prefixed with admin_notif_pref_* affect all users and require administrator privileges to modify.
• Default User: Keys prefixed with default_user_setting_ establish baseline values for new user accounts.

Security and Encryption

Sensitive configuration values marked as secrets undergo encryption before storage. The encryption mechanism supports key rotation without invalidating existing settings, detailed in wiki/Encryption-Key-Rotation.md.

Authentication Method Interactions

When the server operates in OIDC-only mode (as documented in the OIDC-SSO wiki), certain account-level settings—specifically password and MFA configuration options—become hidden in the UI and restricted via API, as authentication is delegated to the identity provider.

Summary

• Configuration Interface: Use the Settings page in the web UI (defined in wiki/User-Settings.md) with seven tabs, or interact directly with server/src/services/settingsService.ts via REST API.
• Persistence Layer: All settings store in the SQLite app_settings table using INSERT OR REPLACE operations, with scopes distinguished by key prefixes (admin_notif_pref_* vs default_user_setting_).
• Validation: JSON schemas in shared/src/ directories enforce type safety for appearance, map, and notification settings.
• API Patterns: Most settings use PATCH /api/settings/:key for immediate updates, while map configuration requires POST /api/settings/map.
• Security: Secret fields encrypt at rest, and the Plugin SDK (@trek/plugin-sdk) handles decryption automatically when accessing getSettings().
• Real-time Updates: WebSocket events (settings:update) synchronize configuration changes across all active client sessions.

Frequently Asked Questions

How do I programmatically change the default map provider for all users?

To configure the default map provider instance-wide, send a PATCH request to /api/settings/map_provider with administrator credentials, or modify the default_user_setting_map_provider key directly in the app_settings table via the settingsService.ts API. Global defaults apply to new users, while existing users retain their individual preferences unless explicitly reset.

Why does the Map tab require an explicit Save button while other tabs save automatically?

The Map configuration in shared/src/map/map.schema.ts contains interdependent fields (provider selection, API tokens, coordinates) that must validate as a complete set. The explicit POST /api/settings/map endpoint ensures partial or invalid map configurations cannot persist, preventing broken map displays that would occur if coordinates saved without a valid provider token.

Where are sensitive settings like webhook URLs encrypted?

When a schema marks a field as secret: true, the settingsService.ts encrypts the value before the INSERT OR REPLACE operation into app_settings. The encryption uses instance-specific keys managed per wiki/Encryption-Key-Rotation.md. The Plugin SDK and authorized API endpoints decrypt these values on read, while the UI displays masked placeholders instead of raw text.

Can I configure TREK settings if the server uses OIDC authentication?

Yes, but with restrictions. When running in OIDC-only mode, the Account tab hides password and MFA settings since authentication is delegated to your identity provider. You can still configure all other settings (Display, Map, Notifications) via the UI or API using OIDC-derived session tokens, as implemented in the authentication middleware referenced alongside settingsService.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}