Skip to content

Template: REST, GraphQL & gRPC services for CRUD to Popular Databases. Supports Schema Migrations and built using service-engine Docker Image.

License

Notifications You must be signed in to change notification settings

deploymat/service-engine-template

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

19 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

General Service Engine Template

This project is a containerized implementation of service-engine. The goal is to provide a minimalist template that can be used to quickly bootstap services.

This project currently supports PostgreSQL, MySQL, MSSQL (SQL-Server), Sqlite3, Oracle & Redshift. Support for all other database dialects supported by knex.js is planned.

service-envine promo-art

Table of Contents

Application Configuration

Required

.env

Mostly consists of DB Connection information, but also includes options for pagination limits, ports for REST & gRPC services & a flag indicated if you want to enable db migrations on startup.

metadata.json

Most of this content is used to complete the OpenAPI docs. However, the appShortName is also used to define root URL path & is injected into all logs.

Optional

The remaining files are all optional. Detailed descriptions of what each is for is documented on the README of the root project.

Quick Start

Basic Features

Once database configurations are set in a .env file, you can run the application via a Docker container. The resources provisioned for REST, GraphQL & gRPC are fully derived from the database.

# create docker network (if db on docker network)
docker network create mynetwork

# run via docker container
docker run --rm -d \
	--network mynetwork \
	--env-file ./.env \
	-p 8080:8080 \
	-p 50051:50051 \
	--name myservice \
	sudowing/service-engine:latest

The services should now be running:

Notes:

  • Docker run --network flag is only needed if you want ton connect to DB service via Docker Network.

  • DB_HOST should be ip, domain or docker container name. If container name ensure db and this service on same network.

  • GraphQL Playground UI is only functional if ENV VAR NODE_ENV = development.

Custom Functionality & Schema Migration Support

Additional functionality can be configured by mounting any of the files below into the container. Each file can be enabled individually.

# create docker network (if db on docker network)
docker network create mynetwork

# run via docker container
docker run --rm -d \
	--network mynetwork \
	--env-file ./.env \
	-v $(pwd)/src/metadata.json:/app/lib/metadata.json \
	-v $(pwd)/src/permissions.js:/app/lib/permissions.js \
	-v $(pwd)/src/middleware.js:/app/lib/middleware.js \
	-v $(pwd)/src/redactions.js:/app/lib/redactions.js \
	-v $(pwd)/src/complex_resources.js:/app/lib/complex_resources.js \
	-v $(pwd)/migrations:/app/migrations \
	-p 8080:8080 \
	-p 50051:50051 \
	--name myservice \
	sudowing/service-engine:1

The services should now be running:

Schema Migrations

Knex is used for database schema migrations.

All functionality provided by knex is supported -- along with some project specific features which support more modular schema migrations via batches of SQL files held within specific directories.

Basic Schema Migrations via knex.js

Documentation from NPM Package

# knex schema migration support via redefining Docker CMDs
docker run --rm \
	--env-file ./.env \
	-v $(pwd)/migrations:/app/migrations \
	sudowing/service-engine:1 \
	npm run migrate:make some_script_name

# ANY/ALL OF THE BELOW LINES ARE SUPPORTED
docker run ...options sudowing/service-engine:1 \
	# create new knex migration script
	npm run migrate:make some_script_name
	# run all pending migration scripts
	npm run migrate:latest
	# rollback all migration scripts committing in last batch
	npm run migrate:rollback
	# rollback all migration scripts
	npm run migrate:rollback-all
	# run next pending migration script
	npm run migrate:up
	# uncommit last committed migration script
	npm run migrate:down
	# list all migration script along with commitment status
	npm run migrate:list

Modular Schema Migration Scripts

# create modular knex schema migration script
docker run --rm \
	--env-file ./.env \
	-v $(pwd)/migrations:/app/migrations \
	sudowing/service-engine:1 \
	npm run migrate:new hello world

API Documentation

The service has a two sets of resources -- some static development resources and others that are generated dynamically that are specific to the database.

I use the Insomnia API Client for develoment, and I've included an insomnia workplace export of some general service calls to speed your adoption.

OpenAPI UI

The OpenAPI UI is available via Docker Container and the command below will run that container and populate it with the OpenAPI definition generated from this server.

docker run -p 8088:8080 -e API_URL='http://localhost:8080/openapi' swaggerapi/swagger-ui

The services should now be running:
OpenAPI Web UI

OpenAPI Import

Insomnia has a feature that supports importing OpenAPI definitions and because the REST service auto-generates OpenAPI3 definitions. This means you can actually use the service to build calls in the insomnia workplace.

This is really helpful for documenting the REST calls, but you will have to build GraphQL calls out manually.

Static HTML Documentation

You can also generate some awesome static HTML documentation using Mermade/shins. Tip: I always use the --inline flag when generating the shin docs.

Mermade/shins does not take the OpenAPI docs as input directly -- but rather a markdown format. You can generate this intermediate format using a related Mermade project widdershins

# use local node winddershins to generate intermediate md
npx widdershins \
 --search true \
 --language_tabs 'javascript:JavaScript' 'javascript--nodejs:Node.JS' 'python:Python' 'go:Go' 'http:HTTP' 'ruby:Ruby' \
 --summary http://localhost:8080/openapi \
 -o docs/service.md

Notes:

  • You will need node installed locally to use npx
  • shins has been replaced by reslate. Support for building out static HTML with reslate will be added in the future (likely via Docker container).

Setup & Feature Video Walkthrough

A series of videos, showing how to configure the application and how several features work, have been published as a playlist on YouTube.

Videos have been produced covering the following topics related to setup & Features:

Versioning

SemVer is used for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

About

Template: REST, GraphQL & gRPC services for CRUD to Popular Databases. Supports Schema Migrations and built using service-engine Docker Image.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 100.0%