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:
# in a new directory run
wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-compose/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/stable/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.
$ docker-compose up -d
Check if the containers are running:
$ 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
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
graphql-engine:
image: hasura/graphql-engine:v2.0.0
environment:
HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:[email protected]:5432/postgres
HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
...
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.
Hasura GraphQL engine server logs
You can check the logs of the Hasura GraphQL engine deployed using Docker by checking the logs of the GraphQL engine container:
$ 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:
- https://docs.docker.com/config/containers/logging for more details on logging in Docker.
- Hasura GraphQL engine logs for more details on Hasura logs.
Updating Hasura GraphQL engine
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:
hasura/graphql-engine:v2.3.0
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:
graphql-engine:
image: hasura/graphql-engine:v1.2.0
you should change it to:
graphql-engine:
image: hasura/graphql-engine:v2.3.0
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