Supabase Deployment Integration

Supabase provides both authentication and object storage for deployed NodeTool instances. This guide covers how to configure Supabase as your auth and storage backend.

What Supabase Provides

Feature	What It Does
Authentication	User sign-up, login, and JWT-based session management. The server checks each token against your project’s `/auth/v1/user` endpoint
Object Storage	Asset storage in Supabase Storage buckets, with public or signed URLs

NodeTool talks to Supabase with the service role key, which bypasses Row Level Security. RLS policies do not restrict what the NodeTool server can read or write.

Prerequisites

A Supabase project at supabase.com
Your project’s URL, service role key, and anon key from the Supabase dashboard
A NodeTool deployment target (self-hosted Docker server)

Setup

1. Create Storage Buckets

In your Supabase dashboard, go to Storage and create the following buckets:

Bucket	Purpose	Visibility
`assets`	Permanent workflow assets (images, documents, audio)	Private or Public
`assets-temp`	Temporary files during workflow execution	Private

Public vs. Private buckets:

Public buckets generate direct URLs that anyone can access – suitable for assets shared externally
Private buckets require signed URLs or authenticated access – better for sensitive content

2. Configure Environment Variables

Add these variables to your deployment target’s container.environment section:

container:
  environment:
    # Supabase connection (presence of both enables Supabase auth)
    SUPABASE_URL: https://your-project.supabase.co
    SUPABASE_KEY: your-service-role-key   # server-only

    # Public key the web login screen uses. Served by GET /api/config.
    SUPABASE_ANON_KEY: your-anon-key

    # Select Supabase as the STORAGE backend (default is "file").
    # Setting only SUPABASE_URL/KEY enables Supabase AUTH but NOT storage.
    NODETOOL_STORAGE_BACKEND: supabase

    # Storage buckets
    ASSET_BUCKET: assets
    TEMP_BUCKET: assets-temp

Without SUPABASE_ANON_KEY the server logs a warning, the web app has no public key to use, and every login fails with 401. Add AUTH_REDIRECT_URL when you serve NodeTool behind a domain, and allow-list it in the Supabase project.

Or set them as environment variables directly:

export SUPABASE_URL=https://your-project.supabase.co
export SUPABASE_KEY=your-service-role-key
export SUPABASE_ANON_KEY=your-anon-key
export NODETOOL_STORAGE_BACKEND=supabase
export ASSET_BUCKET=assets
export TEMP_BUCKET=assets-temp

3. Deploy

Apply the configuration to your deployment target:

nodetool deploy apply <target-name>

apply recreates the container with the new container.environment. For Docker Compose, put the variables in .env and run docker compose up -d. See Self-Hosted Deployment.

Authentication

The server enables Supabase auth automatically when both SUPABASE_URL and SUPABASE_KEY are present. There is no AUTH_PROVIDER switch read by the server entrypoint — Supabase-vs-local auth is selected purely by the presence of those two variables. When set, NodeTool uses Supabase JWTs for all API authentication:

Users authenticate through Supabase (email/password, OAuth, magic link, etc.)
API requests require a valid JWT in the Authorization header:
```
Authorization: Bearer <supabase_jwt>
```
NodeTool validates tokens against your Supabase project automatically

When SUPABASE_URL/SUPABASE_KEY are not set, the server falls back to a local auth provider.

Storage Behavior

Backend Selection

NodeTool selects the storage backend from NODETOOL_STORAGE_BACKEND (file | s3 | supabase, default file). Any other value fails at startup:

file (default) – local filesystem under ASSET_FOLDER, then STORAGE_PATH, then the assets folder in the NodeTool data directory.
s3 – requires ASSET_BUCKET and TEMP_BUCKET. Optional S3_REGION and S3_ENDPOINT (or S3_ENDPOINT_URL).
supabase – requires SUPABASE_URL, SUPABASE_KEY, ASSET_BUCKET, and TEMP_BUCKET. A missing variable throws an error that names it.

Storage is not auto-selected from the presence of SUPABASE_URL/SUPABASE_KEY: those enable Supabase auth, but you must set NODETOOL_STORAGE_BACKEND=supabase to route storage through Supabase. The asset bucket is ASSET_BUCKET and the temp bucket is TEMP_BUCKET.

Asset URLs

Public buckets generate direct Supabase Storage URLs
Private buckets generate signed URLs that expire after 7 days (SIGNED_URL_TTL, the Supabase maximum)
For a controlled proxy layer, configure your reverse proxy to mediate access

Verification

After deploying with Supabase, verify the integration:

Check logs – Confirm the server started without a storage or auth error:
```
nodetool deploy logs <target-name>
```
Test asset storage – Run a workflow that writes assets and verify the resulting URLs point to your Supabase storage

Test authentication – Call an API endpoint with a Supabase JWT:

curl -H "Authorization: Bearer <supabase_jwt>" \
  https://your-deployment.example.com/api/workflows

Check Supabase dashboard – Verify assets appear in your storage buckets

Security Considerations

Never expose your service role key in client-side code – it has full admin access
Use Row Level Security (RLS) policies if multiple users share the same Supabase project
Rotate your service role key periodically and update deployment configs
Consider using separate Supabase projects for staging and production
See Security Hardening for the full production checklist

Deployment Guide – Overview of all deployment options
Authentication – Detailed authentication configuration
Storage – Storage backend options and configuration
Configuration – All environment variables and settings
Security Hardening – Production security checklist

Edit this page on GitHub