Skip to content

How to Host Data via Local HTTP Server?

This guide explains how to host spatial transcriptomics dataset folders over HTTP for testing or sharing with CartoScope.

1. Prepare Your Processed Dataset Folder

Ensure your processed dataset directory contains the catalog.yaml catalog file, PMTILES image files, spatial factor/gene expression data matrices, and metadata.

1
2
3
4
5
6
# Option A: Navigate into a single dataset directory
cd /path/to/your/dataset_directory
# Example: cd xenium-human-kidney-igan-bull2024-20260516

# Option B: Navigate into a parent directory containing multiple dataset folders
cd /path/to/parent_data_directory

2. Start a Local HTTP Server with CORS Enabled

CartoScope requires Cross-Origin Resource Sharing (CORS) header support when fetching remote data chunks. Start a lightweight Node.js HTTP server using npx http-server:

1
npx http-server --cors -p 8080

Why is the --cors flag required?

CartoScope executes in your web browser and fetches binary data tiles (.pmtiles, .parquet) from your HTTP server (http://localhost:8080). Enabling CORS allows your browser to download these data assets without cross-origin security blockades.

3. Get the Entry Point URL

Your dataset's entry point is the YAML file containing metadata about your dataset, typically named catalog.yaml (for single datasets) or multi-catalog.yaml (for multi-sample cohort sessions).

3.A Single Dataset Entry Point (catalog.yaml)

1
2
3
4
5
6
7
8
9
# Replace `<folder_name>` with your actual folder name and `<catalog_filename>` with the name of your catalog file.

# Option A: If serving from inside a single dataset folder (Option A in Section 1)
http://localhost:8080/<catalog_filename>
# Example: http://localhost:8080/catalog.yaml

# Option B: If serving from a parent directory (Option B in Section 1)
http://localhost:8080/<folder_name>/<catalog_filename>
# Example: http://localhost:8080/xenium-human-kidney-igan-bull2024-20260516/catalog.yaml

Why specify /catalog.yaml in Option A?

When serving directly from inside a dataset folder, http://localhost:8080/ represents the root server origin rather than a named subfolder path. To avoid ambiguity between the server origin and catalog file, you must explicitly specify the catalog filename (e.g. http://localhost:8080/catalog.yaml) so CartoScope can fetch the metadata file directly.

Use Folder URL

If your data are served from a parent directory (Option B) and your metadata file is named catalog.yaml, you can also use the subfolder URL as the entry point:

1
2
http://localhost:8080/<folder_name>/
# Example: http://localhost:8080/xenium-human-kidney-igan-bull2024-20260516/

3.B Multi-Sample Cohort Session Entry Point (multi-catalog.yaml)

To launch a multi-sample session containing multiple sample slides, reference the multi-catalog.yaml file:

1
2
3
4
5
6
7
8
9
# Replace <session_id> with the name of the folder containing the multi-sample cohort data.

# Option A: If serving from the multi-sample cohort folder (Option A in Section 1)
http://localhost:8080/multi-catalog.yaml
# Example: http://localhost:8080/multi-catalog.yaml

# Option B: If serving from a parent directory (Option B in Section 1)
http://localhost:8080/<session_id>/multi-catalog.yaml
# Example: http://localhost:8080/cohort_study_2026/multi-catalog.yaml

Use Folder URL

If your data are served from a parent directory (Option B) and your metadata file is named multi-catalog.yaml, you can also use the subfolder URL as the entry point:

1
2
http://localhost:8080/<session_id>/
# Example: http://localhost:8080/cohort_study_2026/

Related Pages

Concepts

Manual Pages

How-to Guides

FAQs