datasette-showboat

Datasette plugin that provides a remote viewer for Showboat documents. It receives streaming document chunks over HTTP and displays them in a live-updating web interface.

See this blog post for background on this project.

Installation

Install this plugin in the same environment as Datasette.

datasette install datasette-showboat

Usage

Once installed, the plugin adds a /-/showboat page to your Datasette instance listing all received documents, and a /-/showboat/receive endpoint for ingesting chunks.

Sending documents

Set the SHOWBOAT_REMOTE_URL environment variable to point at your Datasette instance:

export SHOWBOAT_REMOTE_URL="https://your-datasette-instance/-/showboat/receive"

The /-/showboat page will display the correct URL for your instance including the hostname.

Permissions

Viewing showboat documents requires the showboat permission. By default this is denied to anonymous users — only the root user (when Datasette is started with --root) has access automatically.

To grant access to specific users, add to your datasette.yaml:

permissions:
  showboat:
    id: your-username

Or to allow all authenticated users:

permissions:
  showboat:
    id: "*"

The receive endpoint (/-/showboat/receive) does not require the showboat permission — it uses token authentication instead (see below).

Token authentication

To protect the receive endpoint, configure a secret token in your datasette.yaml (or metadata.yaml):

plugins:
  datasette-showboat:
    token: your-secret-token

When a token is configured, all requests to /-/showboat/receive must include it as a query parameter:

export SHOWBOAT_REMOTE_URL="https://your-datasette-instance/-/showboat/receive?token=your-secret-token"

Without a configured token, the receive endpoint accepts all POST requests.

Custom database

By default chunks are stored in Datasette's internal database. To use a named database instead:

plugins:
  datasette-showboat:
    database: my_database

Development

To set up this plugin locally, first checkout the code. You can confirm it is available like this:

cd datasette-showboat
# Confirm the plugin is visible
uv run datasette plugins

To run the tests:

uv run pytest