madewithq v1.0.1

madewithq

New modules introduced to this project will exist in separate branches. Production instances will be available in the repos that declare Q as a depenency.

This repository is the backbone of all 3merge applications. It is highly extensible: we can configure it as an order management system, content management system, event registration platform and more.

Table of contents

• Setup
  • Environment variables
    • Configuring on third-party services
  • Software configuration options

Setup

Environment variables

Locally, create a .env file in the root. Add the following code to it, replacing with real values where appropriate:

NODE_ENV=testing
LOCALHOST=localhost
USER=user
PASSWORD=password
HOSTNAME=example.com
SECRET=somestrongstring
PORT=80
EMAIL=example@yourdomain.com
PASSWORD=Str0ngPa55W0rd!12

If NODE_ENV equals "testing," it will require the LOCALHOST. Otherwise, "production" and "development" look for real server credentials. Note that the hostname encompasses everything following @ in a mongoDB URI connection string. For example, it will likely include ssl and replicaSet query parameters.

Configuring on third-party services

Not every vendor reads .env files in production. Really, this file exists for testing and development processes. When ready for production, you'll need to setup environment variables according to the vendor's own documentation. For example, checkout Heroku.

Software configuration options

Q depends on many instance properties to run. These are defined in qconfig.json at the root level. Without it, the application will fail to run. There are no default properties because the setup of each instance will be wildly different. Use the json schema below to populate the file before starting development.

{   
    /**
     * @NOTE
     * Each factory collection can be enabled and disabled.
     * For instance, this instance will contain CMS functionalities with "pages" set as true.
     * A full list of available collections comes later in this document.
     */
     
    "pages": "true",
    
    
    /**
     * @NOTE
     * There are various vendors that this software integrates with.
     * Services such as email and file hosting are provided via third-parties.
     * The credentials for each strategy defined must also exist as environment variables.
     * For a list of strategies, see each respective module's instructions below.
     */
     
     "strategies": {
         "email": "mailgun",
         "media": "cloudinary"
     }
    
    /**
     * @NOTE: 
     * This contains all role types for the application.
     * Roles can inherit permissions from other roles.
     * All "rules" refer to document collections inside the database
     */
    
    "accesscontrol": {
        "admin": {
            "inherits": "basic",
            "rules": {
                "users": ["read", "write", "delete"], 
                "pages": ["read", "write", "delete"]
            }
        },
        "basic": {}
    }
}

Modules internal API

madewithq ships with various security constraints, meaning all calls to the API must include several standard headers. The following applies to all private endpoints; however, public still requires all but the Bearer Authorization token and refreshToken cookie.

Cookie _curf // must match the x-csrf-token in the header
Cookie accessToken // this is an httpOnly cookie that the api reads

headers['x-csrf-token'] // special client generated token
headers['Authorization'] // bearer token
headers['Referer'] // must match host
headers['host']

Users

Content management

File hosting

Notifications

Email