README

An elegant operator UI for monitoring the technical runtime state of workflows.

Waterline is for fleet health, queues, waits, retries, failures, repair, history, and runtime diagnostics. Business dashboards should read application-owned read models projected at domain milestones, with workflow_id and run_id stored only as correlation references.

Installation

Waterline uses one UI and operator behavior contract with two backend modes:

Embedded mode is the Composer package inside a Laravel application and adds the optional durable-workflow/workflow integration.
Service mode is the self-contained durableworkflow/waterline image. It needs no host PHP installation and connects to a standalone server through the published PHP SDK, never through the server database.

See Waterline service mode for the image, deployment inputs, authorization modes, persistence boundary, and Docker Compose example.

Embedded Laravel

This UI is installable via Composer.

composer require \
    "durable-workflow/waterline:^2.0@RC" \
    "durable-workflow/workflow:^2.0@RC"

php artisan waterline:install

The ^2.0@RC constraints follow the supported 2.0 prerelease channel without selecting an RC sequence number. Composer only honors prerelease stability allowances from the root project, so default-stable applications must allow both packages explicitly. The standalone PHP SDK is not part of the embedded dependency graph. Use a clean Composer solve when changing the channel, and drop the stability flags after 2.0.0 is tagged stable for both packages.

Authorization

Waterline exposes a dashboard at the /waterline URL. By default, you will only be able to access this dashboard in the local environment. However, within your app/Providers/WaterlineServiceProvider.php file, there is an authorization gate definition. This authorization gate controls access to Waterline in non-local environments.

Gate::define('viewWaterline', function ($user) {
    return in_array($user->email, [
        'admin@example.com',
    ]);
});

This will allow only the single admin user to access the Waterline UI.

Isolated observer stacks that have no application users can opt in to unauthenticated Waterline access:

WATERLINE_ALLOW_UNAUTHENTICATED=true

Configuration

Waterline can display a thin environment strip above the dashboard so production and non-production tabs are visibly distinct before an operator acts:

WATERLINE_ENV_NAME=production
WATERLINE_ENV_COLOR=#dc3545

WATERLINE_ENV_COLOR accepts hex colors. Invalid values fall back to a neutral gray.

If your workflow IDs are strings (for example UUIDs) and do not sort in a useful order, publish the config and set workflow_sort_column to a timestamp column such as created_at:

'workflow_sort_column' => 'created_at',

Operator Preferences

Waterline persists small operator view preferences through GET /waterline/api/preferences/{surface} and PUT /waterline/api/preferences/{surface}. Supported surfaces are workflow-list, run-detail, schedules-list, and workers-list; supported keys are tab, sort_direction, row_density, saved_view_id, and columns. Preferences are scoped to the authenticated Laravel user when one is available, otherwise to WATERLINE_PREFERENCES_SCOPE for local installs.

URL query parameters still win for shared links. For example, ?tab=timeline&sort=asc&density=dense&columns=workflow_id,status returns those values in effective_preferences without mutating the stored preferences.

Upgrading Waterline

When upgrading into or within the 2.0 prerelease channel, let Composer resolve the supported channel together and publish the latest assets.

composer require --with-all-dependencies \
    "durable-workflow/waterline:^2.0@RC" \
    "durable-workflow/workflow:^2.0@RC"

php artisan waterline:publish

Screenshots

The v2 branch keeps repo-owned screenshots in docs/screenshots/. They are refreshed by the Screenshots workflow and mirrored into the workflow artifact for visual review.

Dashboard

Workflow Detail

Development

Quick Start

Get a working Waterline dashboard in under 5 minutes:

# Clone and install
git clone https://github.com/durable-workflow/waterline.git
cd waterline
make install

# Start development environment (asset watch + server)
make dev

Open http://localhost:18280/waterline

The make dev command automatically:

Sets up the SQLite database with migrations
Builds and watches assets for changes
Starts the workbench server
Publishes assets to the correct location

Available Commands

Run make help to see all available commands:

make dev - Start development environment (recommended)
make install - Install dependencies
make test - Run PHPUnit test suite
make test-sqlite / make test-mysql / make test-pgsql / make test-mssql - Run tests on specific database
make clean - Clean build artifacts

Manual Setup

If you prefer to run commands manually:

Install dependencies:
```
composer install
npm ci
```
Build assets:
```
npm run production
```

Publish assets to testbench:

./vendor/bin/testbench waterline:publish

Run migrations:

./vendor/bin/testbench workbench:create-sqlite-db
./vendor/bin/testbench migrate:fresh --database=sqlite

Start server:
```
composer run serve
```
Access dashboard at http://localhost:18280/waterline

laravel-workflow / waterline

Maintainers

Package info

Statistics

Security