graphql-playground-server
v0.1.6
Published
Standalone GraphQL Playground server
Downloads
23
Readme
graphql-playground-server
A simple HTTP server that serves a web-based GraphQL Playground.
Rationale
GraphQL Playground is nice, but it would be even nicer if you could easily host it in a stanadlone web server. This would keep it completely separate from your API processes and repositories, simplifying your dependency trees and just generally making more sense than embedding it inside your apps with middleware which you turn off in production.
There does not seem to be a package on npm for doing this yet, however, even though it would be dead simple to make. So, we're making it here. :)
Installation
As a Local Service
Ideally you want to install as a service, so that the server is always running when your machine is on.
MacOS (with Homebrew)
brew tap batterii/graphql-playground-server
brew install graphql-playground-server
brew services start graphql-playground-server
Updates
This project will likely not be updated much, but if we do put out a new version and you want to upgrade, you can use the usual Homebrew commands to do so:
brew update
brew upgrade graphql-playground-server
brew services restart graphql-playground-server
Debian
I am not a Debian expert by any means and I don't have a ton of time to become one, so as far as releasing this as an easily-installed package goes, this is kind of the best I can do for now. If there are any Debian packaging gurus out there who might like to lend a hand, feel free.
Starting with v0.1.6, you can find a deb
package under Assets for each release
in the Releases tab. Find the latest one and download it to your machine, along
with the associated pubkey.gpg
.
Signing of individual packages is kind of a mess in Debian, it seems, but we're
doing it anyway for those responsible folks who want peace of mind before using
sudo
to install this thing. Packages are signed with dpkg-sig. If you
don't have it already, install it from the official Debian repository like so:
sudo apt install dpkg-sig
Next, you should add the public key to your gnupg public keychain:
gpg --import ~/Downloads/pubkey.gpg
We won't be changing this public key for most releases, so if you've already
added this key your keychan, the gpg
tool will let you know. Once you have it
in place, you can check the package's signature like so:
dpkg-sig --verify ~/Downloads/graphql-playground-server_0.1.6_all.deb
This command will print, among other things, GOODSIG _gpgoriginl
into your
console if the signature checks out. If it does not check out you will see
BADSIG _gpgoriginl
or NOSIG
instead, depending on whether the signature is
bad or simply not present due to tampering.
Again, I'm sure there is a much better way of doing this stuff, but it seems to be some kind of arcane art and I'm not in a position to learn it right now.
Once you've verified the signature, you can safely install like so:
sudo apt install ~/Downloads/graphql-playground-server_0.1.6_all.deb
You'll of course want to change the version number in that filename to match the one you are installing.
The service should start automatically once installed, but if you want to
control it, use your system's service manager which-- if you aren't using an
old or heavily customized Debian version-- is likely systemd
:
# Check status
systemctl status graphql-playground-server
# Start
sudo systemctl start graphql-playground-server
# Stop
sudo systemctl stop graphql-playground-server
# Restart
sudo systemctl restart graphql-playground-server
Updates
This project will likely not be updated much, so I'm not
bothering with trying to get together a repository for publishing .changes
and
stuff like that. If you need to install a new version, just remove the one you
have:
sudo apt remove graphql-playground-server
Then install the new one, downloaded and verified the same way as above.
NPM Global Install
If for whatever reason you can't or would rather not install as a service, you can install globally with npm:
npm i -g graphql-playground-server
Once installed you can run the server in a console like so:
graphql-playground-server
Using the Playground
By default, you can access the playground while it is running at
http://localhost:3001. It will send its GraphQL
requests to https://localhost:3000/graphql
, though you can change this address
using the address bar in the playground itself.
The server's port number and default GraphQL endpoint can be configured as described below.
Configuration
Config Files
Configuration files for this server are simple yaml and only support two
properties: port
and endpoint
.
graphql-playground-server.conf.yaml
port: 3002 # Changes the server's port number.
endpoint: https://your.host/graphql # Changes the url for graphql requests.
You can reference a config file when running the server like so:
graphql-playground-server --config graphql-playground-server.conf.yaml
MacOS Service
The service installed by the Homebrew formula looks for a configuration file at
HOMEBREW_PREFIX/etc/graphql-playground-server.conf.yaml
. HOMEBREW_PREFIX
is
typically /usr/local
, but this may vary if you installed Homebrew differently
than usual.
To configure the service, simply create this file and populate it with your yaml configuration as above. Once your configuration is in place, you just need to restart the service to use it:
brew services restart graphql-playground-server
Debian Service
The service installed by the deb
package looks for a configration file at
/etc/graphql-playground-server/graphql-playground-server.conf.yaml
. This file
will not exist by default, though its parent directory will.
To configure the service, simply create this file and populate it with your yaml configuration as above. Once your configuration is in place, you just need to restart the service to use it:
sudo systemctl restart graphql-playground-server
Other Configuration Methods
In addition to using a config file, you can provide command-line arguments:
graphql-playground-server --port 3002 --endpoint https://your.host/graphql
You can also provide environment variables:
GRAPHQL_PLAYGROUND_PORT=3002 GRAPHQL_PLAYGROUND_ENDPOINT=https://your.host/graphql graphql-playground-server
If you provide the same configuration option in multiple ways, they will be prioritized like so:
- CLI args
- config file values
- environment variables
For Developers
The Homebrew tap for this project is completely managed inside its own git repo and was creating according to the guidelines described here.
As for the Debian package, it is built using node-deb. I had attempted to
keep any packaging stuff out of this repository, but node-deb
is rather
finicky in how it is configured so I kind of just gave up and put it in this
repo directly.
To build a package file, just run this:
npm run deb
The created package can then be signed with a secret GPG in your keyring like
so-- assuming you have dpkg-sig
installed:
dpkg-sig -k <your_key_id> --sign origin <new_package_path>
This will alter the package file, adding the signature in place. You should then use GitHub's UI to add the signed package and the public key to your release.
Of course, to produce a signature that can be checked against the public key we're already using, you would need the associated private key, which I do not plan on sharing, at least not until I know more about how this crap works. So if you really need to do a new release yourself, make your own new key pair like so:
gpg --gen-key
And export the public key to a file like so:
gpg --output pubkey.gpg --armor export <your_email_address>
Now you can sign the package as above, then add the signed package and your exported public key to your Release using GitHub's UI. If you do this, though, make sure to make a note of the public key change in the release notes, just to warn anybody who might updates and tries verifying the signature with the same key as before.
I'd like to have a better system for key management in place to make it easier for more people to work on this... but also I doubt anybody in our company is ever going to change this library but me, so I'm not worried about it for now. :)