{"id":20496432,"url":"https://github.com/jkheadley/appy-backend","last_synced_at":"2025-04-13T18:21:38.281Z","repository":{"id":44525865,"uuid":"79547497","full_name":"JKHeadley/appy-backend","owner":"JKHeadley","description":"A user system to bootstrap your app.","archived":false,"fork":false,"pushed_at":"2023-01-04T06:20:09.000Z","size":130054,"stargazers_count":108,"open_issues_count":21,"forks_count":30,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-27T09:05:21.123Z","etag":null,"topics":["api","api-server","authentication","authorization","hapi","hapi-api","login","mongodb","mongoose","permissions","registration","rest","rest-hapi","restful-api","server","swagger","user-management","user-roles","user-system","users"],"latest_commit_sha":null,"homepage":"https://appyapp.io","language":"JavaScript","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/JKHeadley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-01-20T09:56:14.000Z","updated_at":"2023-11-03T17:12:43.000Z","dependencies_parsed_at":"2023-02-02T01:02:04.897Z","dependency_job_id":null,"html_url":"https://github.com/JKHeadley/appy-backend","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JKHeadley%2Fappy-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JKHeadley%2Fappy-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JKHeadley%2Fappy-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JKHeadley%2Fappy-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JKHeadley","download_url":"https://codeload.github.com/JKHeadley/appy-backend/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248759088,"owners_count":21157088,"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","api-server","authentication","authorization","hapi","hapi-api","login","mongodb","mongoose","permissions","registration","rest","rest-hapi","restful-api","server","swagger","user-management","user-roles","user-system","users"],"created_at":"2024-11-15T18:07:08.368Z","updated_at":"2025-04-13T18:21:38.252Z","avatar_url":"https://github.com/JKHeadley.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003ca href=\"https://appyapp.io\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\u003cimg width=\"262\" height=\"295\" src=\"https://user-images.githubusercontent.com/12631935/39099920-eaab3d3e-4636-11e8-9955-b53be05e1c13.png\" alt=\"appy logo\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n\nA user system leveraging [rest-hapi](https://github.com/JKHeadley/rest-hapi) to bootstrap your app.\n\nappy-backend is the server portion of the [appy](https://appyapp.io) project. It provides a boilerplate user system that leverages the powerful [rest-hapi](https://github.com/JKHeadley/rest-hapi) API generator.  Inspired by the [frame](https://github.com/jedireza/frame) user system, the goal of appy-backend is to provide an easy to use user API that is also capable of supporting a wide range of applications.  appy-backend is a great resource for starting almost any app. By leveraging [rest-hapi](https://github.com/JKHeadley/rest-hapi), adding new endpoints is as simple as defining a new model, and model associations are a snap.  Bootstrapping your app has never been easier!\n\n## Features\n \n* Registration and account activation flows\n* Login system with forgot password and reset password\n* Social login\n* Abusive login attempt detection\n* User permissions based on roles and groups\n* Three optional authentication strategies\n* Websocket chat via [@hapi/nes](https://github.com/hapijs/nes)\n* File upload api\n* Endpoint validation and query support\n* Swagger docs for easy endpoint access\n\n## Technologies\n\nappy-backend implements a [hapi](https://github.com/hapijs/hapi) framework server.  appy-backend's RESTful API endpoints are generated through [rest-hapi](https://github.com/JKHeadley/rest-hapi), which means models are based off of [mongoose](https://github.com/Automattic/mongoose) and data is stored in [MongoDB](www.mongodb.org).\n\n## Demos\n\nView the swagger docs for the **live demo**:\n\nhttps://api.appyapp.io\n\n### Starting appy-backend\n\n\u003cp align=\"center\"\u003e\u003ca\u003e\u003cimg width=\"1024\" height=\"480\" src=\"https://user-images.githubusercontent.com/12631935/79036262-7f96bb00-7b7b-11ea-9fb0-bed77cc9d043.gif\" alt=\"appy_start\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n### Logging in\n\n\u003cp align=\"center\"\u003e\u003ca\u003e\u003cimg width=\"1024\" height=\"640\" src=\"https://user-images.githubusercontent.com/12631935/79036503-a5bd5a80-7b7d-11ea-9964-737706a81467.gif\" alt=\"appy_login\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n### GET /users\n\n\u003cp align=\"center\"\u003e\u003ca\u003e\u003cimg width=\"1024\" height=\"640\" src=\"https://user-images.githubusercontent.com/12631935/79036809-a0154400-7b80-11ea-9824-4670ad349b64.gif\" alt=\"appy_get_users\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n### Filter Query and Populate Relationship\n\n\u003cp align=\"center\"\u003e\u003ca\u003e\u003cimg width=\"1024\" height=\"640\" src=\"https://user-images.githubusercontent.com/12631935/79037098-161aaa80-7b83-11ea-8fd5-5046e2d5fff7.gif\" alt=\"appy_permissions_filter\"\u003e\u003c/a\u003e\u003c/p\u003e\n\n## Readme contents\n- [Requirements](#requirements)\n- [Getting Started](#getting-started)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [First time setup](#first-time-setup)\n- [Running appy](#running-appy)\n- [Wiki](#wiki)\n- [Swagger documentation](#swagger-documentation)\n- [Authentication](#authentication)\n- [Authorization](#authorization)\n- [License](#license)\n- [Questions](#questions)\n- [Contributing](#contributing)\n- [Thanks!](#thanks)\n\n\n## Requirements\n\nJust [Docker](https://docs.docker.com/install)\n\n**OR**\n\nYou need [Node.js](https://nodejs.org/en/) installed (\u003e=12.14.1) and you'll need [MongoDB](https://docs.mongodb.com/manual/installation/) installed and running.\n\n[Back to top](#readme-contents)\n\n## Getting Started\n\nDownload from GitHub:\n\n```bash\n$ git clone https://github.com/JKHeadley/appy-backend.git\n$ cd appy-backend\n```\n\n## Installation\n\n### Using Docker\n\nNone required.\n\n### Without Docker\n\n```bash\n$ npm install\n```\n\n[Back to top](#readme-contents)\n\n## Configuration\nappy configuration follows [frame's](https://github.com/jedireza/frame) configuration flow:\n\n\u003e Simply edit ``config/index.js``. The configuration uses confidence which makes it easy to manage configuration settings across environments. Don't store secrets in this file or commit them to your repository.\n\n\u003e Instead, access secrets via environment variables. We use dotenv to help make setting local environment variables easy (not to be used in production).\n\n### Using Docker\n\u003e Simply copy .env-docker-sample to .env-docker and edit as needed. Don't commit .env-docker to your repository.\n\n### Without Docker\n\u003e Simply copy .env-sample to .env and edit as needed. Don't commit .env to your repository.\n\n## First time setup\n**WARNING**: This will clear all data in the MongoDB database defined in ``restHapiConfig.mongo.URI`` (default ``mongodb://localhost/appy``).\n\nIf you would like to seed your database with some data, run:\n\n### Using Docker\n\n```\n$ sh seed_data.sh\n```\n\n### Without Docker\n\n```\n$ npm run seed\n```\n\nNOTE: The password for all seed users is ``root``.\n\n[Back to top](#readme-contents)\n\n## Running appy-backend\n\nTo quickly run the app locally, simply run:\n\n## Using Docker\n\n```\n$ sh run_server.sh\n```\n\n## Without Docker\n\n```\n$ npm start\n```\n\nOnce the app is running point your browser to http://localhost:8080/ to view the Swagger docs.\n\n[Back to top](#readme-contents)\n\n## Wiki\n\nFor detailed explanations on many of the topics covered in this readme, including authentication, authorization, and logging in and testing endpoints, please refer to the [wiki pages](https://github.com/JKHeadley/appy-backend/wiki).\n\n\n[Back to top](#readme-contents)\n\n## Swagger documentation\n\nSwagger documentation is automatically generated for all endpoints and can be viewed by pointing a browser at the server URL. By default this will be http://localhost:8080/. The swagger docs provide quick access to testing your endpoints along with model schema descriptions and query options.\n\n[Back to top](#readme-contents)\n\n## Authentication\n\nThere are three optional authentication strategies in appy and each make use of javascript web tokens (JWT) and the [hapi-auth-jwt2](https://www.npmjs.com/package/hapi-auth-jwt2) scheme.  The three strategies are:\n\n1. Standard token\n2. Session\n3. Session with refresh token\n\nThe strategy used is determined by the ``restHapiConfig.authStrategy`` config property.\n\nFor a more in-depth description of these strategies, please view the [wiki](https://github.com/JKHeadley/appy-backend/wiki/Authentication).\n\n[Back to top](#readme-contents)\n\n## Authorization\n\nAuthorization in appy is enforced via the hapi ``scope`` endpoint property.  Endpoints generated through [rest-hapi](https://github.com/JKHeadley/rest-hapi) come prepopulated with scope values. See the [rest-hapi docs](https://resthapi.com/docs/authorization.html) for more info.\n\nUser scope values are populated based on appy's permission system.  User's gain permissions based on three associations:\n\n1. User defined permissions\n2. Group defined permissions\n3. Role defined permissions\n\nUsers must belong to at least one role and can belong to multiple groups.  Each permission association carries with it a ``state`` property that can be set to `Included`, `Excluded`, or `Forbidden`.  This property allows permissions to override each other based on priority.  User permissions have the highest priority, followed by Group permissions and lastly Role permissions:\n```\nUser-\u003eGroup-\u003eRole\n```\nThis allows easy and specific configuration of user endpoint access.  In general, a user will gain the majority of it's permissions through it's role.  Those permissions will be further defined by any groups the user belongs to.  Finally a user might have a few specific permissions assigned directly to them.  A user's scope final scope is a combination of the user's role, groups, and effective permissions.  See below for an example:\n\nUser: ``'test@manager.com'``\nRole: ``'Admin'``\nRole Permissions: \n\n```javascript\n[\n  { name:'readUser', state:'Included' },\n  { name:'updateUser', state:'Included' },\n  { name:'addUserPermissions', state:'Included' },\n  { name:'removeUserPermissions', state:'Included' }\n]\n```\n\nUser's Groups: ``['Managers']``\nGroup Permissions: \n\n```javascript\n[\n  { name:'updateUser', state:'Excluded' },\n]\n```\n\nUser Permissions: \n\n```javascript\n[\n  { name:'removeUserPermissions', state:'Excluded' },\n]\n```\n\nFinal User Scope:\n\n```javascript\n['Admin','Managers','readUser','addUserPermissions']\n``` \n\nFor a more in-depth description of authorization within appy, please view the [wiki](https://github.com/JKHeadley/appy-backend/wiki/Authorization)\n\n[Back to top](#readme-contents)\n\n## License\nMIT\n\n[Back to top](#readme-contents)\n\n## Questions?\nIf you have any questions/issues/feature requests, please feel free to open an [issue](https://github.com/JKHeadley/appy-backend/issues/new). We'd love to hear from you!\n\n[Back to top](#readme-contents)\n\n## Contributing\nPlease reference the contributing doc: https://github.com/JKHeadley/appy-backend/blob/master/CONTRIBUTING.md\n\n[Back to top](#readme-contents)\n\n## Thanks!\nWe hope you enjoy appy-backend!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkheadley%2Fappy-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjkheadley%2Fappy-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkheadley%2Fappy-backend/lists"}