### Install Dependencies and Serve Frontend

Source: https://github.com/bluesky/tiled/blob/main/web-frontend/README.md

Navigate to the web-frontend directory, install npm dependencies, and start the development server. The frontend will be accessible at http://localhost:5173.

```bash
cd web-frontend
npm install
npm run serve
```

--------------------------------

### Full PAM Configuration Example

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/security.md

A complete configuration file example for PAM authentication, including provider setup and tree definition.

```yaml
# pam_config.yml
authentication:
  providers:
    - authenticator: tiled.authenticators:PAMAuthenticator
      # This 'provider' can be any string; it is used to differentiate
      # authentication providers when multiple ones are supported.
      provider: local
trees:
  - path: /
    tree: tiled.examples.generated_minimal:tree
```

--------------------------------

### Start Tiled Demo Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/http-api-overview.md

Start the Tiled server with the demo Tree locally. Navigate to http://localhost:8000/docs in your browser to access the interactive documentation.

```bash
tiled serve demo
```

--------------------------------

### Start a Local Tiled Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/10-minutes-to-tiled.md

Launches a local Tiled server with embedded storage and basic security. For persistent storage, provide a directory path. This setup is for personal use and small experiments, not production.

```python
from tiled.client import simple

c = simple()
```

--------------------------------

### Launch Example Tiled Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/access-control.md

Command to launch the example Tiled server with specified user passwords and configuration. This loads the prepared databases and access control settings.

```bash
# launch the example server, which loads these databases
ALICE_PASSWORD=secret1 BOB_PASSWORD=secret2 CARA_PASSWORD=secret3 tiled serve config example_configs/toy_authentication.yml
```

--------------------------------

### Start Tiled Server with Toy Authentication

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/api-keys.md

Start a Tiled server with a simple authentication provider for testing. Ensure you have run the helper scripts to prepare the necessary databases.

```bash
# You can find example_configs/ in the root of the tiled source code repository.
ALICE_PASSWORD=secret1 tiled serve config example_configs/toy_authentication.yml
```

```bash
# prep the access tags and catalog databases
python example_configs/access_tags/compile_tags.py
python example_configs/catalog/create_catalog.py
```

--------------------------------

### Run Docker Compose Example

Source: https://github.com/bluesky/tiled/blob/main/monitoring_example/README.md

Clone the tiled repository and run this command from the root directory to start a complete working example with monitoring enabled. Ensure the TILED_SINGLE_USER_API_KEY matches the secret in prometheus/prometheus.yml.

```bash
TILED_SINGLE_USER_API_KEY=secret docker-compose up
```

--------------------------------

### Example Server Configuration (YAML)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/example-server-config.md

This is an example server configuration file in YAML format. It outlines various settings for server operation.

```yaml
server:
  port: 8080

logging:
  level: INFO

database:
  type: postgresql
  host: localhost
  port: 5432
  username: user
  password: password
  db_name: tiled

authentication:
  jwt_secret: "a-very-secret-key"
  token_expiry: "1h"

# Example of a custom configuration parameter
custom_setting:
  value: "some_value"
```

--------------------------------

### Install Tiled Helm Chart

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/helm.md

Installs the Tiled Helm chart with default values. This is a quickstart for a basic setup.

```bash
helm install tiled oci://ghcr.io/bluesky/charts/tiled
```

--------------------------------

### Install and Use Tiled Python Client

Source: https://github.com/bluesky/tiled/blob/main/share/tiled/templates/index.html

Install the Tiled client and import it in a Python session to connect to a Tiled server. Ensure you have the necessary dependencies installed.

```bash
$ pip install "tiled[client]"
```

```python
from tiled.client import from_uri
client = from_uri("{{ root_url }}")
```

--------------------------------

### Start Tiled Server with OIDC

Source: https://github.com/bluesky/tiled/blob/main/example_configs/simple_oidc/README.md

Start the Tiled server with environment variables pointing to the local OIDC provider. Ensure the OIDC_BASE_URL, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET match the provider's configuration.

```bash
OIDC_BASE_URL=http://localhost:9000 OIDC_CLIENT_ID=example_client_id OIDC_CLIENT_SECRET=example_client_secret tiled serve config config.yml
```

--------------------------------

### Start Basic Tiled Server

Source: https://github.com/bluesky/tiled/blob/main/locust/README.md

Starts a basic Tiled server for testing purposes. It runs on all interfaces, port 8000, uses a 'secret' API key, and creates a temporary catalog.

```bash
# Basic server (works for most tests)
uv run tiled serve catalog \
  --host 0.0.0.0 \
  --port 8000 \
  --api-key secret \
  --temp \
  --init
```

--------------------------------

### Run Tiled with Custom Configuration

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/docker.md

Starts the Tiled server, overriding the default configuration by mounting a local 'config' directory to '/deploy/config' within the container. This example does not specify a network, implying the default bridge network.

```bash
docker run \
  -p 8000:8000 \
  -e TILED_SINGLE_USER_API_KEY=secret \
  -v ./config:/deploy/config:ro \
  ghcr.io/bluesky/tiled:latest
```

--------------------------------

### Start Tiled Server with Directory Catalog

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/register.md

Use this command to start a Tiled server with a persistent database and register files from a specified directory. The database can be a SQLite file or a PostgreSQL URI. The directory specified with `-r` is the only one from which clients can register files.

```bash
tiled serve catalog <DATABASE_URI> -r <DIRECTORY> [--public] [--api-key <SECRET>]
```

--------------------------------

### Serve Data Using a Configuration File

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/configuration.md

Start the Tiled server and specify the path to a single configuration file.

```bash
tiled serve config my_config_file.yml
```

--------------------------------

### Start Demo Server with CORS Enabled

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/integrations/zarr.md

To allow Tiled servers to accept requests from web applications like vizarr, declare the web application's domain in the `allow_origins` configuration. This example shows how to start the demo server with a specific origin.

```bash
TILED_ALLOW_ORIGINS='["https://hms-dbmi.github.io"]' tiled serve demo
```

--------------------------------

### Install PAM Dependency

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/security.md

Install the necessary dependency for PAM authentication.

```bash
pip install pamela
```

--------------------------------

### Serve Tiled with PAM Configuration

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/security.md

Command to start the Tiled server using a PAM configuration file.

```bash
tiled serve config pam_config.yml
```

--------------------------------

### Serve Tiled Configuration

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/custom-export-formats.md

Command to start the Tiled server using a custom configuration file.

```bash
tiled serve config --public config.yml
```

--------------------------------

### Serve Data Using a Configuration Directory

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/configuration.md

Start the Tiled server and specify the path to a directory containing multiple configuration files.

```bash
tiled serve config my_config_directory/
```

--------------------------------

### Install OIDC Dependency

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/security.md

Install the necessary dependency for OpenID Connect authentication.

```bash
pip install httpx
```

--------------------------------

### Start Tiled Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/docker.md

Starts the Tiled server in a Docker container, connecting it to the 'tilednet' network. It maps port 8000, sets API keys and database credentials, and mounts local directories for configuration and data.

```bash
docker run \
  --net=tilednet \
  -p 8000:8000 \
  -e TILED_SINGLE_USER_API_KEY=secret \
  -e TILED_DATABASE_PASSWORD=${TILED_DATABASE_PASSWORD} \
  -v ./config:/deploy/config:ro \
  -v ./data:/data:ro \
  ghcr.io/bluesky/tiled:latest
```

--------------------------------

### Install Tiled with pip

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/index.md

Install the Tiled library and all its dependencies using pip within a virtual environment.

```shell
python3 -m pip install "tiled[all]"
```

--------------------------------

### Example Tiled Single User Configuration

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/deploy-tiled-single-node.md

An example YAML configuration file for a single-user Tiled catalog. This configuration specifies persistent storage locations and authentication settings.

```yaml
server:
  port: 8000

storage:
  # Use PostgreSQL for metadata and appendable tabular data
  catalog_database: postgresql://tiled:password@localhost:5432/tiled
  appendable_tables: postgresql://tiled:password@localhost:5432/tiled

  # Use local directory for file-based data storage
  # This is a path on the server's filesystem.
  # It can be a relative path (like here) or an absolute path.
  blobs: ./storage/data

authentication:
  # Use a single API key for authentication
  # This is suitable for single-user deployments.
  authenticator: tiled.authenticators.SingleUserAuthenticator
  single_user_api_key: "secret"

# Optional: Use Redis for live data streaming
# streaming:
#   redis_url: redis://:password@localhost:6379

```

--------------------------------

### Serve a Directory of Files (Quick Start)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/docker.md

Runs a Tiled server container that serves files from a local './data' directory mounted as read-only. This method re-indexes files on server startup and is not suitable for scaling.

```bash
docker run \
  -p 8000:8000 \
  -e TILED_SINGLE_USER_API_KEY=secret \
  -v ./data:/data:ro \
  ghcr.io/bluesky/tiled:latest \
  tiled serve directory --host 0.0.0.0 /data
```

--------------------------------

### Start Tiled Server with Redis Cache

Source: https://github.com/bluesky/tiled/blob/main/locust/README.md

Starts a Tiled server with Redis cache enabled for enhanced streaming performance. Ensure Redis is running separately before executing this command.

```bash
# Start Redis first
redis-server

# Start Tiled server with Redis cache
uv run tiled serve catalog \
  --host 0.0.0.0 \
  --port 8000 \
  --api-key secret \
  --cache "redis://localhost:6379" \
  --cache-ttl 60 \
  --temp \
  --init
```

--------------------------------

### Create Example Files for Registration

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/10-minutes-to-tiled.md

Generates sample data files (TIFF images) in a specified directory, preparing them to be registered with Tiled.

```python
from pathlib import Path
import numpy as np
import pandas as pd
import tifffile

# Create directory.
dir = Path('external_data')
dir.mkdir(exist_ok=True)

# Write an image stack of TIFFs.
for i in range(10):
    tifffile.imwrite(f'external_data/image_stack{i:03}.tiff', np.random.random((5, 5)))
```

--------------------------------

### Complete Public Server Configuration Example

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/security.md

A complete YAML configuration file to launch a Tiled server in public mode, specifying the authentication setting and the root tree.

```yaml
# config.yml
authentication:
  allow_anonymous_access: true
trees:
  - path: /
    tree: tiled.examples.generated_minimal:tree

```

--------------------------------

### Serve Tiled Catalog with Configuration File

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/deploy-tiled-single-node.md

Starts a Tiled catalog server using a specified configuration file. This is useful for complex configurations like multi-user authentication.

```sh
tiled serve config path/to/config.yml
```

--------------------------------

### Start Tiled Server for Plotly

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/integrations/plotly.md

Start the Tiled server, allowing requests from the Plotly Chart Studio frontend. Ensure the TILED_ALLOW_ORIGINS environment variable is set correctly.

```bash
TILED_ALLOW_ORIGINS='["https://chart-studio.plotly.com"]' tiled serve pyobject --public tiled.examples.generated:tree
```

--------------------------------

### Start Secure Single-User Tiled Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/security.md

This command starts a Tiled server in secure single-user mode, generating a unique API key for access. The URL includes the generated API key for initial connection.

```bash
$ tiled serve pyobject tiled.examples.generated_minimal:tree

    Use the following URL to connect to Tiled:

    "http://127.0.0.1:8000?api_key=a4062c3dd6ab2af0d28fdb7eb278dd985c462ecf08d39f33233554c7fdaa42e7"

```

--------------------------------

### Example of YAML profile configuration

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/profiles.md

This YAML snippet demonstrates how to define a profile with advanced options, including nested service-side configuration under the `direct:` key.

```yaml
my_profile:
   direct:
      service_directory: "/path/to/my/data"
      driver: "json"
   client_directory: "/path/to/my/data"
```

--------------------------------

### Create and Activate Virtual Environment (pip)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/index.md

Set up an isolated Python environment for Tiled installation using venv.

```shell
python3 -m venv ./venv
source ./venv/bin/activate
```

--------------------------------

### Start Tiled Server for Development

Source: https://github.com/bluesky/tiled/blob/main/web-frontend/README.md

Run the Tiled server with specific origin allowances for the React development server. This command enables cross-origin requests from the frontend.

```bash
TILED_ALLOW_ORIGINS='["http://localhost:5173"]' tiled serve demo --public
```

--------------------------------

### Serve Tiled Catalog with Fixed API Key (Development)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/deploy-tiled-single-node.md

Starts a Tiled catalog server using temporary storage and a fixed API key. This is convenient for development but should not be used on production servers.

```sh
tiled serve catalog --temp --api-key secret
```

--------------------------------

### Tiled Environment File Example

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/deploy-tiled-single-node.md

A template for the `.env` file used by Tiled. This file should contain secure secrets for the Tiled services.

```yaml
TILED_SINGLE_USER_API_KEY=""
POSTGRES_PASSWORD=""
REDIS_PASSWORD=""
TILED_TOKEN_SECRET=""

```

--------------------------------

### Serve Data Using Default Configuration File

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/configuration.md

Start the Tiled server without specifying a configuration path. It will attempt to use './config.yml' if the TILED_CONFIG environment variable is unset.

```bash
tiled serve config  # uses ./config.yml if environment variable TILED_CONFIG is unset
```

--------------------------------

### Run Tiled with Persistent Storage (Podman)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/deploy-tiled-single-node.md

Starts a Tiled server using Podman with persistent storage. It mounts the local 'storage' directory and uses specific options (`--userns=keep-id`, `--group-add`) to ensure the container can write to the mounted volume.

```sh
echo "TILED_SINGLE_USER_API_KEY=$(openssl rand -hex 32)" >> .env
podman run -p 8000:8000 --env-file .env -v ./storage:/storage --userns=keep-id --group-add $(id -g) ghcr.io/bluesky/tiled:latest
```

--------------------------------

### Compile Tags and Create Catalog

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/access-control.md

Python scripts to prepare the access tags and catalog databases for the example Tiled server. These commands must be run before launching the server.

```bash
# prep the access tags and catalog databases
python example_configs/access_tags/compile_tags.py
python example_configs/catalog/create_catalog.py
```

--------------------------------

### Run Tiled with Persistent Storage (Docker)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/deploy-tiled-single-node.md

Starts a Tiled server using Docker, mounting a local 'storage' directory to persist data and metadata. A secure API key is generated.

```sh
echo "TILED_SINGLE_USER_API_KEY=$(openssl rand -hex 32)" >> .env
docker run -p 8000:8000 --env-file .env -v ./storage:/storage ghcr.io/bluesky/tiled:latest
```

--------------------------------

### Run a Read-Only Public Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/configuration.md

Use this command to start a simple read-only public server for existing data in a specified directory.

```bash
tiled serve directory --public files/
```

--------------------------------

### Run a Temporary Writable Catalog

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/configuration.md

This command starts a temporary writable catalog. Data will not persist after the server stops.

```bash
tiled serve catalog --temp
```

--------------------------------

### Start a Tiled server with webhooks enabled

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/webhooks.md

Initializes a SimpleTiledServer with webhook support enabled. This automatically generates a signing secret and allows localhost URLs for webhook targets.

```python
from tiled.server import SimpleTiledServer
from tiled.client import from_uri

server = SimpleTiledServer(enable_webhooks=True)
client = from_uri(server.uri)

print(f"Tiled server running at {server.uri}")
```

--------------------------------

### Run Scalable Tiled Server with Persistent Catalog

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/docker.md

Starts a Tiled server container that uses persistent storage for its catalog. It mounts local './data' as read-only and './storage' for catalog persistence.

```bash
mkdir storage/

docker run \
  -p 8000:8000 \
  -e TILED_SINGLE_USER_API_KEY=secret \
  -v ./data:/data:ro \
  -v ./storage:/storage \
  ghcr.io/bluesky/tiled:latest
```

--------------------------------

### Serve Data Using Configuration via Environment Variable (File)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/configuration.md

Set the TILED_CONFIG environment variable to point to your configuration file before starting the Tiled server.

```bash
TILED_CONFIG=my_config_file.yml tiled serve config
```

--------------------------------

### Start Local OIDC Provider

Source: https://github.com/bluesky/tiled/blob/main/example_configs/simple_oidc/README.md

Run the simple OIDC provider in a Docker container. Mounts the current directory for configuration files and exposes port 9000.

```bash
docker run --rm -p 9000:9000 -v $(pwd):/config -e CONFIG_FILE=/config/oidc_provider_config.json -e USERS_FILE=/config/users.json docker.io/qlik/simple-oidc-provider:0.2.4
```

--------------------------------

### Set up a local HTTP receiver

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/webhooks.md

Starts a simple HTTP server on a background thread to capture incoming webhook POST requests. This is useful for local development and testing.

```python
import json
import threading
from http.server import BaseHTTPRequestHandler, HTTPServer

received = []  # payloads land here


class _Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length", 0))
        received.append(json.loads(self.rfile.read(length)))
        self.send_response(200)
        self.end_headers()

    def log_message(self, *args):
        pass  # silence per-request logs


receiver = HTTPServer(("127.0.0.1", 0), _Handler)
receiver_port = receiver.server_address[1]
threading.Thread(target=receiver.serve_forever, daemon=True).start()

print(f"Receiver listening on http://127.0.0.1:{receiver_port}/hook")
```

--------------------------------

### Tiled Database Initialization Script

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/deploy-tiled-single-node.md

A shell script to initialize the Tiled catalog and storage databases when PostgreSQL starts for the first time. This script should be placed in the `initdb/` directory.

```sh
set -e

# Initialize Tiled catalog database
psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
    CREATE SCHEMA IF NOT EXISTS tiled;
    GRANT ALL PRIVILEGES ON SCHEMA tiled TO tiled;
EOSQL

# Initialize Tiled storage database (appendable tabular data)
psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
    CREATE SCHEMA IF NOT EXISTS tiled_storage;
    GRANT ALL PRIVILEGES ON SCHEMA tiled_storage TO tiled;
EOSQL

```

--------------------------------

### Serve Data Using Configuration via Environment Variable (Directory)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/configuration.md

Set the TILED_CONFIG environment variable to point to your configuration directory before starting the Tiled server.

```bash
TILED_CONFIG=my_config_directory/ tiled serve config
```

--------------------------------

### Launch Public Tiled Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/security.md

Start a Tiled server in public mode using the --public flag. This allows open, anonymous access to data not otherwise restricted.

```bash
tiled serve {pyobject, directory, config} --public ...
```

--------------------------------

### Initialize Project and Add Tiled (uv)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/index.md

Initialize a new project with uv and add Tiled as a dependency.

```shell
uv init
uv add "tiled[all]"
```

--------------------------------

### Check Authentication Requirements

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/authentication.md

Query the root endpoint to determine if authentication is required and identify available authentication providers. This example shows how to check for 'toy' provider details and authentication links.

```shell
$ http :8000/api/v1/ | jq .".authentication"
```

```json
{
  "required": true,
  "providers": [
    {
      "provider": "toy",
      "mode": "internal",
      "links": {
        "auth_endpoint": "http://localhost:8000/api/v1/auth/provider/toy/token"
      },
      "confirmation_message": null
    }
  ],
  "links": {
    "whoami": "http://localhost:8000/api/v1/auth/whoami",
    "apikey": "http://localhost:8000/api/v1/auth/apikey",
    "refresh_session": "http://localhost:8000/api/v1/auth/session/refresh",
    "revoke_session": "http://localhost:8000/api/v1/auth/session/revoke/{session_id}",
    "logout": "http://localhost:8000/api/v1/auth/logout"
  }
}
```

--------------------------------

### Run a Persistent Writable Tiled Catalog in Docker

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/docker.md

Starts a Tiled server container with persistent storage. It maps a local directory './storage' to '/storage' inside the container for data and database persistence.

```bash
mkdir storage/

docker run \
  -p 8000:8000 \
  -e TILED_SINGLE_USER_API_KEY=secret \
  -v ./storage:/storage ghcr.io/bluesky/tiled:latest
```

--------------------------------

### Example curl Commands for XDI Format

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/specialized-formats.md

Demonstrates various ways to request data in XDI format using curl, by specifying the media type in the Accept header or as a query parameter.

```bash
$ curl -H 'Accept: application/x-xdi' 'http://localhost:8000/api/v1/table/full/example.xdi'
$ curl 'http://localhost:8000/api/v1/table/full/example?format=application/x-xdi'
$ curl 'http://localhost:8000/api/v1/table/full/example?format=xdi'
```

--------------------------------

### Install Tiled with conda

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/index.md

Install Tiled from the conda-forge channel into your activated conda environment.

```shell
conda install -c conda-forge tiled
```

--------------------------------

### Launch Tiled Server with Toy Authentication

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/authentication.md

Launches a Tiled server using a toy authentication system. Set environment variables for user passwords before running.

```bash
ALICE_PASSWORD=secret1 BOB_PASSWORD=secret2 CARA_PASSWORD=secret3 tiled serve config example_configs/toy_authentication.yml
```

--------------------------------

### Webhook Delivery Payload Example

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/webhooks.md

This is an example of the JSON payload structure sent to your registered webhook URL for a `container-child-created` event.

```json
{
  "type": "container-child-created",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "key": "scan_001",
  "path": ["my", "container"],
  "structure_family": "array",
  "specs": [],
  "metadata": {}
}
```

--------------------------------

### Install Locust Dependency

Source: https://github.com/bluesky/tiled/blob/main/locust/README.md

Install the Locust load testing tool if it's not already available in your environment. This command adds it to your project's requirements.

```bash
# Install dependencies (locust should already be available in the environment)
# If not installed, add it to your requirements or install with:
# uv add locust
```

--------------------------------

### Tiled Compose Override Example

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/deploy-tiled-single-node.md

An example of a Docker Compose override file. This file can be used to customize the default Tiled configuration when placed next to `compose.yml`.

```yaml
services:
  tiled:
    environment:
      - TILED_REGISTRY_URL=http://localhost:8000
      - TILED_AUTHENTICATOR=tiled.authenticators.OIDCAuthenticator
      - TILED_OIDC_CLIENT_ID=example-client-id
      - TILED_OIDC_CLIENT_SECRET=example-client-secret
      - TILED_OIDC_ISSUER=https://example.com/auth/realms/myrealm
      - TILED_OIDC_REDIRECT_URL=http://localhost:8000/oidc/callback
      - TILED_OIDC_USERINFO_ENDPOINT=https://example.com/auth/realms/myrealm/protocol/openid-connect/userinfo
      - TILED_OIDC_JWKS_URI=https://example.com/auth/realms/myrealm/protocol/openid-connect/certs
      - TILED_OIDC_SCOPES=openid email profile
      - TILED_OIDC_USERNAME_CLAIM=preferred_username
      - TILED_OIDC_GROUPS_CLAIM=groups
      - TILED_OIDC_ROLES_CLAIM=roles
      - TILED_OIDC_EXTRA_AUTHORIZATION_PARAMS=prompt=login
      - TILED_OIDC_USER_CLAIM_MAP=email:email,name:name,groups:roles

```

--------------------------------

### Initialize Workspace and Add Tiled (pixi)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/index.md

Initialize a new workspace with pixi and add Tiled as a dependency.

```shell
pixi init
pixi add tiled
```

--------------------------------

### Start Tiled Services

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/deploy-tiled-single-node.md

Command to start Tiled and its associated services (PostgreSQL, Redis) in detached mode using Docker Compose. The `.env` file is automatically read.

```sh
docker compose up -d
```

--------------------------------

### Initialize and Run a Persistent Writable Catalog

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/configuration.md

First, initialize a persistent catalog database, then run the Tiled server to serve data from a specified directory.

```bash
tiled catalog init catalog.db
tiled serve catalog catalog.db --write data/
```

--------------------------------

### Launch Simple Tiled Server with Temporary Storage

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/simple-server.md

Launches a Tiled server in the background on a thread and returns a client connected to it. Uses temporary storage by default.

```python
from tiled.client import simple

# Default: temporary storage!
c = simple()
```

--------------------------------

### Connect to a Tiled Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/10-minutes-to-tiled.md

Import the necessary client and establish a connection to a public Tiled demo instance.

```python
from tiled.client import from_uri

c = from_uri("https://tiled-demo.nsls2.bnl.gov")
```

--------------------------------

### Initialize Tiled Client from Configuration File

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/direct-client.md

Load Tiled configuration from a YAML file. Ensure the file path is correct and the file contains valid Tiled configuration.

```python
config = parse_configs("path/to/config.yml")
app = build_app_from_config(config)
context = Context.from_app(app)
client = from_context(context)
```

--------------------------------

### Register Custom Client via Entry Points

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/custom-clients.md

For third-party packages, register custom Tiled clients using Python entry points in `setup.py`. This allows Tiled to discover and load them automatically.

```python
# setup.py
setup(
    entry_points={
        "tiled.special_client": [
            "xdi = my_package.my_module:XDIDatasetClient",
        ],
    },
)
```

--------------------------------

### Get Current User Information

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/authentication.md

Retrieve information about the currently authenticated user.

```APIDOC
## GET /api/v1/auth/whoami

### Description
Retrieve information about the currently authenticated user.

### Method
GET

### Endpoint
/api/v1/auth/whoami

### Parameters
No parameters are required for this endpoint.

### Request Example
```bash
http GET :8000/api/v1/auth/whoami "Authorization:Bearer <access_token>"
```

### Response
#### Success Response (200)
Returns an object containing details about the current user. The exact structure may vary but typically includes user identification.

### Response Example
```json
{
  "username": "alice"
}
```
```

--------------------------------

### Get Authentication Status

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/authentication.md

Check the current authentication status and available providers.

```APIDOC
## GET /

### Description
An initial handshake with the `/` route tells us that authentication is required on this server and provides details about authentication providers.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **authentication** (object) - Information about authentication requirements and providers.
  - **required** (boolean) - Indicates if authentication is required.
  - **providers** (array) - List of available authentication providers.
    - **provider** (string) - The name of the authentication provider.
    - **mode** (string) - The mode of the provider (e.g., "internal", "external").
    - **links** (object) - Links related to the provider.
      - **auth_endpoint** (string) - The endpoint for authentication with this provider.
    - **confirmation_message** (string or null) - A message to confirm authentication.
  - **links** (object) - General authentication-related links.
    - **whoami** (string) - Endpoint to get current user information.
    - **apikey** (string) - Endpoint to manage API keys.
    - **refresh_session** (string) - Endpoint to refresh the current session.
    - **revoke_session** (string) - Endpoint to revoke a session.
    - **logout** (string) - Endpoint to log out.

### Response Example
```json
{
  "required": true,
  "providers": [
    {
      "provider": "toy",
      "mode": "internal",
      "links": {
        "auth_endpoint": "http://localhost:8000/api/v1/auth/provider/toy/token"
      },
      "confirmation_message": null
    }
  ],
  "links": {
    "whoami": "http://localhost:8000/api/v1/auth/whoami",
    "apikey": "http://localhost:8000/api/v1/auth/apikey",
    "refresh_session": "http://localhost:8000/api/v1/auth/session/refresh",
    "revoke_session": "http://localhost:8000/api/v1/auth/session/revoke/{session_id}",
    "logout": "http://localhost:8000/api/v1/auth/logout"
  }
}
```
```

--------------------------------

### Check Python Version

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/index.md

Verify your Python installation. Tiled requires Python 3.10 or later.

```shell
python3 --version
```

--------------------------------

### Initialize Tiled Client from Configuration Directory

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/direct-client.md

Load Tiled configuration from multiple YAML files within a directory. This allows for modular configuration management.

```python
config = parse_configs("path/to/directory/")
app = build_app_from_config(config)
context = Context.from_app(app)
client = from_context(context)
```

--------------------------------

### Initialize Tiled Database

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/tiled-authn-database.md

Run this command to initialize the database schema for Tiled. This only needs to be done once. The database URI should include the password injected via environment variable.

```bash
$ tiled admin initialize-database postgresql://tiled:${TILED_DATABASE_PASSWORD}@.../tiled
```

--------------------------------

### Get Application URL with Ingress

Source: https://github.com/bluesky/tiled/blob/main/helm/tiled/templates/NOTES.txt

If Ingress is enabled, this template generates the application URL based on configured hosts and paths.

```go-template
{{- if .Values.ingress.enabled }}
{{- range $host := .Values.ingress.hosts }}
  {{- range .paths }}
  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }}
  {{- end }}
{{- end }}
{{- end }}
```

--------------------------------

### Using a Convenience Function

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/queries.md

Demonstrates how to use a defined convenience function (Sample) to perform a search, making the call more concise.

```python
c.search(Sample("stuff"))
```

--------------------------------

### Launch Simple Tiled Server with Persistent Storage

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/simple-server.md

Launches a Tiled server with persistent storage. Specify a directory path for storage.

```python
from tiled.client import simple

# Or use persistent storage
c = simple('path/to/some/directory')
```

--------------------------------

### Construct Tiled client using a profile

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/profiles.md

Use `from_profile` with a profile alias for a more memorable and succinct way to construct a Tiled client, assuming the profile is already configured.

```python
from tiled.client import from_profile

client = from_profile("demo")
```

--------------------------------

### Request Custom Format via HTTPie

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/custom-export-formats.md

Example of requesting data in the custom `application/x-smileys` format using the HTTPie command-line tool.

```bash
$ http :8000/array/full/A?slice=:5,:5 Accept:application/x-smileys
HTTP/1.1 200 OK
content-length: 159
content-type: application/x-smileys; charset=utf-8
date: Wed, 12 Jan 2022 21:38:24 GMT
etag: 8b6ec7a60f30c181762a4c73a6b433b0
server: uvicorn
server-timing: read;dur=3.3, tok;dur=0.1, pack;dur=0.2, app;dur=8.1
set-cookie: tiled_csrf=JDHYkMUIBWECLqIJJvTaEcinv_Vd3kTxS08XCw3N4Yg; HttpOnly; Path=/; SameSite=lax

1.0🙂1.0🙂1.0🙂1.0🙂1.0
1.0🙂1.0🙂1.0🙂1.0🙂1.0
1.0🙂1.0🙂1.0🙂1.0🙂1.0
1.0🙂1.0🙂1.0🙂1.0🙂1.0
1.0🙂1.0🙂1.0🙂1.0🙂1.0
```

--------------------------------

### Prepare Databases for Tiled Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/authentication.md

Helper scripts to prepare the necessary databases for Tiled, including access tags and catalog databases. Run these before launching the server.

```python
python example_configs/access_tags/compile_tags.py
```

```python
python example_configs/catalog/create_catalog.py
```

--------------------------------

### Get Application URL with NodePort

Source: https://github.com/bluesky/tiled/blob/main/helm/tiled/templates/NOTES.txt

When the service type is NodePort, these commands retrieve the NodePort and Node IP to construct the application URL.

```bash
export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "tiled.fullname" . }})
export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
echo http://$NODE_IP:$NODE_PORT
```

--------------------------------

### Get Distinct Metadata Values and Counts

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/10-minutes-to-tiled.md

Query Tiled to find unique values for a metadata key and their frequencies within a dataset.

```python
x.distinct('element.category', counts=True)['metadata']
```

--------------------------------

### Verify Webhook Delivery Signature

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/webhooks.md

Example Python code to verify the HMAC signature of an incoming webhook delivery using the provided secret.

```APIDOC
## Verifying Deliveries

When a `secret` is set during webhook registration, Tiled adds an `X-Tiled-Signature` header to every request. This header contains a SHA256 HMAC digest of the request body, prefixed with `sha256=`. The following Python code demonstrates how to verify this signature:

```python
import hashlib
import hmac

def verify_signature(body: bytes, secret: str, header: str) -> bool:
    """Verifies the HMAC signature of a webhook delivery.

    Args:
        body: The raw request body as bytes.
        secret: The secret key used for signing.
        header: The value of the X-Tiled-Signature header.

    Returns:
        True if the signature is valid, False otherwise.
    """
    expected_signature = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_signature, header)

# Example usage:
# raw_body = request.get_data()
# signature_header = request.headers.get('X-Tiled-Signature')
# webhook_secret = "your-registered-secret"
# if signature_header and verify_signature(raw_body, webhook_secret, signature_header):
#     print("Signature verified!")
# else:
#     print("Invalid signature!")
```

Additionally, the `X-Tiled-Event-ID` header can be used to deduplicate retried deliveries.
```

--------------------------------

### Construct Tiled client using URI

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/profiles.md

This is the standard way to construct a Tiled client by providing the URI. Profiles offer a more concise alternative.

```python
from tiled.client import from_uri
from tiled.client.cache import Cache

client = from_uri("https://tiled-demo.nsls2.bnl.gov")
```

--------------------------------

### Get Filepaths for Data Assets

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/10-minutes-to-tiled.md

Retrieve the physical file paths associated with a Tiled data source. This is useful for accessing the underlying files directly.

```python
from tiled.client.utils import get_asset_filepaths

get_asset_filepaths(c['examples/xraydb/C/edges'])
```

--------------------------------

### Locate Data Sources

Source: https://github.com/bluesky/tiled/blob/main/docs/source/getting-started/cheat-sheet.md

Retrieve file paths for data assets or get more detailed information about data sources, including format, shape, and URIs.

```python
from tiled.client.utils import get_asset_filepaths

# Just the file path(s)
get_asset_filepaths(c['examples/xraydb/C/edges'])
```

```python
# More detailed information, including format, shape or column names
# (as applicable), URIs, etc.
c['examples/xraydb/C/edges'].data_sources()
```

--------------------------------

### Check External Authentication Type

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/authentication.md

Query the root endpoint to determine if the server uses an external identity provider for authentication. This example checks the 'authentication.type' field.

```shell
$ http https://tiled-demo.nsls2.bnl.gov/api/v1/ | jq .authentication.type
"external"
```

--------------------------------

### Initialize Tiled Client from Dictionary Configuration

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/direct-client.md

Configure Tiled using a Python dictionary. This is useful for programmatic configuration or when the configuration is dynamically generated.

```python
from tiled.client import Context, from_context
from tiled.server.app import build_app_from_config

config = {
    "trees": [
        {
             "path": "/",
             "tree": "tiled.examples.generated_minimal:tree",
        }
}
app = build_app_from_config(config)
context = Context.from_app(app)
client = from_context(context)
```

--------------------------------

### Instantiate SimpleTiledServer and Connect Client

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/simple-server.md

Manually instantiate SimpleTiledServer and create a client connected to its URI. This approach offers more control over server management.

```python
from tiled.server import SimpleTiledServer
from tiled.client import from_uri

server = SimpleTiledServer()
client = from_uri(server.uri)
```

--------------------------------

### Initialize Tiled Client from Service-Side Tree Instance

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/direct-client.md

Use this when you want to run the Tiled service and client in the same Python process. It bypasses network overhead and simplifies debugging by allowing exceptions to be raised directly.

```python
from tiled.client import Context, from_context
from tiled.examples.generated_minimal import tree
from tiled.server.app import build_app

app = build_app(tree)
context = Context.from_app(app)
client = from_context(context)
```

--------------------------------

### Access XDI Data as CSV

Source: https://github.com/bluesky/tiled/blob/main/docs/source/explanations/specialized-formats.md

Retrieve XDI data from a tiled server in CSV format using an HTTP GET request with the appropriate 'Accept' header.

```bash
$ curl -H 'Accept: text/csv' 'http://localhost:8000/api/v1/table/full/example'
```

--------------------------------

### Make Authenticated Request

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/authentication.md

Include the obtained access token in the Authorization header to make authenticated requests to protected API endpoints. This example demonstrates fetching metadata.

```shell
$ http GET :8000/api/v1/metadata/ "Authorization:Bearer `jq -r .access_token tokens.json`"
```

```json
{
    "data": {
        "attributes": {
            "count": 2,
            "metadata": {},
            "sorting": null,
            "specs": null
        },
        "id": "",
        "links": {
            "search": "http://localhost:8000/api/v1/search/",
            "self": "http://localhost:8000/api/v1/metadata/"
        },
        "meta": null,
        "type": "tree"
    },
    "error": null,
    "links": null,
    "meta": {}
}
```

--------------------------------

### API Key Authentication (Explicit)

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/authentication.md

This example shows how to explicitly pass an API key to the `from_uri` function. It is generally discouraged to hardcode API keys directly in code.

```python
import os
from tiled.client import from_uri

client = from_uri("https://....", api_key=os.environ["TILED_API_KEY"])
```

--------------------------------

### Connect to Tiled Server

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/authentication.md

Connect to a Tiled server using its URI. This is the initial step before any authentication.

```python
from tiled.client import from_uri
>>> client = from_uri("https://...")
>>> <Container ...>
```

--------------------------------

### Defining a Convenience Function for Searches

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/queries.md

Create convenience functions for common searches to improve code readability and reduce repetition. This example defines a function for searching by 'sample_name'.

```python
def Sample(sample_name):
    return Key("sample_name") == sample_name
```

--------------------------------

### Log in to Tiled and Create API Key

Source: https://github.com/bluesky/tiled/blob/main/docs/source/user-guide/api-keys.md

Log in to a Tiled server using the command line interface and create a new API key. The generated key should be kept secret.

```bash
$ tiled profile create http://localhost:8000
$ tiled login
Username: alice
Password:
```

```bash
$ tiled api_key create
48e8f8598940fa0f3e80b406def606e17e815a2c76fe21350a99d6d9935371d11533b318
```

--------------------------------

### Connect and Log in with Python Client

Source: https://github.com/bluesky/tiled/blob/main/example_configs/simple_oidc/README.md

Connect to the Tiled server using the Python client and initiate the login process. This will typically open a browser or provide a URL for authentication.

```python
from tiled.client import from_uri
c = from_uri("http://localhost:8000")
c.login()
```

--------------------------------

### Get External Authentication Endpoint

Source: https://github.com/bluesky/tiled/blob/main/docs/source/reference/authentication.md

Retrieve the authentication endpoint URL for the external identity provider from the root endpoint response. This URL is used to initiate the OAuth flow.

```shell
$ http https://tiled-demo.nsls2.bnl.gov/api/v1/ | jq .authentication.endpoint
"https://orcid.org/oauth/authorize?client_id=APP-0ROS9DU5F717F7XN&response_type=code&scope=openid&redirect_uri=https://tiled-demo.nsls2.bnl.gov/auth/code",
```