Locations only¶

When the GraphQL endpoint must live in a server {} you already have (same domain, same TLS certificate, next to other locations), render with --locations-only. You get two files instead of one.

flowchart LR
    toml[gqlgw.toml] --> r["gqlc render --locations-only"]
    r --> h["gqlgw.http.conf<br/>shm · init_by_lua · upstreams<br/>admin server (metrics, purge)"]
    r --> l["gqlgw.locations.conf<br/>location = /api/graphql<br/>location /_src/#lt;source#gt;/"]
    r --> lua[gqlgw.lua]
    h -- "include in http {}" --> ng[your nginx.conf]
    l -- "include in your server {}" --> ng

# Locations-only mode: the gateway is served by an existing server {} (its TLS,
# its domain, its other locations). `gqlc render --locations-only` writes:
#   gqlgw.http.conf       to include inside http { }
#   gqlgw.locations.conf  to include inside your server { }
#
# render: --locations-only
#   gqlc compile -c gqlgw.toml ../docker/schema.graphqls
#   gqlc render  -c gqlgw.toml -o /etc/nginx/gqlgw --locations-only

[gateway]
path = "/api/graphql"
introspection = false

[cache]
shm_size = "32m"

[metrics]
port = 8191                               # the admin server {} stays in gqlgw.http.conf

[sources.users]
url = "http://127.0.0.1:9001"

[sources.posts]
url = "http://127.0.0.1:9002"

# An existing nginx configuration that serves gqlgw from its own server {}.
events {}

http {
    include /etc/nginx/gqlgw/gqlgw.http.conf;      # shm, init_by_lua, upstreams, admin server

    server {
        listen 443 ssl;
        server_name www.example.com;
        ssl_certificate     /etc/ssl/example.com.pem;
        ssl_certificate_key /etc/ssl/example.com.key;

        location / {
            root /srv/www;                         # the rest of the site
        }

        include /etc/nginx/gqlgw/gqlgw.locations.conf;   # /api/graphql + /_src/<source>/
    }
}

gqlc compile -c gqlgw.toml schema.graphqls
gqlc render  -c gqlgw.toml -o /etc/nginx/gqlgw --locations-only
nginx -t && nginx -s reload

What goes where¶

The generated GraphQL location:

location = /api/graphql {
    set $gqlgw_path "";        # variables used by the /_src/ locations and the access log
    set $gqlgw_ctype "";
    set $gql_rounds "-";
    set $gql_subrequests "-";
    set $gql_cache "-";
    client_max_body_size 1m;   # [gateway] max_body
    client_body_buffer_size 1m;
    content_by_lua_block { require("gqlgw").serve() }
    log_by_lua_block { require("gqlgw").log() }
}

Things to note¶

• [gateway] listen and server_name are ignored in this mode: the host server {} decides.
• The admin server (metrics, purge) stays a separate server {} on its own port, in gqlgw.http.conf. Set [metrics] enabled = false and [purge] enabled = false to drop it.
• /_src/ is reserved in the host server: the generated locations are internal, so a client cannot reach them, but you cannot use that prefix for anything else.
• Only one init_by_lua is allowed per http {}. If yours exists, set [nginx] init = false and call require("gqlgw").init("/etc/nginx/gqlgw/gqlgw.lua") in it. See Existing nginx / OpenResty.