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.
- Application Configuration
- Quick Start
- Schema Migrations
- API Documentation
- Setup & Feature Video Walkthrough
- Versioning
- License
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.
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.
The remaining files are all optional. Detailed descriptions of what each is for is documented on the README of the root project.
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:latestThe services should now be running:
Notes:
-
Docker run
--networkflag is only needed if you want ton connect to DB service via Docker Network. -
DB_HOSTshould 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.
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:1The services should now be running:
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.
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# 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 worldThe 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.
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-uiThe services should now be running:
OpenAPI Web UI
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.
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.mdNotes:
- You will need node installed locally to use
npx - shins has been replaced by reslate. Support for building out static HTML with
reslatewill be added in the future (likely via Docker container).
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:
- GIS DB Setup & Load
- Quick Start
- Insomnia Import
- Key REST Endpoints
- Permissions
- API Response Metadata
- Query Context
- SQL Operators
- CRUD Operations
- Debug Mode
- Complex Resources (subqueries & aggregate queries)
- Middleware & Redactions
- GraphQL Playground and Geoqueries
- gRPC Service (CRUD & Geoqueries)
- DB Schema Migrations
SemVer is used for versioning. For the versions available, see the tags on this repository.
This project is licensed under the MIT License - see the LICENSE.md file for details