> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hasura

> Ready-to-run Hasura container stack you can run directly or inherit to integrate instant GraphQL APIs on top of your databases.

## Overview

This template provides a production‑ready Hasura stack as a Monk runnable. You can:

* Run it directly to get a managed Hasura deployment with PostgreSQL metadata storage
* Inherit it in your own runnable to seamlessly add instant GraphQL APIs to your databases

Hasura is an open-source engine that connects to your databases and instantly provides a production-ready GraphQL API. It supports PostgreSQL, MySQL, SQL Server, and other databases with real-time subscriptions, authorization, and event triggers.

## What this template manages

* Hasura GraphQL Engine container (`hasura/graphql-engine` image)
* PostgreSQL database for metadata storage
* Network service on port 8080 (Hasura Console & GraphQL endpoint)
* Real-time GraphQL subscriptions
* Authorization and authentication
* Persistent volumes for data storage

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Hasura stack

```bash theme={null}
monk run hasura/stack
```

3. Access the Hasura Console

Once started, open your browser to `http://localhost:8080/console` to access the Hasura Console.

Default admin secret: `monk` (recommended to change in production via inheritance)

4. Connect your databases

In the Hasura Console, navigate to the "Data" tab to connect your existing databases or create new tables.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  hasura_admin_secret: "monk"                              # Admin secret for console access (env: HASURA_GRAPHQL_ADMIN_SECRET)
  hasura_graphql_cnsl: true                               # Enable Hasura Console (env: HASURA_GRAPHQL_ENABLE_CONSOLE)
  hasura_graphql_dev: true                                # Enable dev mode (env: HASURA_GRAPHQL_DEV_MODE)
  hasura_graphql_log_types: "startup, http-log, ..."     # Log types (env: HASURA_GRAPHQL_ENABLED_LOG_TYPES)
  db_hasura: "postgres://monk:monk@<host>:5432/monk"     # Metadata database URL (env: HASURA_GRAPHQL_METADATA_DATABASE_URL)
  db: "postgres://monk:monk@<host>:5432/monk"            # Primary database URL (env: PG_DATABASE_URL)
```

PostgreSQL (metadata storage) variables:

```yaml theme={null}
variables:
  image-tag: "latest"              # PostgreSQL container image tag
  db-password: "monk"              # PostgreSQL password (env: POSTGRES_PASSWORD)
  db-user: "monk"                  # PostgreSQL user (env: POSTGRES_USER)
  db-name: "monk"                  # PostgreSQL database (env: POSTGRES_DB)
  db-port: 5432                    # PostgreSQL port
```

Data is persisted under `${monk-volume-path}/growthbook` on the host.

## Use by inheritance (recommended for apps)

Inherit the Hasura stack in your application and declare connections. Example:

```yaml theme={null}
namespace: myapp
graphql:
  defines: runnable
  inherits: hasura/hasura
  connections:
    database:
      runnable: myapp/postgres  # Your application database
      service: postgres-service
  variables:
    hasura_admin_secret:
      value: <- secret("hasura-admin-secret")
    db:
      env: PG_DATABASE_URL
      value: <- `postgres://${db-user}:${db-password}@${db-host}:5432/${db-name}`
    db-user:
      value: <- secret("postgres-user")
    db-password:
      value: <- secret("postgres-password")
    db-host:
      value: <- connection-hostname("database")
    db-name:
      value: <- secret("postgres-database")

postgres:
  defines: runnable
  inherits: postgresql/postgres
```

Then set the secrets once and run your app:

```bash theme={null}
monk secrets add -g hasura-admin-secret="YOUR_STRONG_SECRET"
monk secrets add -g postgres-user="appuser"
monk secrets add -g postgres-password="STRONG_PASSWORD"
monk secrets add -g postgres-database="appdb"
monk run myapp/graphql
```

## Stack components

* `hasura/hasura` - Hasura GraphQL Engine (port 8080)
* `hasura/hasura-db` - PostgreSQL database for metadata storage (port 5432)

The stack automatically manages the connection between Hasura and its metadata database.

## Ports and connectivity

* Service: `hasura-svc` on TCP port `8080` (GraphQL API & Console)
* Metadata DB: `hasura-db-svc` on TCP port `5432` (internal use)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Hasura host.

GraphQL endpoint: `http://\<hasura-host>:8080/v1/graphql`
Console: `http://\<hasura-host>:8080/console`

## Persistence and configuration

* Data path: `${monk-volume-path}/growthbook:/usr/local/src/app/packages/back-end/uploads`
* PostgreSQL metadata is stored in the `hasura-db` container's internal volumes
* You can customize Hasura behavior through environment variables (see Configuration section)

## Features

* Instant GraphQL APIs on existing databases
* Real-time GraphQL subscriptions with live queries
* Authorization with row-level security and role-based access control
* Remote schemas to stitch external GraphQL APIs
* Actions to extend your schema with custom business logic
* Event triggers for asynchronous business logic
* Scheduled triggers for cron-like functionality
* Database migrations and schema management

## Related templates

* See other templates in this repository for complementary services
* Combine with `postgresql/` for your primary application database
* Integrate with `redis/` for caching and rate limiting
* Use with monitoring tools (`prometheus-grafana/`) for observability
* Pair with authentication services for complete auth workflows

## Troubleshooting

* If you changed `hasura_admin_secret` but can't access the console, ensure you're using the correct secret in the `x-hasura-admin-secret` header or console login.
* Ensure the metadata database is healthy before Hasura starts. The template includes a readiness check and `wait-for` dependency.
* For production deployments, disable dev mode (`hasura_graphql_dev: false`) and consider disabling the console (`hasura_graphql_cnsl: false`).
* Check Hasura logs:

```bash theme={null}
monk logs -l 500 -f hasura/hasura
```

* Check PostgreSQL metadata database logs:

```bash theme={null}
monk logs -l 500 -f hasura/hasura-db
```

* Check stack health:

```bash theme={null}
monk describe hasura/stack
```