Service Tools

Strata Service Tools (SST) is a web UI for calling Strata services. It connects to your Strata backend, discovers running services, and lets you invoke any operation with a JSON payload editor. It supports saved environments, authentication, and is useful for both development and production debugging.

Installation

SST is a standalone application. Clone the repository and install dependencies:

git clone https://gitlab.com/stratajs/strata-service-tools.git
cd strata-service-tools
npm install

Setup

Environment File

Create a .env file in the project root. Use the provided .env.sample as a starting point:

cp .env.sample .env

The default sample sets ENVIRONMENT="local", which loads the local config file (no authentication required).

Configuration

SST uses YAML config files in the config/ directory. The ENVIRONMENT variable in .env determines which config file is loaded (e.g. local.yml, docker.yml).

A minimal local config:

logging:
    level: 'debug'
    prettyPrint: true

http:
    secret: 'your-session-secret'
    key: 'sst_session'
    secure: false
    port: 9090

database:
    client: 'better-sqlite3'
    connection:
        filename: './db/sst.db'
    useNullAsDefault: true
    migrations:
        directory: './dist/server/knex/migrations'
        loadExtensions: [ '.js' ]
    seeds:
        directory: './dist/server/knex/seeds'
        loadExtensions: [ '.js' ]

Running

Development (with hot module reloading):

npm run dev

Production:

npm run build
npm start

SST will be available at http://localhost:9090 (or whatever port you configured).

Authentication

Authentication is optional. For local development, leave the auth section commented out in your config and SST runs without requiring login.

Providers

SST supports two authentication providers via Passport.js:

GitLab

Works with GitLab.com or self-hosted instances.

1. In your GitLab instance, go to User Settings > Applications > New Application.
2. Set the Redirect URI to your SST callback URL (e.g. http://localhost:9090/auth/callback).
3. Select the read_user scope.
4. Save and note the Client ID and Client Secret.

auth:
    strategy: 'gitlab'
    options:
        clientID: '<your_client_id>'
        clientSecret: '<your_client_secret>'
        baseURL: 'https://gitlab.com'    # Or your self-hosted instance URL

OpenID Connect

Works with any OpenID Connect provider (Auth0, Okta, KeyCloak, etc.).

auth:
    strategy: 'openid'
    options:
        clientID: '<your_client_id>'
        clientSecret: '<your_client_secret>'
        issuer: 'https://your-provider.com/auth/realms/your-realm'
        redirectURI: 'http://localhost:9090/auth/callback'
        scope: 'openid profile email groups'

Admin Access

Admin access is used for managing system-level environments (shared across all users). There are three ways to grant admin access:

1. GitLab admin -- if using the GitLab provider, GitLab admins are automatically SST admins.
2. OpenID group -- request the groups scope and set adminGroupName in your provider options. Users in that group are admins.
3. Hardcoded list -- add email addresses to the admins list in config:

auth:
    strategy: 'openid'
    options:
        # ... provider options ...
    admins:
        - admin@example.com
        - ops@example.com

When running locally without authentication, you are automatically treated as a local admin.

Service Discovery

SST uses Strata's built-in service discovery to find running services. When you open the UI, it queries the backend for all registered service groups and their available contexts and operations. You can select a service, pick an operation, and fire off a request with a custom payload.

Configuration Reference

HTTP

Option	Type	Description
secret	string	Session secret for cookie signing.
key	string	Session cookie name.
secure	boolean	Set the secure flag on session cookies (requires HTTPS).
port	number	Port to listen on.

Database

SST uses SQLite (via better-sqlite3) for storing user sessions and saved environments. The database section is passed directly to Knex.

Logging

Option	Type	Description
level	string	Log level: trace, debug, info, warn, error, critical.
prettyPrint	boolean	Enable pino-pretty for readable logs (development only).

Examples

Calling a Service

After starting SST and opening it in a browser:

1. Select a service group from the discovery panel.
2. Choose a context and operation.
3. Enter a JSON payload in the editor.
4. Click Send and view the response.

This is equivalent to:

import { StrataClient } from '@strata-js/strata';

const client = new StrataClient({
    client: { name: 'SST' },
    backend: { type: 'redis', redis: { host: 'localhost', port: 6379 } },
});

await client.start();

const response = await client.request('UserService', 'users', 'get', {
    userId: '12345',
});

SST just gives you a browser UI for doing the same thing without writing code.

Docker Deployment

For production, use the Docker config:

# docker.yml
logging:
    level: 'info'
    prettyPrint: false

auth:
    strategy: 'gitlab'
    options:
        baseURL: $GITLAB_URL
        clientID: $GITLAB_CLIENT_ID
        clientSecret: $GITLAB_CLIENT_SECRET
        callbackURL: $CALLBACK_BASE_URL

http:
    secret: '$HTTP_SECRET'
    key: 'sst_session'
    secure: false
    port: 9090

database:
    client: 'better-sqlite3'
    connection:
        filename: './db/sst.db'
    useNullAsDefault: true
    migrations:
        directory: './dist/server/knex/migrations'
        loadExtensions: [ '.js' ]
    seeds:
        directory: './dist/server/knex/seeds'
        loadExtensions: [ '.js' ]

Set the corresponding environment variables (GITLAB_URL, GITLAB_CLIENT_ID, etc.) and run with ENVIRONMENT=docker.