Cargo publish headlessly

ScriptSmith · ScriptSmith · commit 12796e008d00 · 2026-02-23T20:54:46.000+10:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -70,7 +70,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        features: [tiny, minimal, standard, full]
+        features: [tiny, minimal, standard, full, headless]
     steps:
       - uses: actions/checkout@v4
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -79,7 +79,7 @@ jobs:
         include:
           - target: x86_64-unknown-linux-gnu
             os: ubuntu-latest
-            features: "full standard minimal tiny"
+            features: "full headless standard minimal tiny"
           - target: x86_64-unknown-linux-musl
             os: ubuntu-latest
             features: "standard minimal tiny"
@@ -88,7 +88,7 @@ jobs:
             features: "standard minimal tiny"
           - target: aarch64-apple-darwin
             os: macos-latest
-            features: "full standard minimal tiny"
+            features: "full headless standard minimal tiny"
           - target: x86_64-pc-windows-msvc
             os: windows-latest
             features: "standard minimal tiny"
@@ -236,16 +236,13 @@ jobs:
         with:
           shared-key: publish
 
-      - name: Fetch model catalog
-        run: mkdir -p data && curl -sSL https://models.dev/api.json -o data/models-dev-catalog.json
-
       - name: Set version from tag
         run: |
           VERSION="${GITHUB_REF_NAME#v}"
           sed -i "s/^version = \".*\"/version = \"$VERSION\"/" Cargo.toml
 
       - name: Publish to crates.io
-        run: cargo publish --no-default-features --features tiny --allow-dirty
+        run: cargo publish --no-default-features --features headless --allow-dirty
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
 
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -28,6 +28,7 @@ tiny = ["provider-openai", "provider-test"]
 minimal = [
     "tiny",
     "database-sqlite",
+    "embed-catalog",
     "embed-ui",
     "provider-anthropic",
     "provider-azure",
@@ -63,6 +64,40 @@ full = [
     "virus-scan",
 ]
 
+# All features except embedded assets (UI, docs, catalog).
+# Suitable for `cargo install` users who don't have build artifacts,
+# and for deployments that serve the frontend separately.
+headless = [
+    "cel",
+    "csv-export",
+    "database-postgres",
+    "database-sqlite",
+    "document-extraction-basic",
+    "document-extraction-full",
+    "forecasting",
+    "json-schema",
+    "otlp",
+    "prometheus",
+    "provider-anthropic",
+    "provider-azure",
+    "provider-bedrock",
+    "provider-openai",
+    "provider-test",
+    "provider-vertex",
+    "redis",
+    "response-validation",
+    "s3-storage",
+    "saml",
+    "secrets-aws",
+    "secrets-azure",
+    "secrets-gcp",
+    "sso",
+    "utoipa",
+    "vault",
+    "virus-scan",
+    "wizard",
+]
+
 # Providers (always-available: openai, anthropic, test)
 provider-openai = []
 provider-anthropic = []
@@ -99,6 +134,7 @@ s3-storage = ["aws-sdk", "dep:aws-sdk-s3"]
 # Embedded assets
 embed-ui = ["dep:rust-embed"]
 embed-docs = ["dep:rust-embed"]
+embed-catalog = ["dep:rust-embed"]
 
 # Databases
 database-sqlite = ["dep:sqlx", "sqlx/sqlite"]
@@ -214,7 +250,7 @@ opentelemetry-otlp = { version = "0.30", features = ["trace", "logs", "grpc-toni
 opentelemetry-semantic-conventions = { version = "0.30", optional = true }
 opentelemetry_sdk = { version = "0.30", features = ["rt-tokio", "logs"], optional = true }
 redis = { version = "0.32.7", features = ["aio", "tokio-comp", "cluster-async"], optional = true }
-rust-embed = { version = "8", features = ["mime-guess"], optional = true }
+rust-embed = { version = "8", features = ["mime-guess", "include-exclude"], optional = true }
 samael = { version = "0.0.19", optional = true }
 schemars = { version = "0.8", optional = true }
 sqlx = { version = "0.8", features = ["runtime-tokio", "uuid", "chrono", "rust_decimal", "migrate", "json"], optional = true }
diff --git a/docs/content/docs/deployment/index.mdx b/docs/content/docs/deployment/index.mdx
@@ -91,12 +91,13 @@ Hadrian uses Cargo feature flags for modular compilation. Choose a profile based
 
 ### Profiles
 
-| Profile          | Features                                                                                                                                                                                                          | Use Case                             |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| `tiny`           | OpenAI + Test providers only — no database, no embedded assets                                                                                                                                                    | Stateless API proxy, smallest binary |
-| `minimal`        | tiny + all providers (Anthropic, Azure, Bedrock, Vertex), SQLite, embedded UI, wizard                                                                                                                             | Development, Windows, embedded       |
-| `standard`       | minimal + PostgreSQL, Redis, OTLP, Prometheus, CEL, SSO, basic doc extraction, embedded docs, OpenAPI docs, S3, secrets managers (AWS/Azure/GCP/Vault), forecasting, JSON schema, response validation, CSV export | Typical deployment                   |
-| `full` (default) | standard + SAML, Kreuzberg (full doc extraction), ClamAV (virus scan)                                                                                                                                             | Production multi-tenant              |
+| Profile          | Features                                                                                                                                                                                                          | Use Case                                  |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `tiny`           | OpenAI + Test providers only — no database, no embedded assets                                                                                                                                                    | Stateless API proxy, smallest binary      |
+| `minimal`        | tiny + all providers (Anthropic, Azure, Bedrock, Vertex), SQLite, embedded UI, embedded catalog, wizard                                                                                                           | Development, Windows, embedded            |
+| `standard`       | minimal + PostgreSQL, Redis, OTLP, Prometheus, CEL, SSO, basic doc extraction, embedded docs, OpenAPI docs, S3, secrets managers (AWS/Azure/GCP/Vault), forecasting, JSON schema, response validation, CSV export | Typical deployment                        |
+| `full` (default) | standard + SAML, Kreuzberg (full doc extraction), ClamAV (virus scan)                                                                                                                                             | Production multi-tenant                   |
+| `headless`       | All `full` features except embedded assets (no UI, docs, or catalog)                                                                                                                                              | `cargo install`, separate frontend, CI/CD |
 
 Build with a specific profile:
 
@@ -112,6 +113,9 @@ cargo build --release --no-default-features --features standard
 
 # Everything enabled (default)
 cargo build --release
+
+# All features without embedded assets — for cargo install or separate frontend
+cargo build --release --no-default-features --features headless
 ```
 
 ### Individual Feature Flags
@@ -128,6 +132,7 @@ Select individual features for a custom build by combining flags with `--no-defa
 |                         | `provider-azure`            | Azure OpenAI (pulls in `azure-sdk`)                     | minimal     |
 | **Assets**              | `embed-ui`                  | Embedded web UI                                         | minimal     |
 |                         | `embed-docs`                | Embedded documentation site                             | standard    |
+|                         | `embed-catalog`             | Embedded model catalog from models.dev                  | minimal     |
 | **Databases**           | `database-sqlite`           | SQLite database support                                 | minimal     |
 |                         | `database-postgres`         | PostgreSQL database support                             | standard    |
 | **Secrets**             | `vault`                     | HashiCorp Vault                                         | standard    |
diff --git a/docs/content/docs/getting-started.mdx b/docs/content/docs/getting-started.mdx
@@ -9,15 +9,16 @@ Get Hadrian Gateway running in under a minute. No complex setup required.
 
 ## Quick Start
 
-### Using Cargo (Recommended)
+### Pre-built Binary (Recommended)
 
-```bash
-# Download and run (creates config automatically)
-cargo install hadrian
-hadrian
+Download the latest release for your platform from the
+[GitHub Releases](https://github.com/ScriptSmith/hadrian/releases) page. Pre-built binaries
+include the embedded web UI, documentation, and model catalog.
 
-# Or with a custom config
-hadrian --config hadrian.toml
+```bash
+# Extract and run (creates config automatically)
+tar xzf hadrian-*.tar.gz
+./hadrian
 ```
 
 ### Using Docker
@@ -30,7 +31,21 @@ docker run -p 8080:8080 -e OPENROUTER_API_KEY=sk-... ghcr.io/ScriptSmith/hadrian
 docker run -p 8080:8080 -v ./hadrian.toml:/etc/hadrian/hadrian.toml ghcr.io/ScriptSmith/hadrian
 ```
 
-The gateway starts at `http://localhost:8080` with the chat UI. No database required for basic use.
+### Using Cargo
+
+```bash
+cargo install hadrian
+hadrian
+```
+
+<Callout type="warn">
+  `cargo install` builds the **headless** profile, which includes all backend features but does not
+  embed the web UI, documentation site, or model catalog. For the full experience with embedded
+  assets, use a [pre-built binary](https://github.com/ScriptSmith/hadrian/releases) or [build from
+  source](#building-from-source).
+</Callout>
+
+The gateway starts at `http://localhost:8080` with the chat UI (when embedded assets are included). No database required for basic use.
 
 ## Zero-Config Mode
 
@@ -115,13 +130,34 @@ open http://localhost:8080/api/docs
 
 ## Building from Source
 
+Build Hadrian with all features and embedded assets:
+
 ```bash
 git clone https://github.com/ScriptSmith/hadrian.git
-cd hadrian/gateway
+cd hadrian
+
+# Build frontend assets
+cd ui && pnpm install && pnpm build && cd ..
+
+# Build documentation site
+cd docs && pnpm install && pnpm build && cd ..
+
+# Fetch model catalog
+./scripts/fetch-model-catalog.sh
+
+# Build the full binary
 cargo build --release
 ./target/release/hadrian
 ```
 
+To build without frontend assets (headless), skip the UI/docs/catalog steps:
+
+```bash
+cargo build --release --no-default-features --features headless
+```
+
+See [Deployment](/docs/deployment) for build profiles and feature flags.
+
 ## Next Steps
 
 <Cards>
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
@@ -27,12 +27,12 @@ Hadrian is an **AI Gateway** that provides a unified OpenAI-compatible API for r
 
 ## Documentation Sections
 
-| Section                                  | Description                         |
-| ---------------------------------------- | ----------------------------------- |
-| [Getting Started](/docs/getting-started) | Installation and basic setup        |
-| [Configuration](/docs/configuration)     | All configuration options           |
-| [Features](/docs/features)               | Detailed feature guides             |
-| [API Reference](/docs/api)               | OpenAI-compatible API documentation |
-| [Deployment](/docs/deployment)           | Production deployment guides        |
-| [Security](/docs/security)               | Security best practices             |
-| [Troubleshooting](/docs/troubleshooting) | Common issues and solutions         |
+| Section                                  | Description                                                                        |
+| ---------------------------------------- | ---------------------------------------------------------------------------------- |
+| [Getting Started](/docs/getting-started) | Installation and basic setup                                                       |
+| [Configuration](/docs/configuration)     | All configuration options                                                          |
+| [Features](/docs/features)               | Detailed feature guides                                                            |
+| [API Reference](/docs/api)               | OpenAI-compatible API documentation                                                |
+| [Deployment](/docs/deployment)           | Production deployment guides, build profiles (`full`, `headless`, `standard`, ...) |
+| [Security](/docs/security)               | Security best practices                                                            |
+| [Troubleshooting](/docs/troubleshooting) | Common issues and solutions                                                        |
diff --git a/src/catalog/mod.rs b/src/catalog/mod.rs
@@ -3,16 +3,18 @@
 //! This module provides access to the models.dev model catalog, which contains
 //! per-model metadata including capabilities, pricing, context limits, and modalities.
 //!
-//! The catalog is embedded at build time as a fallback and optionally synced at
-//! runtime via a background job.
+//! The catalog is optionally embedded at build time as a fallback (via the `embed-catalog`
+//! feature) and can be synced at runtime via a background job.
 //!
 //! # Usage
 //!
 //! ```rust,ignore
 //! use crate::catalog::ModelCatalogRegistry;
 //!
 //! let registry = ModelCatalogRegistry::new();
-//! registry.load_from_json(EMBEDDED_CATALOG)?;
+//! if let Some(json) = embedded_catalog() {
+//!     registry.load_from_json(&json)?;
+//! }
 //!
 //! // Look up model metadata
 //! if let Some(enrichment) = registry.lookup("anthropic", "claude-opus-4-5") {
@@ -28,20 +30,39 @@ pub use registry::{
     ModelCapabilities, ModelCatalogRegistry, ModelModalities, resolve_catalog_provider_id,
 };
 
-/// The embedded model catalog from models.dev.
-///
-/// This is loaded at compile time and serves as a fallback when runtime sync is
-/// disabled or unavailable. The catalog is fetched via `scripts/fetch-model-catalog.sh`.
-pub const EMBEDDED_CATALOG: &str = include_str!("../../data/models-dev-catalog.json");
+/// Embedded catalog assets from the data/ directory.
+/// Gated behind the `embed-catalog` feature and uses `allow_missing` so the
+/// build succeeds even when `data/models-dev-catalog.json` is absent.
+#[cfg(feature = "embed-catalog")]
+#[derive(rust_embed::Embed)]
+#[folder = "data"]
+#[include = "models-dev-catalog.json"]
+#[allow_missing = true]
+struct CatalogAssets;
+
+/// Returns the embedded model catalog JSON, if the `embed-catalog` feature is
+/// enabled and the catalog file was present at build time.
+pub fn embedded_catalog() -> Option<String> {
+    #[cfg(feature = "embed-catalog")]
+    {
+        CatalogAssets::get("models-dev-catalog.json")
+            .map(|file| String::from_utf8_lossy(&file.data).into_owned())
+    }
+    #[cfg(not(feature = "embed-catalog"))]
+    {
+        None
+    }
+}
 
-#[cfg(test)]
+#[cfg(all(test, feature = "embed-catalog"))]
 mod tests {
     use super::*;
 
     #[test]
     fn test_embedded_catalog_parses() {
+        let json = embedded_catalog().expect("Embedded catalog should be present");
         let catalog: types::ModelCatalog =
-            serde_json::from_str(EMBEDDED_CATALOG).expect("Embedded catalog should be valid JSON");
+            serde_json::from_str(&json).expect("Embedded catalog should be valid JSON");
 
         // Should have multiple providers
         assert!(
@@ -67,9 +88,10 @@ mod tests {
 
     #[test]
     fn test_load_embedded_catalog_into_registry() {
+        let json = embedded_catalog().expect("Embedded catalog should be present");
         let registry = ModelCatalogRegistry::new();
         registry
-            .load_from_json(EMBEDDED_CATALOG)
+            .load_from_json(&json)
             .expect("Should load embedded catalog");
 
         // Should have many models
diff --git a/src/main.rs b/src/main.rs
