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.

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.

This UI is installable via Composer.

composer require \
    durable-workflow/waterline:2.0.0-rc.1@RC \
    durable-workflow/workflow:2.0.0-rc.1@RC \
    durable-workflow/sdk:2.0.0-rc.1@RC

php artisan waterline:install

The @RC stability flags are required while Waterline and its Durable Workflow runtime dependencies are on the 2.0 prerelease channel. Composer only honors prerelease stability allowances from the root project, so default-stable applications must allow all three packages explicitly. Drop the flags after 2.0.0 is tagged stable for all three packages.

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

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',

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.

When upgrading into or within the 2.0 prerelease channel, keep Waterline and its runtime dependencies on the supported versions shown below and publish the latest assets.

composer require --with-all-dependencies \
    durable-workflow/waterline:2.0.0-rc.1@RC \
    durable-workflow/workflow:2.0.0-rc.1@RC \
    durable-workflow/sdk:2.0.0-rc.1@RC

php artisan waterline:publish

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.

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

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

If you prefer to run commands manually:

1. Install dependencies:

   composer install
   npm ci

2. Build assets:

   npm run production

3. Publish assets to testbench:

   ./vendor/bin/testbench waterline:publish

4. Run migrations:

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

5. Start server:

   composer run serve

6. Access dashboard at http://localhost:18280/waterline