From 26ea67d6f35e65b8e2974782a71ec791d77c9ee1 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Wed, 22 Apr 2026 16:30:45 -0500 Subject: [PATCH 1/3] docs: rewrite BlazeGraph connection guide with practical instructions --- docs/guides/connecting-to-blazegraph.md | 54 ++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/docs/guides/connecting-to-blazegraph.md b/docs/guides/connecting-to-blazegraph.md index 5caeba8ed..d56187ec9 100644 --- a/docs/guides/connecting-to-blazegraph.md +++ b/docs/guides/connecting-to-blazegraph.md @@ -2,5 +2,55 @@ # Connecting to BlazeGraph -- Build and run the Docker container as normal and connect Graph Explorer to BlazeGraph through the proxy server. -- If using Docker, ensure that the container running Graph Explorer can properly access the container running BlazeGraph. You can find documentation on how to connect containers via [Docker networks](https://docs.docker.com/network/). +[BlazeGraph](https://blazegraph.com/) is an open-source RDF graph database that supports the SPARQL query language. Graph Explorer connects to BlazeGraph through its SPARQL endpoint. + +## Running BlazeGraph with Docker + +Pull and run the BlazeGraph Docker image: + +``` +docker run -d -p 9999:9999 --name blazegraph lyrasis/blazegraph:2.1.5 +``` + +You can verify BlazeGraph is running by visiting `http://localhost:9999/blazegraph/` in your browser. + +## Connecting Graph Explorer + +Open Graph Explorer and add a new connection with the following settings: + +- Name: `BlazeGraph` +- Query Language: `SPARQL` +- Public or Proxy Endpoint: `https://localhost` +- Using Proxy Server: `true` +- Graph Connection URL: `http://localhost:9999/blazegraph/namespace/kb/sparql` + +> [!NOTE] +> +> The default namespace in BlazeGraph is `kb`. If you created a custom namespace, replace `kb` with your namespace name in the Graph Connection URL. + +## Docker Networking + +If both Graph Explorer and BlazeGraph are running as Docker containers, they need to communicate over a shared Docker network. The default `localhost` address won't work between containers. + +1. Create a Docker network: + ``` + docker network create graph-net + ``` +2. Run BlazeGraph on the network: + ``` + docker run -d -p 9999:9999 --name blazegraph --network graph-net lyrasis/blazegraph:2.1.5 + ``` +3. Run Graph Explorer on the same network: + ``` + docker run -p 80:80 -p 443:443 \ + --name graph-explorer \ + --network graph-net \ + --env HOST=localhost \ + public.ecr.aws/neptune/graph-explorer + ``` +4. Use the container name as the hostname in the Graph Connection URL: + ``` + http://blazegraph:9999/blazegraph/namespace/kb/sparql + ``` + +For more details on container networking, see the [Docker networks documentation](https://docs.docker.com/network/). From 5658199db363cdf6b2c626593dfc26565a9fddd2 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Mon, 4 May 2026 12:15:34 -0500 Subject: [PATCH 2/3] docs: add reverse proxy workaround and troubleshooting for BlazeGraph guide Address review findings: - Explain proxy server path stripping limitation with nginx workaround - Add --restart unless-stopped to Docker command - Note BlazeGraph 2.1.5 is the final release - Add tables explaining connection settings and Docker options - Add troubleshooting section for common issues --- docs/guides/connecting-to-blazegraph.md | 127 ++++++++++++++++++------ 1 file changed, 98 insertions(+), 29 deletions(-) diff --git a/docs/guides/connecting-to-blazegraph.md b/docs/guides/connecting-to-blazegraph.md index d56187ec9..f9adff64e 100644 --- a/docs/guides/connecting-to-blazegraph.md +++ b/docs/guides/connecting-to-blazegraph.md @@ -4,6 +4,10 @@ [BlazeGraph](https://blazegraph.com/) is an open-source RDF graph database that supports the SPARQL query language. Graph Explorer connects to BlazeGraph through its SPARQL endpoint. +> [!NOTE] +> +> BlazeGraph 2.1.5 is the final release. The project is no longer actively maintained. + ## Running BlazeGraph with Docker Pull and run the BlazeGraph Docker image: @@ -16,41 +20,106 @@ You can verify BlazeGraph is running by visiting `http://localhost:9999/blazegra ## Connecting Graph Explorer +Graph Explorer's proxy server expects the SPARQL endpoint at `/sparql` on the database host, but BlazeGraph serves it at `/blazegraph/namespace//sparql`. To bridge this gap, you need a reverse proxy (such as nginx) in front of BlazeGraph that rewrites the path. + +### Setting Up the Reverse Proxy + +Create an `nginx.conf` file: + +```nginx +events {} +http { + server { + listen 8080; + location /sparql { + proxy_pass http://blazegraph:9999/blazegraph/namespace/kb/sparql; + } + } +} +``` + +> [!NOTE] +> +> The default namespace in BlazeGraph is `kb`. If you created a custom namespace, replace `kb` with your namespace name in the `proxy_pass` URL. + +Then run nginx alongside BlazeGraph on a shared Docker network: + +``` +docker network create graph-net +docker run -d -p 9999:9999 --name blazegraph --network graph-net lyrasis/blazegraph:2.1.5 +docker run -d --name blazegraph-proxy --network graph-net -p 8080:8080 -v ./nginx.conf:/etc/nginx/nginx.conf:ro nginx:stable-alpine +``` + +### Connection Settings + Open Graph Explorer and add a new connection with the following settings: - Name: `BlazeGraph` - Query Language: `SPARQL` - Public or Proxy Endpoint: `https://localhost` - Using Proxy Server: `true` -- Graph Connection URL: `http://localhost:9999/blazegraph/namespace/kb/sparql` +- Graph Connection URL: `http://blazegraph-proxy:8080` -> [!NOTE] -> -> The default namespace in BlazeGraph is `kb`. If you created a custom namespace, replace `kb` with your namespace name in the Graph Connection URL. - -## Docker Networking - -If both Graph Explorer and BlazeGraph are running as Docker containers, they need to communicate over a shared Docker network. The default `localhost` address won't work between containers. - -1. Create a Docker network: - ``` - docker network create graph-net - ``` -2. Run BlazeGraph on the network: - ``` - docker run -d -p 9999:9999 --name blazegraph --network graph-net lyrasis/blazegraph:2.1.5 - ``` -3. Run Graph Explorer on the same network: - ``` - docker run -p 80:80 -p 443:443 \ - --name graph-explorer \ - --network graph-net \ - --env HOST=localhost \ - public.ecr.aws/neptune/graph-explorer - ``` -4. Use the container name as the hostname in the Graph Connection URL: - ``` - http://blazegraph:9999/blazegraph/namespace/kb/sparql - ``` +| Setting | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| **Public or Proxy Endpoint** | The URL where Graph Explorer is accessible in your browser. | +| **Using Proxy Server** | Enables the Graph Explorer proxy server, which forwards requests to the database. | +| **Graph Connection URL** | The URL the proxy server uses to reach the database. Points to the nginx reverse proxy, which rewrites the path for BlazeGraph. | + +## Running Graph Explorer with Docker + +If Graph Explorer is also running as a Docker container, it needs to be on the same network: + +``` +docker run -p 80:80 -p 443:443 \ + --name graph-explorer \ + --network graph-net \ + --restart unless-stopped \ + --env HOST=localhost \ + public.ecr.aws/neptune/graph-explorer +``` + +| Option | Description | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `-p 80:80 -p 443:443` | Maps HTTP and HTTPS ports from the container to the host. | +| `--network graph-net` | Connects the container to the shared Docker network so it can reach BlazeGraph and the reverse proxy by container name. | +| `--restart unless-stopped` | Automatically restarts the container on failure or host reboot, unless explicitly stopped. | +| `--env HOST=localhost` | Sets the hostname used in the self-signed TLS certificate generated by Graph Explorer. | + +Then update the **Graph Connection URL** to use the container name: `http://blazegraph-proxy:8080` For more details on container networking, see the [Docker networks documentation](https://docs.docker.com/network/). + +## Troubleshooting + +### Schema sync fails or queries return errors + +Graph Explorer's proxy server appends `/sparql` to the Graph Connection URL when making SPARQL requests. BlazeGraph does not serve its SPARQL endpoint at `/sparql` — it uses `/blazegraph/namespace//sparql` instead. If you see connection errors or empty results, verify that the reverse proxy is running and correctly rewriting the path. + +Test the reverse proxy directly: + +``` +curl -X POST http://localhost:8080/sparql \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "query=SELECT * WHERE { ?s ?p ?o } LIMIT 1" +``` + +If this returns SPARQL results, the reverse proxy is working. If it returns a 404 or connection error, check the nginx configuration and ensure all containers are on the same Docker network. + +### Connection refused between containers + +If Graph Explorer cannot reach BlazeGraph, verify all containers are on the same Docker network: + +``` +docker network inspect graph-net +``` + +The default `localhost` address does not work between Docker containers. Use container names (e.g., `blazegraph`, `blazegraph-proxy`) as hostnames instead. + +### BlazeGraph UI not accessible + +If you cannot reach `http://localhost:9999/blazegraph/` in your browser, check that the container is running: + +``` +docker ps --filter name=blazegraph +``` From 6b6b2c674b8d7bb2fd8101ee1a05afe9c44516f8 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Mon, 11 May 2026 10:53:52 -0500 Subject: [PATCH 3/3] Remove reverse proxy requirement from BlazeGraph guide The proxy server now preserves URL paths, so users can connect directly to BlazeGraph's SPARQL endpoint without nginx in between. --- docs/guides/connecting-to-blazegraph.md | 76 ++++++++----------------- 1 file changed, 24 insertions(+), 52 deletions(-) diff --git a/docs/guides/connecting-to-blazegraph.md b/docs/guides/connecting-to-blazegraph.md index f9adff64e..5f56e628a 100644 --- a/docs/guides/connecting-to-blazegraph.md +++ b/docs/guides/connecting-to-blazegraph.md @@ -20,57 +20,31 @@ You can verify BlazeGraph is running by visiting `http://localhost:9999/blazegra ## Connecting Graph Explorer -Graph Explorer's proxy server expects the SPARQL endpoint at `/sparql` on the database host, but BlazeGraph serves it at `/blazegraph/namespace//sparql`. To bridge this gap, you need a reverse proxy (such as nginx) in front of BlazeGraph that rewrites the path. - -### Setting Up the Reverse Proxy - -Create an `nginx.conf` file: - -```nginx -events {} -http { - server { - listen 8080; - location /sparql { - proxy_pass http://blazegraph:9999/blazegraph/namespace/kb/sparql; - } - } -} -``` - -> [!NOTE] -> -> The default namespace in BlazeGraph is `kb`. If you created a custom namespace, replace `kb` with your namespace name in the `proxy_pass` URL. - -Then run nginx alongside BlazeGraph on a shared Docker network: - -``` -docker network create graph-net -docker run -d -p 9999:9999 --name blazegraph --network graph-net lyrasis/blazegraph:2.1.5 -docker run -d --name blazegraph-proxy --network graph-net -p 8080:8080 -v ./nginx.conf:/etc/nginx/nginx.conf:ro nginx:stable-alpine -``` - -### Connection Settings - Open Graph Explorer and add a new connection with the following settings: - Name: `BlazeGraph` - Query Language: `SPARQL` - Public or Proxy Endpoint: `https://localhost` - Using Proxy Server: `true` -- Graph Connection URL: `http://blazegraph-proxy:8080` +- Graph Connection URL: `http://localhost:9999/blazegraph/namespace/kb/sparql` -| Setting | Description | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| **Public or Proxy Endpoint** | The URL where Graph Explorer is accessible in your browser. | -| **Using Proxy Server** | Enables the Graph Explorer proxy server, which forwards requests to the database. | -| **Graph Connection URL** | The URL the proxy server uses to reach the database. Points to the nginx reverse proxy, which rewrites the path for BlazeGraph. | +| Setting | Description | +| ---------------------------- | --------------------------------------------------------------------------------- | +| **Public or Proxy Endpoint** | The URL where Graph Explorer is accessible in your browser. | +| **Using Proxy Server** | Enables the Graph Explorer proxy server, which forwards requests to the database. | +| **Graph Connection URL** | The full URL to the BlazeGraph SPARQL endpoint, including the namespace path. | + +> [!NOTE] +> +> The default namespace in BlazeGraph is `kb`. If you created a custom namespace, replace `kb` with your namespace name in the Graph Connection URL. ## Running Graph Explorer with Docker -If Graph Explorer is also running as a Docker container, it needs to be on the same network: +If Graph Explorer is also running as a Docker container, it needs to be on the same network as BlazeGraph: ``` +docker network create graph-net +docker run -d -p 9999:9999 --name blazegraph --network graph-net lyrasis/blazegraph:2.1.5 docker run -p 80:80 -p 443:443 \ --name graph-explorer \ --network graph-net \ @@ -79,14 +53,14 @@ docker run -p 80:80 -p 443:443 \ public.ecr.aws/neptune/graph-explorer ``` -| Option | Description | -| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `-p 80:80 -p 443:443` | Maps HTTP and HTTPS ports from the container to the host. | -| `--network graph-net` | Connects the container to the shared Docker network so it can reach BlazeGraph and the reverse proxy by container name. | -| `--restart unless-stopped` | Automatically restarts the container on failure or host reboot, unless explicitly stopped. | -| `--env HOST=localhost` | Sets the hostname used in the self-signed TLS certificate generated by Graph Explorer. | +| Option | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------- | +| `-p 80:80 -p 443:443` | Maps HTTP and HTTPS ports from the container to the host. | +| `--network graph-net` | Connects the container to the shared Docker network so it can reach BlazeGraph by container name. | +| `--restart unless-stopped` | Automatically restarts the container on failure or host reboot, unless explicitly stopped. | +| `--env HOST=localhost` | Sets the hostname used in the self-signed TLS certificate generated by Graph Explorer. | -Then update the **Graph Connection URL** to use the container name: `http://blazegraph-proxy:8080` +When both containers are on the same network, update the **Graph Connection URL** to use the container name: `http://blazegraph:9999/blazegraph/namespace/kb/sparql` For more details on container networking, see the [Docker networks documentation](https://docs.docker.com/network/). @@ -94,17 +68,15 @@ For more details on container networking, see the [Docker networks documentation ### Schema sync fails or queries return errors -Graph Explorer's proxy server appends `/sparql` to the Graph Connection URL when making SPARQL requests. BlazeGraph does not serve its SPARQL endpoint at `/sparql` — it uses `/blazegraph/namespace//sparql` instead. If you see connection errors or empty results, verify that the reverse proxy is running and correctly rewriting the path. - -Test the reverse proxy directly: +Verify that the SPARQL endpoint is reachable by testing it directly: ``` -curl -X POST http://localhost:8080/sparql \ +curl -X POST http://localhost:9999/blazegraph/namespace/kb/sparql \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "query=SELECT * WHERE { ?s ?p ?o } LIMIT 1" ``` -If this returns SPARQL results, the reverse proxy is working. If it returns a 404 or connection error, check the nginx configuration and ensure all containers are on the same Docker network. +If this returns SPARQL results, BlazeGraph is working correctly. If it returns a 404, check that the namespace in the URL matches your BlazeGraph configuration. ### Connection refused between containers @@ -114,7 +86,7 @@ If Graph Explorer cannot reach BlazeGraph, verify all containers are on the same docker network inspect graph-net ``` -The default `localhost` address does not work between Docker containers. Use container names (e.g., `blazegraph`, `blazegraph-proxy`) as hostnames instead. +The default `localhost` address does not work between Docker containers. Use container names (e.g., `blazegraph`) as hostnames instead. ### BlazeGraph UI not accessible