{"id":13877793,"url":"https://github.com/subzerocloud/subzero-starter-kit","last_synced_at":"2025-07-16T13:32:39.131Z","repository":{"id":27236229,"uuid":"90354872","full_name":"subzerocloud/subzero-starter-kit","owner":"subzerocloud","description":"Starter Kit and tooling for authoring GraphQL/REST API backends with subZero","archived":true,"fork":false,"pushed_at":"2023-01-24T04:59:28.000Z","size":1716,"stargazers_count":162,"open_issues_count":8,"forks_count":25,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-08-07T08:09:18.693Z","etag":null,"topics":["api","automatic-api","boilerplate","docker","graphql","openresty","postgresql","postgrest","rest","starter-kit","subzero"],"latest_commit_sha":null,"homepage":"https://subzero.cloud","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/subzerocloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-05T08:32:55.000Z","updated_at":"2023-03-20T06:35:30.000Z","dependencies_parsed_at":"2023-02-13T17:50:28.793Z","dependency_job_id":null,"html_url":"https://github.com/subzerocloud/subzero-starter-kit","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subzerocloud%2Fsubzero-starter-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subzerocloud%2Fsubzero-starter-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subzerocloud%2Fsubzero-starter-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subzerocloud%2Fsubzero-starter-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/subzerocloud","download_url":"https://codeload.github.com/subzerocloud/subzero-starter-kit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226134226,"owners_count":17578778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","automatic-api","boilerplate","docker","graphql","openresty","postgresql","postgrest","rest","starter-kit","subzero"],"created_at":"2024-08-06T08:01:24.301Z","updated_at":"2024-11-24T06:31:30.763Z","avatar_url":"https://github.com/subzerocloud.png","language":"PLpgSQL","funding_links":[],"categories":["PLpgSQL"],"sub_categories":[],"readme":"# subZero GraphQL/REST API Starter Kit\n\nBase project and tooling for authoring **data API**\nbackends with [subZero](https://subzero.cloud/).\n\n## Runs Anywhere\nRun subZero stack as a hassle-free service ([free plan](https://subzero.cloud/pricing.html) available) or deploy it yourself anywhere using binary and docker distributions.\n\n## Features\n\n✓ Out of the box GraphQL/REST/OData endpoints created by reflection over a PostgreSQL schema\u003cbr\u003e\n✓ Authentication using email/password or using 3rd party OAuth 2.0 providers (google/facebook/github preconfigured) \u003cbr\u003e\n✓ Auto-generation of SSL certificates with \"Let's Encrypt\" \u003cbr\u003e\n✓ Uses [PostgREST+](https://subzero.cloud/postgrest-plus.html) with features like aggregate functions (group by), window functions, SSL, HTTP2, custom relations\u003cbr\u003e\n✓ Cross-platform development on macOS, Windows or Linux inside [Docker](https://www.docker.com/)\u003cbr\u003e\n✓ [PostgreSQL](https://www.postgresql.org/) database schema boilerplate with authentication and authorization flow\u003cbr\u003e\n✓ Debugging and live code reloading (sql/configs/lua) functionality using [subzero-cli](https://github.com/subzerocloud/subzero-cli)\u003cbr\u003e\n✓ Full migration management (migration files are automatically created) through [subzero-cli](https://github.com/subzerocloud/subzero-cli)\u003cbr\u003e\n✓ SQL unit test using [pgTAP](http://pgtap.org/)\u003cbr\u003e\n✓ Integration tests with [SuperTest / Mocha](https://github.com/visionmedia/supertest)\u003cbr\u003e\n✓ Community support on [Slack](https://slack.subzero.cloud/)\u003cbr\u003e\n✓ Scriptable proxy level caching using nginx [proxy_cache](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache) or Redis\u003cbr\u003e\n\n## Directory Layout\n\n```bash\n.\n├── db                        # Database schema source files and tests\n│   └── src                   # Schema definition\n│       ├── api               # Api entities available as REST and GraphQL endpoints\n│       ├── data              # Definition of source tables that hold the data\n│       ├── libs              # A collection of modules used throughout the code\n│       ├── authorization     # Application level roles and their privileges\n│       ├── sample_data       # A few sample rows\n│       └── init.sql          # Schema definition entry point\n├── html                      # Place your static frontend files here\n├── tests                     # Tests for all the components\n│   ├── db                    # pgTap tests for the db\n│   ├── graphql               # GraphQL interface tests\n│   └── rest                  # REST interface tests\n├── docker-compose.yml        # Defines Docker services, networks and volumes\n└── .env                      # Project configurations\n\n```\n\n\n\n## Installation \n\n### Prerequisites\n* [Docker](https://www.docker.com)\n* [Node.js](https://nodejs.org/en/)\n* [subzero-cli](https://github.com/subzerocloud/subzero-cli#install)\n\n### Create a New Project\nClick **[Use this template]** (green) button.\nChoose the name of your new repository, description and public/private state then click **[Create repository from template]** button.\nCheck out the [step by step guide](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template) if you encounter any problems.\n\nAfter this, clone the newly created repository to your computer.\nIn the root folder of application, run the docker-compose command\n\n```bash\ndocker-compose up -d\n```\n\nThe API server will become available at the following endpoints:\n\n- Frontend [http://localhost:8080/](http://localhost:8080/)\n- REST [http://localhost:8080/rest/](http://localhost:8080/rest/)\n- GraphQL Simple Schema [http://localhost:8080/graphql/simple/](http://localhost:8080/graphql/simple/)\n- GraphQL Relay Schema [http://localhost:8080/graphql/relay/](http://localhost:8080/graphql/relay/)\n- OData v4 (experimental) [http://localhost:8080/odata/](http://localhost:8080/graphql/relay/)\n\nTry a simple request\n\n```bash\ncurl http://localhost:8080/rest/todos?select=id,todo\n```\n\nTry a GraphQL query in the integrated [GraphiQL IDE](http://localhost:8080/explore/graphql.html)\n\n```\n{\n  todos{\n    id\n    todo\n  }\n}\n```\n\n## Development workflow and debugging\n\nExecute `subzero dashboard` in the root of your project.\u003cbr /\u003e\nAfter this step you can view the logs of all the stack components (SQL queries will also be logged) and\nif you edit a sql/conf file in your project, the changes will immediately be applied.\n\n\n## Unit and integration tests\n\nThe starter kit comes with a testing infrastructure setup.\nYou 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).\nIntegration tests are written in JavaScript.\n\nHere is how you run them locally\n\n```bash\nyarn install         # Install test dependencies\nyarn test            # Run all tests (db, rest, graphql)\nyarn test_db         # Run pgTAP tests\nyarn test_rest       # Run rest integration tests\nyarn test_graphql    # Run graphql integration tests\n```\n\nAll the test are also executed on on git push (on GitHub) \n\n## Deployment\nThe deployment is done using a [GitHub Actions script](.github/workflows/test_deploy.yaml).\nThe deploy action will push your migrations to the production database using sqitch and the static files with scp.\nThe deploy step is triggered only on git tags in the form of `v1.2`\n\nNote 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 \u003cmigration_name\u003e`\n\nYou'll also need to configure the following \"secrets\" for your github deploy action\n```\nSUBZERO_EMAIL\nSUBZERO_PASSWORD\nAPP_DOMAIN\nAPP_DB_HOST\nAPP_DB_PORT\nAPP_DB_NAME\nAPP_DB_MASTER_USER\nAPP_DB_MASTER_PASSWORD\nAPP_DB_AUTHENTICATOR_USER\nAPP_DB_AUTHENTICATOR_PASSWORD\nAPP_JWT_SECRET\n```\n\nWhile 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.\n\nIf you with to deploy to AWS Fargate, you'll need to additionally configure the secrets starting with `AWS_*`.\n\nIf you have a preexisting database, you can also deploy the container to AWS Fargate by clicking the button below. \nThe 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.\n\n\u003ca href=\"https://console.aws.amazon.com/cloudformation/home?#/stacks/quickcreate?stackName=subzero-container\u0026templateURL=https://public-aws-templates.s3.amazonaws.com/fargate_single_container.yml\u0026\u0026param_DbPort=5432\u0026param_DbName=app\u0026param_DbAuthenticatorUser=authenticator\u0026param_DbSchema=api\u0026param_DbAnonRole=anonymous\" target=\"_blank\"\u003e\u003cimg src=\"https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png\"\u003e\u003c/a\u003e\n\n## Contributing\n\nAnyone and everyone is welcome to contribute.\n\n## Support and Documentation\n* [subZero Documentation](https://docs.subzero.cloud)\n* [PostgREST API Referance](https://postgrest.com/en/stable/api.html)\n* [PostgreSQL Manual](https://www.postgresql.org/docs/current/static/index.html)\n* [Slack](https://slack.subzero.cloud/) — Watch announcements, share ideas and feedback\n* [GitHub Issues](https://github.com/subzerocloud/subzero-starter-kit/issues) — Check open issues, send feature requests\n\n## License\n\nCopyright © 2017-2021 subZero Cloud, LLC.\u003cbr /\u003e\nThis source code in this repository is licensed under [MIT](https://github.com/subzerocloud/subzero-starter-kit/blob/master/LICENSE.txt) license\u003cbr /\u003e\nComponents implementing the GraphQL interface (customized PostgREST+ and OpenResty docker images) are available under a [commercial license](https://subzero.cloud)\u003cbr /\u003e\nThe documentation to the project is licensed under the [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/) license.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubzerocloud%2Fsubzero-starter-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsubzerocloud%2Fsubzero-starter-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubzerocloud%2Fsubzero-starter-kit/lists"}