gottfired / aaa-backend-demo

aaa-backend-demo README

This is a demo backend serving the API for https://github.com/majodev/aaa-frontend-demo and https://github.com/gottfired/aaa-frontent-demo-angular

Prerequisites: Needed software for workshop

• Javascript runtime: nodejs (https://nodejs.org/). Version installed for this project (12 LTS)
  • If you already have nodejs installed on your machine and want to switch between versions for this workshop, install nvm (https://github.com/nvm-sh/nvm). On Windows machines use nvm-windows (https://github.com/coreybutler/nvm-windows)
• Editor: Visual Studio Code (https://code.visualstudio.com/). Microsoft's typescript IDE (Electron App written in TS)
• Version control: git with Sourcetree (https://www.sourcetreeapp.com/). On Linux you can use GitKraken (https://www.gitkraken.com/)
• Vagrant (2.2.3)
• VirtualBox (5.2.3)
• Ansible (2.8.0 using Python 2.7.10)

Original README below ...

This project was scaffolded through create-aaa-backend.

This project is managed with yarn not npm, therefore always use yarn!

See the other README*.md files for more specific information on setup...

Project structure

These are the most important folders:

• ansible: Provisioning and deployment definitions
• assets: Public resources to host
• certs: (Push-) certificates
• env: specific and default env vars (medium and lowest priority)
• introspect: Autogenerated Swagger and GraphQL schemas, GraphQL test queries and snapshots
• src/api: Controllers of your RESTful JSON API
• src/configure: Static service and packages configuration and env var bindings
• src/graphql: Queries and mutations of your GraphQL API
• src/hooks: Lifecycle management of all enabled features
• src/migrations: Database migrations
• src/models: Database models (ORM)
• src/scripts: Other CLI entrypoints
• src/services: Shared business logic and layers to external services
• src/test: Test environment setup
• templates: Templates for emails and static pages

Basic Concepts

The following diagram shows the basic initialization procedure. Concepts like env vars propagation (high to low priority), lifecycle management and ownership (hooks) are highlighted.

Common commands

Type yarn run to get a full list of available commands or see the project package.json file's scripts property for a complete list of available commands. The Makefile furthermore defines some useful commands which mostly only make sence with docker dev environments.

Run test suites

There are several unit and integration tests defined. At least all exposed features should be tested in the same manner. You can execute the complete test suite via yarn test (inside the Vagrant VM) or make test (through Docker on the Host).

Upgrade all @aaa-backend-stack/* packages

# Always ensure the **latest** yarn global cli version is installed!
vagrant$ sudo yarn upgrade

# Update all packages to their latest version...
vagrant$ yarn upgrade --scope @aaa-backend-stack --latest

Typescript

Code is automatically compiled using yarn build, or via your own integrated IDE.

For watch mode, simply use Visual Studio Code, hit ⌘ + SHIFT + P and type watch.

We use a global tsconfig.json file in the project for compiler configuration (see TypeScript/wiki).

Installing new packages

If you add a new external package (through yarn add PKG_NAME), always check if there is a type definition available @types/PKG_NAME.

Package ownership by @aaa-backend-stack/* packages

You are not allowed to install 3rd party packages that are explicitly owned by a @aaa-backend-stack/* package (their functionality in a specific version is guaranteed to work for the whole stack).

If you don't obey, your service will fail during startup.

Set a password in the database

You can easily set the password for a specific user with this command:

# USER_UID is optional and defaults to the root admin superuser.
vagrant$ yarn db set-user-password -p NEW_PASS [-u USER_UID]`

Generate a custom salt/password combination

To generate salt/passwords using the same hashing function of your service, simply type:

vagrant$ yarn utils defaultHashingProvider -p PASS

API Documentation

Docs are autogenerated and live by default. Don't forget to start the service: vagrant$ yarn start

OpenAPI/Swagger documentation is available at http://10.0.0.30:8080/documentation (Vagrant). GraphiQL is available at http://10.0.0.30:8080/documentation/graphiql (Vagrant).

ERM

Every backend should have its own Entity-Relationship Model diagram, please use this lucidchart template as a starting point.