Skip to content

Latest commit

 

History

History
165 lines (124 loc) · 8.01 KB

README.md

File metadata and controls

165 lines (124 loc) · 8.01 KB
Raw

subZero GraphQL/REST API Starter Kit

Base project and tooling for authoring data API backends with subZero.

Runs Anywhere

Run subZero stack as a hassle-free service (free plan available) or deploy it yourself anywhere using binary and docker distributions.

Features

✓ Out of the box GraphQL/REST/OData endpoints created by reflection over a PostgreSQL schema
✓ Authentication using email/password or using 3rd party OAuth 2.0 providers (google/facebook/github preconfigured)
✓ Auto-generation of SSL certificates with "Let's Encrypt"
✓ Uses PostgREST+ with features like aggregate functions (group by), window functions, SSL, HTTP2, custom relations
✓ Cross-platform development on macOS, Windows or Linux inside Docker
✓ PostgreSQL database schema boilerplate with authentication and authorization flow
✓ Debugging and live code reloading (sql/configs/lua) functionality using subzero-cli
✓ Full migration management (migration files are automatically created) through subzero-cli
✓ SQL unit test using pgTAP
✓ Integration tests with SuperTest / Mocha
✓ Community support on Slack
✓ Scriptable proxy level caching using nginx proxy_cache or Redis

Directory Layout

.
├── db                        # Database schema source files and tests
│   └── src                   # Schema definition
│       ├── api               # Api entities available as REST and GraphQL endpoints
│       ├── data              # Definition of source tables that hold the data
│       ├── libs              # A collection of modules used throughout the code
│       ├── authorization     # Application level roles and their privileges
│       ├── sample_data       # A few sample rows
│       └── init.sql          # Schema definition entry point
├── html                      # Place your static frontend files here
├── tests                     # Tests for all the components
│   ├── db                    # pgTap tests for the db
│   ├── graphql               # GraphQL interface tests
│   └── rest                  # REST interface tests
├── docker-compose.yml        # Defines Docker services, networks and volumes
└── .env                      # Project configurations

Installation

Prerequisites

Create a New Project

Click [Use this template] (green) button. Choose the name of your new repository, description and public/private state then click [Create repository from template] button. Check out the step by step guide if you encounter any problems.

After this, clone the newly created repository to your computer. In the root folder of application, run the docker-compose command

docker-compose up -d

The API server will become available at the following endpoints:

Try a simple request

curl http://localhost:8080/rest/todos?select=id,todo

Try a GraphQL query in the integrated GraphiQL IDE

{
  todos{
    id
    todo
  }
}

Development workflow and debugging

Execute subzero dashboard in the root of your project.
After this step you can view the logs of all the stack components (SQL queries will also be logged) and if you edit a sql/conf file in your project, the changes will immediately be applied.

Unit and integration tests

The starter kit comes with a testing infrastructure setup. You can write pgTAP tests that run directly in your database, useful for testing the logic that resides in your database (user privileges, Row Level Security, stored procedures). Integration tests are written in JavaScript.

Here is how you run them locally

yarn install         # Install test dependencies
yarn test            # Run all tests (db, rest, graphql)
yarn test_db         # Run pgTAP tests
yarn test_rest       # Run rest integration tests
yarn test_graphql    # Run graphql integration tests

All the test are also executed on on git push (on GitHub)

Deployment

The deployment is done using a GitHub Actions script. The deploy action will push your migrations to the production database using sqitch and the static files with scp. The deploy step is triggered only on git tags in the form of v1.2

Note that the deploy action pushes to production the database migrations (db/migrations/) not the current database schema definition (db/src/) so you'll need execute subzero migrations init --with-roles before the first deploy and when iterating, you'll create new migrations using subzero migration add <migration_name>

You'll also need to configure the following "secrets" for your github deploy action

SUBZERO_EMAIL
SUBZERO_PASSWORD
APP_DOMAIN
APP_DB_HOST
APP_DB_PORT
APP_DB_NAME
APP_DB_MASTER_USER
APP_DB_MASTER_PASSWORD
APP_DB_AUTHENTICATOR_USER
APP_DB_AUTHENTICATOR_PASSWORD
APP_JWT_SECRET

While the deploy action is written for subzero.cloud and fargate (DEPLOY_TARGET: subzerocloud) it can easily be adapted for other deploy targets that run the subzero stack.

If you with to deploy to AWS Fargate, you'll need to additionally configure the secrets starting with AWS_*.

If you have a preexisting database, you can also deploy the container to AWS Fargate by clicking the button below. The cloudformation stack will launch the container in Fargate and create a DNS record for it in a Route53 zone. You'll only need to update the domain registration to use Amazon Route 53 name servers from the domain's zone.

Contributing

Anyone and everyone is welcome to contribute.

Support and Documentation

License

Copyright © 2017-2021 subZero Cloud, LLC.
This source code in this repository is licensed under MIT license
Components implementing the GraphQL interface (customized PostgREST+ and OpenResty docker images) are available under a commercial license
The documentation to the project is licensed under the CC BY-SA 4.0 license.