signage-next-graphql v0.144.3

ScreenCloud Signage Next GraphQL API

ScreenCloud Signage API built on PostgreSQL and GraphQL

Requirements

• Node.js (>= 13.6)
• npm (>= 6.13)
• Docker

Setup

Clone the repo

$ git clone git@github.com:screencloud/signage-next-graphql.git

Install the npm dependencies

$ npm install

Copy the .env file across via the example and make changes accordingly

$ cp .env.development .env.development.local

You must run the API under https://signage-api.dev.next.sc locally, to do this you will need to self-sign a SSL certificate for *.dev.next.sc. See our guide on how to do this on windows or mac.

Add the server.key and server.crt for *.dev.next.sc into a /ssl folder in this repo's root folder.

Ensure you have Docker installed, then create a docker account via the app. Now login to docker via the terminal

$ docker login

Start the Docker instance

$ docker-compose up -d

The -d will run docker in detached mode (background service), omit the -d to keep docker running in the foreground (useful if you want more debugging).

Now we must migrate the database (more on migrations below)

$ npm run migrate

Now start the API

$ npm start

This will run the API through nodemon, which will watch the API and automatically restart the application when file changes in the directory are detected. Run npm start to start the API normally via node. For extra debugging you can run DEBUG="postgraphql*" npm start.

To stop the Docker instance, stop the node process (cmd/ctrl+c) and run

$ docker-compose stop

Reset

To remove the docker instance and destroy the DB (reset everything) you can run

$ docker-compose down

To keep the Docker instance running, but reset the entire database and seed you can run

$ npm run db:reset

This will drop the database, start the docker instance, migrate the database and seed it. It will then start the node service automatically.

Migrations

To migrate your database.

$ npm run migrate

To rollback the last migration.

$ npm run migrate:rollback

To rollback all migrations and reset the database.

$ npm run migrate:reset

To create a new migration file (you should have the sequelize-cli installed globally)

$ sequelize migration:create --name some-name-for-migration

When naming your migration file, please follow the format used by the existing migrations (dashes only - and no underscores _) in /migrations. E.g. create-tablename, alter-tablename-add-column etc.

Seeding

To seed the database.

$ npm run seed

To unseed the database (reset all seeders).

$ npm run seed:reset

To create a new seed file.

$ sequelize seed:create --name=tablename-seeder

Generating new types and mutations:

Make sure the docker instance is running, then...

    npm run migrate:test
    npm run start:test

Now open another terminal tab/window and run:

    npm run get-schema:test
    npm run gen:test

Testing

To run the test suite

$ npm run migrate:test
$ npm run start:test

then in a different terminal

$ npm run gen:test

$ npm run test

Commands

Below is a list of all NPM commands.

# Migrate the database (should be run whenever new migrations are added)
$ npm run migrate
# Rollback to the last migration (revert the last migration)
$ npm run migrate:rollback
# Revert all migrations (reset the DB to default empty state)
$ npm run migrate:reset
# Seed the database
$ npm run seed
# Unseed the database (reset all seeds)
$ npm run seed:reset
# Run the Postgraphile service in development with out JWT authentication
$ NODE_ENV=hack npm start
# Run the Postgraphile service in development, NODE_ENV=development
$ npm start
# Run the Postgraphile service in production, NODE_ENV=production
$ npm start
# Run SchemaSpy against the DB to visualise the DB schema, replace DB_OWNER_ID with your local db owner id
$ DB_USERNAME=DB_OWNER_ID npm run visualize
# Run all tests
$ npm run test
# Recreate all database (drop and recreate)
$ npm run db:recreate
# Reset database data, reset migration and seed then re-run migration and seed
$ npm run db:reset

Create Database Visualize Relation Report

To create the graphical report for tables and relations

$ DB_USERNAME=example_db_username npm run visualize

Content JSON Structure

https://paper.dropbox.com/doc/Refined-Content-JSON-Structure--AISHe6i~4H_xk8mFcn0M8Mg9Ag-JRnVlcHa4JpWWdaMjXbyc

Rules JSON Structure

https://paper.dropbox.com/doc/Contents-Rules-JSON-Structure--AIQEJ1_PiWAOySW35JVMCF8RAg-AiFJ3zatAmBxTLpXap7jc

GraphQL

For query and mutations examples please check inside __test__ folder.

Using the docker image

There are docker images generated for this project, which can be used CI, deploy and dev use-cases. The image is available on Docker Hub here.

The most recent tagged master commit, usually a tag done by semantic-release, is tagged as latest and therefor will be the default image to pull. Additionally all tags on master-branch are also available with matching tags, e.g. get version v1.2.3 by using image screencloud/signage-graphql:v1.2.3

The image is self-starting and requires a migrated database. Internally it runs the project with PM2.

Configuring the image

All env vars can be either set directly on container start or via a .env-file.

GraphIQL

It doesn't work and we don't intend to fix that. It's an annoying bundling issue and no one is using it anyway...

docker

If you want to run run signage-graphql with USE_SSL=true, prepare a ssl-folder with server.crt and server.key files inside.

If you want to pass in all required env vars via an .env prepare it as well. Alternatively you can inject all env vars via cli or compose files.

docker run

With neither ssl-folder or .env-file simply run with all required env vars:

• docker run -d -e "<envKey1>:<envValue1>" -e "<envKey2>:<envValue2>" -p 5000:5000 screencloud/signage-graphql

With both ssl-folder and .env-file in your CWD:

• CMD: docker run -d --env-file .env -v %CD%/ssl:/app/ssl:ro -p 5000:5000 screencloud/signage-graphql
• Bash: docker run -d --env-file .env -v ${pwd}/ssl:/app/ssl:ro -p 5000:5000 screencloud/signage-graphql
• PS: docker run -d --env-file .env -v "$($(get-location).Path)/ssl:/app/:ro" -p 5000:5000 screencloud/signage-graphql

To interact with a running container you'll need to retrieve the docker container id using docker ps first, then you can run

• docker exec <containerId> ls -la inspect the current working directory (aka. /app)
• docker exec <containerId> ./migrate to migrate the database
• docker exec <containerId> ./seed to seed the database
• docker exec <containerId> node sequelize to access sequelize
• docker exec -it <containerId> sh to start an interactive shell session

docker compose

With both ssl-folder and .env-file add to your docker-compose.yml. In this example the local .env-file is called .env.graphql as its likely near other .env-files. If you're running with USE_SSL as proxy or `false, you can skip the volume mount.

graphql:
  image: screencloud/signage-graphql:${SIGNAGE_GRAPHQL_VERSION:-latest}
  container_name: signage-graphql
  restart: always
  env_file: .env.graphql
  volumes:
    - ./ssl:/app/ssl
  ports:
    - 5000:5000

To interact with the composed container simply run:

• docker-compose exec graphql ./migrate to migrate the database
• docker-compose exec graphql ./seed to seed the database
• docker-compose exec graphql node sequelize to access sequelize-cli
• docker-compose exec graphql sh to start an interactive shell session

add a signage-graphql-database container

To add a matching database container add another service to your docker-compose.yml

db:
  image: screencloud/signage-graphql-database:${SIGNAGE_GRAPHQL_VERSION:-latest}
  container_name: signage-graphql-database
  restart: always
  environment:
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: password
    POSTGRES_DB: screencloud
  ports:
    - 35432:5432

If you prefer an empty database, with no seeds or migrations applied, instead use:

db:
  image: screencloud/postgres-signage:${POSTGRES_SIGNAGE_VERSION:-10.5}
  container_name: signage-graphql-database
  restart: always
  environment:
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: password
    POSTGRES_DB: screencloud
  ports:
    - 35432:5432