[Feature Request] Documentation to run this locally

[vemonet]

Description

I have tried to simply deploy this project locally to test it quickly on publicly available SPARQL endpoints, but the current documentation only explain in details how to deploy this on remote AWS machines in the cloud. It would be nice to be able to deploy this on a local machine easily.

I tried to use docker:

docker run -p 8000:80 --env HOST=http://localhost graph-explorer

I am getting this output:

Generating new self-signed SSL cert using http://localhost...
sed: -e expression #1, char 14: unknown option to `s'
sed: -e expression #1, char 13: unknown option to `s'
..+..........+..+.+...........+.+........+.+........+.......+...+......+...........+......+.......+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*......+...........+.+...+..+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*........+.............+.................+....+............+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.....+...+......+..+...+.+.........+..+...+....+..+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*..+....+.........+..+...+.+.........+.........+.................+...............+.+.....+...............+..........+..............+...+.+.....+.+........+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*.+...+......+...+......+...........+...+.+.....+....+.................+....+..+..........+...+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-----
Certificate request self-signature ok
subject=C = US, ST = Washington, L = Seattle, O = Graph Explorer, CN = Graph Explorer
Starting graph explorer...

> [email protected] start:proxy-server /graph-explorer
> pnpm -F graph-explorer-proxy-server start


> [email protected] start /graph-explorer/packages/graph-explorer-proxy-server
> node node-server.js

[11:40:00.702] INFO (39): Proxy server located at https://localhost
[11:40:00.702] INFO (39): Graph Explorer live at: undefined/explorer

But nothing is available on http://localhost:8000/explorer

I also tried to start it in development mode with pnpm start (on Ubuntu 22.04) but I am rightfully getting permission denied to deploy the proxy server on port 80

> [email protected] start /home/vemonet/dev/expasy/graph-explorer
> pnpm --stream -r run start

Scope: 2 of 3 workspace projects
packages/graph-explorer start$ vite
packages/graph-explorer-proxy-server start$ node node-server.js
packages/graph-explorer start:   VITE v4.5.3  ready in 142 ms
packages/graph-explorer start:   ➜  Local:   http://localhost:5173/
packages/graph-explorer start:   ➜  Network: http://130.223.241.54:5173/
packages/graph-explorer-proxy-server start: node:events:496
packages/graph-explorer-proxy-server start:       throw er; // Unhandled 'error' event
packages/graph-explorer-proxy-server start:       ^
packages/graph-explorer-proxy-server start: Error: listen EACCES: permission denied 0.0.0.0:80
packages/graph-explorer-proxy-server start:     at Server.setupListenHandle [as _listen2] (node:net:1880:21)
packages/graph-explorer-proxy-server start:     at listenInCluster (node:net:1945:12)
packages/graph-explorer-proxy-server start:     at Server.listen (node:net:2037:7)
packages/graph-explorer-proxy-server start:     at Function.listen (/home/vemonet/dev/expasy/graph-explorer/node_modules/.pnpm/[email protected]/node_modules/express/lib/application.js:635:24)
packages/graph-explorer-proxy-server start:     at Object.<anonymous> (/home/vemonet/dev/expasy/graph-explorer/packages/graph-explorer-proxy-server/node-server.js:515:7)
packages/graph-explorer-proxy-server start:     at Module._compile (node:internal/modules/cjs/loader:1369:14)
packages/graph-explorer-proxy-server start:     at Module._extensions..js (node:internal/modules/cjs/loader:1427:10)
packages/graph-explorer-proxy-server start:     at Module.load (node:internal/modules/cjs/loader:1206:32)
packages/graph-explorer-proxy-server start:     at Module._load (node:internal/modules/cjs/loader:1022:12)
packages/graph-explorer-proxy-server start:     at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:135:12)
packages/graph-explorer-proxy-server start: Emitted 'error' event on Server instance at:
packages/graph-explorer-proxy-server start:     at emitErrorNT (node:net:1924:8)
packages/graph-explorer-proxy-server start:     at process.processTicksAndRejections (node:internal/process/task_queues:82:21) {
packages/graph-explorer-proxy-server start:   code: 'EACCES',
packages/graph-explorer-proxy-server start:   errno: -13,
packages/graph-explorer-proxy-server start:   syscall: 'listen',
packages/graph-explorer-proxy-server start:   address: '0.0.0.0',
packages/graph-explorer-proxy-server start:   port: 80
packages/graph-explorer-proxy-server start: }
packages/graph-explorer-proxy-server start: Node.js v20.12.2
packages/graph-explorer-proxy-server start: Failed
/home/vemonet/dev/expasy/graph-explorer/packages/graph-explorer-proxy-server:
 ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL  [email protected] start: `node node-server.js`
Exit status 1
 ELIFECYCLE  Command failed with exit code 1.

The proxy is trying to deploy on port 80 locally which is blocked on many operating systems for security reason. What would be the best solution to bypass this issue and tell the proxy to deploy on another port than 80 when running in development?

Preferred Solution

1. In the README.md there should be a command to easily deploy the graph-explorer with docker on a local machine, and simply making it available on a non-privileged port (e.g. 8000 or 8080 or 3000, etc)

This command could use the published graph-explorer image available on ECR (https://gallery.ecr.aws/neptune/graph-explorer) to avoid having to build from source.

Ideally there would be a complete command that works out of the box with one of the many publicly available SPARQL endpoint available (e.g. https://www.bgee.org/sparql, https://sparql.uniprot.org/sparql/, https://bio2rdf.org/sparql/), that would be a really nice way to make this stack easy to test and discover for newcomers (and potential new contributors)

2. The pnpm start or pnpm dev development deployment should use a non-privileged port (e.g. 8000 or 8080 or 3000, etc)

Additional Context

I can look into it myself if necessary, but I expect some contributors already know how to do this well, so that could save us some time, and it would probably be better done by someone with already good knowledge of the stack! I can also help with documenting it for future use

Related Issues

Tasks

• Docker run command to deploy locally
• Documentation for development deployment on unprivileged port

---

Important

If you are interested in working on this issue or have submitted
a pull request, please leave a comment.

Tip

Please use a 👍 reaction to provide a +1/vote.

This helps the community and maintainers prioritize this request.

[triggan]

There's actually no need to go through the build process and create your own docker image. We push docker images of the latest builds out to the AWS ECR Public Gallery. But you are correct, we need to update the docs with this info.

Executing the following should get you started:

$ docker pull public.ecr.aws/neptune/graph-explorer:latest
$ docker run -dit -p 443:443 --name mygraphexplorer --env HOST=localhost public.ecr.aws/neptune/graph-explorer:latest

Then browse to https://localhost/explorer and accept the self-signed cert.

[kmcginnes]

@vemonet Thank you for the very detailed issue. It's always helpful when we have more details.

And, thank you @triggan for your fantastic response to this!

I agree the documentation can be improved for setup in both local dev mode and local docker runtime. I recently made some minor improvements to the dev mode setup documentation, but I can see now that we need more.

@vemonet the issue for the port has an easy solution for you. You can change the port used for the local proxy server here:

graph-explorer/packages/graph-explorer-proxy-server/node-server.js

Lines 515 to 517 in 4d4ae7e

	app.listen(80, () => {
	proxyLogger.info(`Proxy server located at http://localhost`);
	});

Don't forget to also change the proxy server URL in the Graph Explorer connection settings to include whatever port you end up using.

Long term we will need a better solution. We are currently investigating options.

[vemonet]

Thanks @triggan and @kmcginnes for the responses! I think just adding the docker run command provided by @triggan in the readme would be already a good way for most users to get started

I authorized all unprivileged ports so now I can also run the dev deployment but it is not ideal, ideally there could be a way to easily deploy locally on port 443 and 80 (maybe some env variables?)

[kmcginnes]

I wholeheartedly agree. I have created a development project to cover these changes.

• [Project] Improve local setup documentation #403