Docs

.github/workflows/docs-deploy.yml

@@ -0,0 +1,111 @@
+name: Deploy docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Git tag or commit to deploy (must contain the docs site)
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+# Serialize image publication and webhook calls. Coolify completes the rollout asynchronously.
+# Configure its Docker Image application to pull ghcr.io/<owner>/<repo>-docs:production.
+concurrency:
+  group: docs-production
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    environment:
+      name: docs-production
+      url: https://spatialnode.com/superstac
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'release' && github.event.release.tag_name || inputs.ref }}
+          persist-credentials: false
+
+      - name: Check deployment configuration
+        env:
+          COOLIFY_DEPLOY_WEBHOOK: ${{ secrets.COOLIFY_DEPLOY_WEBHOOK }}
+          COOLIFY_TOKEN: ${{ secrets.COOLIFY_TOKEN }}
+        run: |
+          : "${COOLIFY_DEPLOY_WEBHOOK:?Set the COOLIFY_DEPLOY_WEBHOOK Actions secret}"
+          : "${COOLIFY_TOKEN:?Set the COOLIFY_TOKEN Actions secret}"
+
+      - name: Name the image
+        id: image
+        run: |
+          image="ghcr.io/${GITHUB_REPOSITORY,,}-docs"
+          revision="$(git rev-parse HEAD)"
+          tag="sha-${revision}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          echo "name=$image" >> "$GITHUB_OUTPUT"
+          echo "ref=$image:$tag" >> "$GITHUB_OUTPUT"
+          echo "revision=$revision" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Build and type-check
+        env:
+          IMAGE: ${{ steps.image.outputs.ref }}
+          REVISION: ${{ steps.image.outputs.revision }}
+        run: |
+          docker build --platform linux/amd64 \
+            --label "org.opencontainers.image.source=https://github.com/$GITHUB_REPOSITORY" \
+            --label "org.opencontainers.image.revision=$REVISION" \
+            --tag "$IMAGE" docs
+
+      - name: Test the built container
+        env:
+          IMAGE: ${{ steps.image.outputs.ref }}
+        run: |
+          docker run --detach --name docs-test --publish 127.0.0.1:3000:3000 "$IMAGE"
+          trap 'docker logs docs-test; docker rm --force docs-test' EXIT
+          ready=false
+          for attempt in {1..60}; do
+            if curl --fail --silent http://127.0.0.1:3000/superstac > /dev/null; then
+              ready=true
+              break
+            fi
+            sleep 2
+          done
+          if [ "$ready" != true ]; then
+            echo 'Documentation container did not become ready' >&2
+            exit 1
+          fi
+          node docs/scripts/check-links.mjs
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish tested image
+        env:
+          IMAGE: ${{ steps.image.outputs.ref }}
+          PRODUCTION_IMAGE: ${{ steps.image.outputs.name }}:production
+        run: |
+          docker push "$IMAGE"
+          docker tag "$IMAGE" "$PRODUCTION_IMAGE"
+          docker push "$PRODUCTION_IMAGE"
+          echo "Published image: \`$IMAGE\`" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Request Coolify deployment
+        env:
+          COOLIFY_DEPLOY_WEBHOOK: ${{ secrets.COOLIFY_DEPLOY_WEBHOOK }}
+          COOLIFY_TOKEN: ${{ secrets.COOLIFY_TOKEN }}
+        run: bash docs/scripts/deploy-coolify.sh
+

Cargo.toml

@@ -6,13 +6,15 @@ members = [
     "crates/search",
     "crates/engine",
     "crates/cli",
+    "crates/python",
 ]
 
 [workspace.package]
 version = "0.1.0"
 edition = "2021"
-rust-version = "1.75"
+rust-version = "1.88"
 license = "MIT"
 repository = "https://github.com/spatialnode/superstac"
-homepage = "https://github.com/spatialnode/superstac"
+homepage = "https://spatialnode.com/superstac"
+documentation = "https://spatialnode.com/superstac"
 authors = ["Emmanuel Jolaiya <emmanuel@spatialnode.com>"]

README.md

@@ -1,11 +1,23 @@
-# superstac
+# SuperSTAC
 
-[![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/spatialnode/superstac/blob/main/LICENSE)
 [![crates.io](https://img.shields.io/crates/v/superstac-search.svg)](https://crates.io/crates/superstac-search)
-[![docs.rs](https://docs.rs/superstac-core/badge.svg)](https://docs.rs/superstac-search)
+[![Documentation](https://img.shields.io/badge/docs-SuperSTAC-blue)](https://spatialnode.com/superstac)
+[![docs.rs](https://docs.rs/superstac-search/badge.svg)](https://docs.rs/superstac-search)
 
-Federated [STAC](https://stacspec.org/) search across multiple catalogs. Query
-Element84, Microsoft Planetary Computer, and others through one API.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/spatialnode/superstac/main/docs/assets/superstac-logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/spatialnode/superstac/main/docs/assets/superstac-logo.svg">
+    <img src="https://raw.githubusercontent.com/spatialnode/superstac/main/docs/assets/superstac-logo.svg" alt="SuperSTAC logo" width="480">
+  </picture>
+</p>
+
+**Many catalogs. One search.**
+
+Search across [STAC](https://stacspec.org/) catalogs through one interface, with Python, Rust, or the command line.
+
+Query Element84, Microsoft Planetary Computer, and others through one API.
 Items come back deduplicated, with their collection IDs and asset keys
 normalized to canonical names — regardless of which catalog they came from.
 
@@ -20,10 +32,22 @@ A single STAC catalog isn't always enough:
 - The catalog you usually use is down or rate-limited.
 - Different providers index the same scenes under different names.
 
-superstac queries every catalog you've registered, drops the ones that don't
+SuperSTAC queries every catalog you've registered, drops the ones that don't
 serve the requested collection, runs the rest concurrently with retry and
 timeouts, then merges and dedupes the results.
 
+## Documentation
+
+Read the [SuperSTAC documentation](https://spatialnode.com/superstac) for installation, tutorials, and API guides.
+
+- [Quickstart](https://spatialnode.com/superstac/docs/start/quickstart)
+- [Python guide](https://spatialnode.com/superstac/docs/python/overview)
+- [Rust guide](https://spatialnode.com/superstac/docs/rust/overview)
+- [Command-line guide](https://spatialnode.com/superstac/docs/cli/overview)
+- [Configuration reference](https://spatialnode.com/superstac/docs/reference/configuration)
+
+Try the [Python quickstart notebook](https://spatialnode.com/superstac/docs/python/notebook) for a two-catalog search, footprint map, and GeoJSON export in Colab or Jupyter.
+
 ## Install
 
 ### Rust library
@@ -102,7 +126,7 @@ settings:
 ```
 
 The full schema and every setting is documented inline at
-[`crates/core/src/models/settings.rs`](./crates/core/src/models/settings.rs).
+[`crates/core/src/models/settings.rs`](https://github.com/spatialnode/superstac/blob/main/crates/core/src/models/settings.rs).
 
 ## Library usage
 
@@ -165,11 +189,10 @@ Some things on the way:
 
 - Authentication (per-catalog headers, OAuth, API keys)
 - SQLite + Postgres backends
-- Python bindings via PyO3
 - and many more.
 
 ## License
 
-MIT. See [LICENSE](./LICENSE).
+MIT. See [LICENSE](https://github.com/spatialnode/superstac/blob/main/LICENSE).
 
-Feedback and issues welcome — this is early. If you try it and you see any bug, feel free to open an issue!
+Feedback and issues welcome — this is early. If you try it and you see any bug, feel free to open an issue!

crates/cli/Cargo.toml

@@ -10,6 +10,7 @@ rust-version.workspace = true
 license.workspace = true
 repository.workspace = true
 homepage.workspace = true
+documentation.workspace = true
 authors.workspace = true
 
 [[bin]]