mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 20:41:49 +03:00
866476ab36
GITHUB_PR_NUMBER: 8011 GITHUB_PR_URL: https://github.com/hasura/graphql-engine/pull/8011 PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3317 Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> GitOrigin-RevId: 90c8f75003a07c5153c9e478efa599ab0bfb85d9
184 lines
6.0 KiB
ReStructuredText
184 lines
6.0 KiB
ReStructuredText
.. meta::
|
|
:description: Get started with Hasura using Docker
|
|
:keywords: hasura, docs, start, docker
|
|
|
|
.. _docker_simple:
|
|
|
|
Quickstart with Docker
|
|
======================
|
|
|
|
.. contents:: Table of contents
|
|
:backlinks: none
|
|
:depth: 1
|
|
:local:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
This guide will help you get the Hasura GraphQL engine and a Postgres database to store its metadata
|
|
running as Docker containers using Docker Compose. This is the easiest way to set up
|
|
Hasura GraphQL engine on your **local environment**.
|
|
|
|
Prerequisites
|
|
-------------
|
|
|
|
- `Docker <https://docs.docker.com/install/>`__
|
|
- `Docker Compose <https://docs.docker.com/compose/install/>`__
|
|
|
|
Step 1: Get the docker-compose file
|
|
-----------------------------------
|
|
|
|
The `hasura/graphql-engine/install-manifests <https://github.com/hasura/graphql-engine/tree/stable/install-manifests>`__ repo
|
|
contains all installation manifests required to deploy Hasura anywhere. Get the docker compose file from there:
|
|
|
|
.. code-block:: bash
|
|
|
|
# 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.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ docker-compose up -d
|
|
|
|
Check if the containers are running:
|
|
|
|
.. code-block:: 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 ...
|
|
|
|
Step 3: Connect a database
|
|
--------------------------
|
|
|
|
Head to ``http://localhost:8080/console`` to open the Hasura console.
|
|
|
|
Navigate to ``Data -> Manage -> Connect Database``:
|
|
|
|
.. thumbnail:: /img/graphql/cloud/getting-started/connect-db-console.png
|
|
:alt: Connect database
|
|
:width: 1000px
|
|
|
|
Enter your database connection URL. *(See the note below if you do not have an existing database)*
|
|
|
|
Click ``Connect Database``.
|
|
|
|
.. thumbnail:: /img/graphql/core/getting-started/connect-db.png
|
|
:alt: Enter URL for existing database
|
|
:width: 700px
|
|
|
|
.. admonition:: Starting from scratch
|
|
|
|
If you are looking to start setting up a backend from scratch, we recommend
|
|
using Postgres as the database.
|
|
|
|
If you do not have an existing Postgres database, you can choose to connect to the Postgres
|
|
database that was created along with Hasura (to store its metadata) and use it as a data source as well.
|
|
The docker-compose file has an additional env var ``PG_DATABASE_URL`` which points to the created metadata database.
|
|
You can use this env var to connect the same database as a data source and continue.
|
|
|
|
Step 4: Try out Hasura
|
|
----------------------
|
|
|
|
.. TODO: add options to track existing vs create new tables
|
|
|
|
Create a table
|
|
^^^^^^^^^^^^^^
|
|
|
|
On the Hasura console, navigate to ``Data -> Create table`` and create a sample table called ``profiles`` with
|
|
the following columns:
|
|
|
|
.. code-block:: sql
|
|
|
|
profiles (
|
|
id SERIAL PRIMARY KEY, -- serial -> auto-incrementing integer
|
|
name TEXT
|
|
)
|
|
|
|
.. thumbnail:: /img/graphql/core/getting-started/create-profile-table.png
|
|
:alt: Create a table
|
|
:width: 1200px
|
|
|
|
Now, insert some sample data into the table using the ``Insert Row`` tab of the ``profiles`` table.
|
|
|
|
Try out a query
|
|
^^^^^^^^^^^^^^^
|
|
|
|
Head to the ``GraphiQL`` tab in the console and try running the following query:
|
|
|
|
.. code-block:: graphql
|
|
|
|
query {
|
|
profiles {
|
|
id
|
|
name
|
|
}
|
|
}
|
|
|
|
You'll see that you get all the inserted data!
|
|
|
|
.. thumbnail:: /img/graphql/core/getting-started/profile-query.png
|
|
:alt: Try out a query
|
|
:width: 1200px
|
|
|
|
Next steps
|
|
----------
|
|
|
|
Learn course
|
|
^^^^^^^^^^^^
|
|
|
|
For a full hands-on tour of Hasura, check out our `30-Minute Hasura Basics Course <https://hasura.io/learn/graphql/hasura/introduction/>`__.
|
|
|
|
Stay up to date
|
|
^^^^^^^^^^^^^^^
|
|
|
|
We release new features every month. Sign up for our newsletter by using the link below. We send newsletters only once a month.
|
|
`https://hasura.io/newsletter/ <https://hasura.io/newsletter/>`__.
|
|
|
|
Database operations
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
- :ref:`Database modelling <pg_schema>`: Learn how to model your database schema, as well as how to extend it.
|
|
- :ref:`Querying data <pg_queries>`: Use GraphQL queries to query data from your GraphQL API.
|
|
- :ref:`Inserting data <pg_mutations>`: Use GraphQL mutations to insert data into your GraphQL API.
|
|
|
|
Business logic
|
|
^^^^^^^^^^^^^^
|
|
|
|
There are several options for the implementation of business logic, depending on your use case.
|
|
|
|
- :ref:`Actions <actions>`: Actions can be used if you'd like to extend your GraphQL schema by integrating with a REST endpoint.
|
|
- :ref:`Remote schemas <remote_schemas>`: If you have an existing GraphQL server or if you're comfortable with implementing one, you can use remote schemas.
|
|
- :ref:`Event triggers <event_triggers>`: To trigger a serverless function based on a database event, use event triggers.
|
|
- :ref:`Scheduled triggers <scheduled_triggers>`: Scheduled triggers are used to execute custom business logic at specific points in time.
|
|
|
|
Migrations
|
|
^^^^^^^^^^
|
|
|
|
Set up :ref:`Hasura migrations <migrations_setup>` to track your database alterations. This will make it easier to move to a different environment (e.g. staging or prod) later.
|
|
|
|
Secure your endpoint
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
:ref:`Add an admin secret <docker_secure>` to make sure that your GraphQL endpoint and the Hasura console are not publicly accessible.
|
|
|
|
Detailed Docker setup
|
|
---------------------
|
|
|
|
This was a quickstart guide to get the Hasura GraphQL engine up and running
|
|
quickly. For more detailed instructions on deploying using Docker, check out
|
|
:ref:`deployment_docker`.
|
|
|
|
.. admonition:: Additional Resources
|
|
|
|
Get Started with Hasura today - `Watch video guide <https://hasura.io/events/webinar/get-started-with-hasura/?pg=docs&plcmt=body&cta=getting-started&tech=>`__.
|