# How to Configure TREK Settings: UI and API Methods Explained

> Learn to configure TREK settings using the user interface or REST API. Maurice Boe's TREK repository offers detailed UI and API methods for seamless configuration.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-07-10

---

**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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/shared/src/appearance/appearance.schema.ts) (color mode, language, time format)
  - **Map**: [`shared/src/map/map.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/map/map.schema.ts) (provider selection, tokens, default view coordinates)
  - **Notifications**: [`shared/src/notifications/notifications.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/settingsService.ts).

### Fetching All Current Settings

Retrieve the complete configuration state using a valid bearer token:

```bash
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:

```bash
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:

```bash
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`](https://github.com/mauriceboe/TREK/blob/main/shared/src/map/map.schema.ts) before persisting to the database.

### Accessing Settings in Plugins

The Plugin SDK abstracts API calls for addon development:

```typescript
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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/wiki/User-Settings.md)) with seven tabs, or interact directly with [`server/src/services/settingsService.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/settingsService.ts).