Legumeinfo GraphQL Server

This repository contains a GraphQL server made with the Apollo Server that consumes data from one or more InterMine servers.

Quick Start

Start a non-production instance of the GraphQL Server using Docker Compose as follows:

docker compose -f compose.yml -f compose.dev.yml up -d

The server can be queried at localhost:4000.

Running

The GraphQL Server can be run via Docker (Compose) or directly in your local environment. The PORT environment variable can be used to change what port the server uses when running locally or with Docker Compose. When using Docker, the port should be changed manually via the port mapping flag when running the container. The port is 4000 by default.

When the server is running in developer mode, you can query it interactively using the Apollo Explorer. You can use the Apollo Explorer by navigating your browser to http://localhost:4000 (the port should be the same as the PORT environment variable).

Docker

A Docker image can be built that contains the environment necessary to build and run the server. The entrypoint for this image is the bun run command. The default command for this entrypoint is the start script defined in package.json, which simply compiles and runs the code in neither development or production mode. The default command should not be used for production. Override the command to compile and run the code in a specific environment or to run another command from package.json; see the Local instructions below for details on commands for development and production.

In general, we recommend using Docker Compose instead of Docker because it provides the configurations necessary to run the server in development or production mode. See Docker Compose below for details.

Setup

Use the following command to build the Docker image:

docker build . -t legumeinfo-graphql-server

Running

Once the Docker image is built, use the following command to start a container:

docker run -p 4000:4000 legumeinfo-graphql-server

Docker Compose

Three Docker Compose files are provided for running the GraphQL Server: compose.yml, compose.dev.yml, and compose.prod.yml. Running each file will automatically build the Docker image and configure it for a particular environment.

compose.yml

This file contains a base configuration that the compose.dev.yml and compose.prod.yml` files extend. Running it alone will compile and run the code in neither development or production mode, as previously described:

docker compose -f compose.yml up -d

compose.dev.yml

This file runs the Docker image in development mode, which will automatically rebuild the code and restart the server whenever a change is made. Note that container health checks are disabled since the server is expected to break during development. Additionally, the code directories on the host machine are mounted as volumes in the container so that the code can be edited on the host.

docker compose -f compose.yml -f compose.dev.yml up

This command does not run the container as a daemon so that compiler errors and debug messages will be printed in the host console in real time.

compose.prod.yml

This is the file to use when running the server in production. This file runs the Docker image in production mode, which disables GraphQL introspection and limits logging to errors only.

docker compose -f compose.yml -f compose.prod.yml up -d

Local

The following instructions describe how to setup your local environment for running the server in both development and production mode. See the package.json file for other commands. NOTE: This project uses Bun, NOT npm.

Setup

The server's dependencies can be installed as follows:

bun install

Development mode

Once the dependencies are installed, use the following command to start the server in development mode:

bun run serve:dev

This will automatically rebuild the code and restart the server whenever a change is made.

Production mode

To run the server in production mode, you must first build the code:

bun run build

Once the code is built, the server can be run in production mode as follows:

bun run serve:prod

As with development mode, this will start the server on port 4000 (or whatever the PORT environment variable is set to). However, for security purposes introspection will be disabled, meaning the Apollo Explorer will not be available.

.env file

This project support the use of a .env file. This file is used to set environment variables that control the server AND Docker Compose. For instance, when running the server directly with bun in your local environment the server will load environment variables from the .env file, such as the PORT variable. However, the .env file is not included in the Docker image when it's built and it is explicitly excluded from the mounted volumes in the compose.dev.yml file. This is to ensure that the environment inside the Docker image is always the same and that environment variables inside a container are set in a canonical way, i.e. via Docker (Compose). Continuing the PORT example, this means when using Docker Compose the server inside the container will run on the default port - 4000 - but the compose.yml file will use the PORT environment variable to determine which port on the host to map the container's port to. In other words, using the .env file to set environment variables will have the same effect, but how the effect is achieved depends on whether the server is being run locally or with Docker Compose.

The following environment variables are supported by the server:

• PORT - What port the server listens on (4000 by default).
• INTERMINE_URI - The Intermine data source ('https://mines.legumeinfo.org/minimine/service' by default).
• MICROSERVICES_URI - The microservices data source ('https://services.lis.ncgr.org' by default).