diff --git a/docs/guides/connecting-to-blazegraph.md b/docs/guides/connecting-to-blazegraph.md index 5caeba8ed..5f56e628a 100644 --- a/docs/guides/connecting-to-blazegraph.md +++ b/docs/guides/connecting-to-blazegraph.md @@ -2,5 +2,96 @@ # 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. + +> [!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: + +``` +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` + +| 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 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 \ + --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 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. | + +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/). + +## Troubleshooting + +### Schema sync fails or queries return errors + +Verify that the SPARQL endpoint is reachable by testing it directly: + +``` +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, BlazeGraph is working correctly. If it returns a 404, check that the namespace in the URL matches your BlazeGraph configuration. + +### 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`) 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 +```