🛠️
Stacks Documentation
  • Start Here
  • 🧠Concepts
    • Stacks 101
      • What Is Stacks?
      • Bitcoin Connection
      • Proof of Transfer
      • Stacks Among Other Layers
      • Financial Incentive and Security Budget
    • Network Fundamentals
      • Network Basics
      • Mainnet and Testnets
      • Accounts
      • Authentication
      • Bitcoin Name System
      • SIPs
      • Technical Specifications
    • Block Production
      • Mining
      • Signing
      • Bitcoin Finality
      • Bitcoin Reorgs
      • Stacking
    • Transactions
      • How Transactions Work
      • Post Conditions
    • Clarity
      • Overview
      • Decidability
    • sBTC
      • Core Features
      • sBTC Operations
        • Deposit
        • Withdrawal
        • Deposit vs Withdrawal Times
      • Emily API
      • Peg Wallet UTXO
      • Clarity Contracts
        • sBTC Registry
        • sBTC Token
        • sBTC Deposit
        • sBTC Withdrawal
      • Auxiliary Features
        • Transaction Fee Sponsorship
        • Signer Wallet Rotation
      • Walkthroughs
        • Signer Process Walkthrough
        • sBTC Transaction Walkthrough
      • sBTC FAQ
    • Gaia
      • Configuration
      • Deploy Gaia Hub
      • Amazon EC2
      • Linux
      • Mac OS
  • 🛠️Guides & Tutorials
    • Developer Quickstart
    • Clarity Crash Course
    • Build a Borrowing & Lending Protocol
    • Bitcoin Integration
      • Sending Bitcoin with Leather Wallet
      • Verifying a Bitcoin Transaction
      • Parsing a Bitcoin Transaction
    • Create Tokens
      • Creating a NFT
      • Creating a Fungible Token
    • Build a Frontend
      • Post Conditions with Stacks.js
      • Authentication with Stacks.js
      • Sending Transactions with Stacks.js
    • Testing Smart Contracts
      • Fuzz Testing
    • Run a Node
      • Run a Node with Docker
      • Run a Node with Digital Ocean
      • Run a Node with a Hosted Provider
      • Run a Node with Quicknode
      • Run a Bitcoin Node
      • Run a Pruned Bitcoin Node
    • Run a Miner
      • Miner Prerequisites
      • Miner Costs and Fees
      • Mine Testnet Stacks Tokens
      • Mine Mainnet Stacks Tokens
      • Verify Miner
    • Run a Signer
      • Signer Quickstart
      • How to Read Signer Logs
      • How to Monitor a Signer
      • Best practices for running a Signer
      • OpSec Best Practices
    • sBTC
      • How to Run an sBTC Signer
      • Best practices for running an sBTC Signer
      • How to Use the sBTC Bridge
      • Earn sBTC Rewards
    • Stack STX
      • Solo Stack
      • Operate a Pool
      • Stack with a Pool
      • Increase Stacked Position
      • Stop Stacking
    • Oracles
    • Community Tutorials
  • 📚Reference
    • API
    • Clarity Types
    • Clarity Functions
    • Clarity Keywords
    • Stacks Node Configuration
    • Signer Configuration
    • Stacks Tooling
  • 🏗️Example Contracts
    • Audited Starter Contracts
    • Stacking
    • BNS
    • Multi Send
  • 🧡Press & Top Links
    • 🔶2024
      • 🔸January 2024
      • 🔸February 2024
      • 🔸March 2024
      • 🔸April 2024
      • 🔸May 2024
      • 🔸June 2024
      • 🔸July 2024
      • 🔸August 2024
      • 🔸September 2024
      • 🔸October 2024
      • 🔸November 2024
      • 🔸December 2024
    • 🔶2025
      • 🔸January 2025
      • 🔸February 2025
      • 🔸March 2025
      • 🔸April 2025
      • 🔸May 2025
  • 🧡Bitcoin Theses and Reports
    • 🟠Bitcoin Theses
    • 📙Bitcoin Reports
  • Contribute
Powered by GitBook
On this page
  • Configuration files
  • GAIA Admin Service
  • Driver Selection
  • Note on SSL
  • Require Correct Hub URL
  • The readURL parameter
  • Minimum Proofs Requirement
  • CDN & Replicated Hubs

Was this helpful?

  1. Concepts
  2. Gaia

Configuration

PreviousGaiaNextDeploy Gaia Hub

Last updated 1 year ago

Was this helpful?

Configuration files

The following configuration files exist in the folder deploy/configs/gaia/:

admin-config.json
hub-config.json
reader-config.json

GAIA Admin Service

You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install npm with a apt install npm. Once npm is installed you can continue with the steps in the .

Driver Selection

The Gaia hub currently supports the following drivers:

'aws' == Amazon S3
'azure' == Azure Blob Storage
'disk' == Local disk
'google-cloud' === Google Cloud Storage

Set the driver you wish to use in your file with the driver parameter. Many drivers additionally accept the bucket parameter, which controls the bucket name that files should be written to.

These driver may require you to provide additional credentials for performing writes to the backends. See config.sample.json for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your config.json).

:::caution The disk driver requires a *nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. :::

Note on SSL

We strongly recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. Configuration options are available to run the hub with an https Node.js server. Otherwise, a reverse proxy web server such as nginx or Apache can be used.

Require Correct Hub URL

If you turn on the requireCorrectHubUrl option in your config.json file, your Gaia hub will require that authentication requests correctly include the hubURL they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs.

By default, the Gaia hub will validate that the supplied URL matches https://${config.serverName}, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your config.json:

{
  ....
  serverName: "normalserver.com"
  validHubUrls: [ "https://specialserver.com/",
                  "https://legacyurl.info" ]
  ....
}

The readURL parameter

By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the readURL parameter to tell the gaia hub that files can be read from the given URL. For example, the hub.blockstack.org Gaia Hub is configured to return a read URL that looks like https://gaia.blockstack.org/hub/.

Unset this configuration parameter if you do not intend to deploy any caching.

Minimum Proofs Requirement

The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the proofsConfig.proofsRequired configuration key to 0.

CDN & Replicated Hubs

  • https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn

  • The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given bucket (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior.

🧠
GAIA Admin Service
config.json