Skip to content

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.

Desktop App ​

SST is available as a standalone desktop app for macOS, Windows, and Linux. No server setup required — it bundles everything and stores data locally.

macOS ​

  1. Download and extract the .zip file
  2. Move Strata Service Tools.app to your Applications folder
  3. Before first launch, open a terminal and run:
    bash
    xattr -c "/Applications/Strata Service Tools.app"
    This clears the quarantine flag since the app is not yet code-signed.
  4. Double-click the app to launch

Windows ​

  1. Run the installer .exe
  2. Windows SmartScreen may show "Windows protected your PC" — click More info, then Run anyway
  3. The app will install and launch automatically

Linux ​

The Linux download contains all four formats. Use whichever fits your system:

AppImage (universal — recommended):

bash
chmod +x strata-service-tools-*.AppImage
./strata-service-tools-*.AppImage

Debian/Ubuntu:

bash
sudo dpkg -i strata-service-tools_*_amd64.deb

Fedora/RHEL:

bash
sudo rpm -i strata-service-tools-*.x86_64.rpm

The .zip contains the unpacked app for manual placement.


On first launch, a setup wizard walks you through connecting to your Strata backend and configuring your first environment.

Running from Source ​

If you prefer to clone and build SST yourself, or want to contribute:

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

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

yaml
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):

bash
npm run dev

Production:

bash
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.
yaml
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.).

yaml
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:
yaml
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 ​

OptionTypeDescription
secretstringSession secret for cookie signing.
keystringSession cookie name.
securebooleanSet the secure flag on session cookies (requires HTTPS).
portnumberPort 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 ​

OptionTypeDescription
levelstringLog level: trace, debug, info, warn, error, critical.
prettyPrintbooleanEnable 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:

typescript
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 ​

For production or shared team environments, SST can run as a Docker container:

yaml
# 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.