ContextQMD
Back to Graphql Engine

Docker

docs/docs/deployment/deployment-guides/docker.mdx

2.50.19.8 KB
Original Source

import LatestRelease from '@site/src/components/LatestRelease'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Run Hasura GraphQL Engine Using Docker

Introduction

This guide will help you deploy the Hasura GraphQL Engine and a Postgres database to store its Metadata using Docker Compose.

Deploying Hasura using Docker

Prerequisites

Step 1: Get the docker-compose file

The hasura/graphql-engine/install-manifests repo contains all installation manifests required to deploy Hasura anywhere. Get the docker compose file from there:

bash
# in a new directory run
wget https://raw.githubusercontent.com/hasura/graphql-engine/main/install-manifests/docker-compose/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/main/install-manifests/docker-compose/docker-compose.yaml -o docker-compose.yml

Step 2: Run Hasura GraphQL Engine

The following command will run Hasura GraphQL Engine along with a Postgres database to store its Metadata.

bash
$ docker compose up -d

Check if the containers are running:

bash
$ docker ps

CONTAINER ID IMAGE                 ... CREATED STATUS PORTS          ...
097f58433a2b hasura/graphql-engine ... 1m ago  Up 1m  8080->8080/tcp ...
b0b1aac0508d postgres              ... 1m ago  Up 1m  5432/tcp       ...

Securing the GraphQL endpoint {#docker-secure}

To make sure that your GraphQL endpoint and the Hasura Console are not publicly accessible, you need to configure an admin secret key.

Run the Docker container with an admin-secret env var

yaml
graphql-engine:
  image: hasura/graphql-engine:v2.0.0
  environment:
    HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
    HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
  ...

:::info Note

The HASURA_GRAPHQL_ADMIN_SECRET should never be passed from the client to the Hasura GraphQL Engine as it would give the client full admin rights to your Hasura instance. See Authentication & Authorization for information on setting up authentication.

:::

<!-- .. hiding this as it mixes auth for the data plane with auth for the control plane and might be confusing .. admonition:: Using collaborators as an alternative to Hasura Admin Secret sharing with Hasura Cloud :class: dhc Hasura Cloud offers Console collaborators which avoids sharing the `HASURA-ADMIN-SECRET` with those that shouldn't have unrestricted access to your project. For more information about collaborator management, see :ref:`Collaborators in Hasura Cloud <manage_project_collaborators>`. -->

Hasura GraphQL Engine server logs {#docker-logs}

You can check the logs of the Hasura GraphQL Engine deployed using Docker by checking the logs of the GraphQL Engine container:

bash
$ docker ps

CONTAINER ID IMAGE                 ... CREATED STATUS PORTS          ...
097f58433a2b hasura/graphql-engine ... 1m ago  Up 1m  8080->8080/tcp ...
b0b1aac0508d postgres              ... 1m ago  Up 1m  5432/tcp       ...


$ docker logs 097f58433a2b

{"timestamp":"2018-10-09T11:20:32.054+0000", "level":"info", "type":"http-log", "detail":{"status":200, "query_hash":"01640c6dd131826cff44308111ed40d7fbd1cbed", "http_version":"HTTP/1.1", "query_execution_time":3.0177627e-2, "request_id":null, "url":"/v1/graphql", "user":{"x-hasura-role":"admin"}, "ip":"127.0.0.1", "response_size":209329, "method":"POST", "detail":null}}
...

See:

Updating Hasura GraphQL Engine {#docker-update}

This guide will help you update the Hasura GraphQL Engine running with Docker. This guide assumes that you already have Hasura GraphQL Engine running with Docker.

Step 1: Check the latest release version

The current latest version is:

<code> hasura/graphql-engine: <LatestRelease /> </code>

All the versions can be found at: https://github.com/hasura/graphql-engine/releases

Step 2: Update the Docker image

In the docker compose command that you're running, update the image tag to this latest version.

For example, if you had:

yaml
graphql-engine:
  image: hasura/graphql-engine:v1.2.0

you should change it to:

<pre> <code> graphql-engine: {' '}image: hasura/graphql-engine: <LatestRelease /> </code> </pre>

:::info Note

If you are downgrading to an older version of the GraphQL Engine you might need to downgrade your Metadata catalogue version as described in Downgrading Hasura GraphQL Engine

:::

Docker networking

Sometimes you might want to connect Hasura running in Docker with APIs (e.g. auth webhooks, Event Triggers, Remote Schemas) that are either running outside of Docker or in a different Docker container. Depending on the setting, the network config is different. This section shows how to connect in each of these use cases.

Network config

<Tabs groupId="user-preference" className="api-tabs"> <TabItem value="linux" label="Linux"> <table> <thead> <tr> <th>Connection</th> <th>Config</th> <th>Comment</th> </tr> </thead> <tbody> <tr> <td> <strong>Hasura to API (outside Docker)</strong> </td> <td> <ol type="1"> <li> With <code>--net=host</code>, <code>localhost:3000</code> </li> <li> Otherwise, <code>&lt;docker-bridge-ip&gt;:3000</code>, e.g. <code>172.17.0.1:3000</code> </li> </ol> </td> <td> <ol type="1"> <li> Assuming the API is running on port <code>3000</code> </li> <li> The Docker bridge IP can be found via <code>ifconfig</code> </li> </ol> </td> </tr> <tr> <td> <strong>API (outside Docker) to Hasura</strong> </td> <td> <code>localhost:8080</code> </td> <td> Hasura runs on port <code>8080</code> by default </td> </tr> <tr> <td> <strong>Hasura to API (both in docker-compose)</strong> </td> <td> service name, e.g.: <code>api:3000</code> </td> <td> Assuming the API is running on port <code>3000</code> </td> </tr> <tr> <td> <strong>API to Hasura (both in docker-compose)</strong> </td> <td> service name, e.g.: <code>hasura:8080</code> </td> <td> Hasura runs on port <code>8080</code> by default </td> </tr> <tr> <td> <strong>Hasura to API (both running with separate docker run)</strong> </td> <td>Docker internal IP address</td> <td> Can be obtained with <code>docker inspect</code> </td> </tr> <tr> <td> <strong>API to Hasura (both running with separate docker run)</strong> </td> <td>Docker internal IP address</td> <td> Can be obtained with <code>docker inspect</code> </td> </tr> </tbody> </table> </TabItem> <TabItem value="mac" label="Mac">
ConnectionConfigComment
Hasura to API (outside Docker)host.docker.internal:3000Assuming the API is running on port 3000
API (outside Docker) to Hasuralocalhost:8080Hasura runs on port 8080 by default
Hasura to API (both in docker-compose)service name, e.g.: api:3000Assuming the API is running on port 3000
API to Hasura (both in docker-compose)service name, e.g.: hasura:8080Hasura runs on port 8080 by default
Hasura to API (both running with separate docker run)Docker internal IP addressCan be obtained with docker inspect
API to Hasura (both running with separate docker run)Docker internal IP addressCan be obtained with docker inspect
</TabItem> <TabItem value="windows" label="Windows">
ConnectionConfigComment
Hasura to API (outside Docker)host.docker.internal:3000Assuming the API is running on port 3000
API (outside Docker) to Hasuralocalhost:8080Hasura runs on port 8080 by default
Hasura to API (both in docker-compose)service name, e.g.: api:3000Assuming the API is running on port 3000
API to Hasura (both in docker-compose)service name, e.g.: hasura:8080Hasura runs on port 8080 by default
Hasura to API (both running with separate docker run)Docker internal IP addressCan be obtained with docker inspect
API to Hasura (both running with separate docker run)Docker internal IP addressCan be obtained with docker inspect
</TabItem> </Tabs>

Advanced

Learn more about Docker specific networking in the Docker documentation.