1 | # Avian
|
2 |
|
3 | Create Enterprise-class component driven applications that scale.
|
4 |
|
5 | [![CircleCI](https://img.shields.io/circleci/build/github/flypapertech/avian/master)](https://circleci.com/gh/flypapertech/avian/tree/master)
|
6 | [![Docker Cloud Build Status](https://img.shields.io/docker/cloud/build/flypapertech/avian)](https://hub.docker.com/repository/docker/flypapertech/avian/builds)
|
7 | [![Known Vulnerabilities](https://snyk.io/test/github/flypapertech/avian/badge.svg)](https://snyk.io/test/github/flypapertech/avian)
|
8 | [![npm (scoped)](https://img.shields.io/npm/v/@flypapertech/avian.svg)](https://www.npmjs.com/package/@flypapertech/avian)
|
9 | [![License](https://img.shields.io/npm/l/@flypapertech/avian.svg)](https://github.com/flypapertech/avian/blob/master/LICENSE)
|
10 | [![Dependencies](https://david-dm.org/flypapertech/avian/status.svg)](https://david-dm.org/flypapertech/avian)
|
11 | [![Docker Pulls](https://img.shields.io/docker/pulls/flypapertech/avian)](https://hub.docker.com/r/flypapertech/avian)
|
12 |
|
13 | ## Synopsis
|
14 |
|
15 | Avian is an application server based on years of experience, built on [Express](https://github.com/expressjs/express) and [Redis](https://redislabs.com/) that meets infinitely scalable demands.
|
16 |
|
17 | ## Key Features
|
18 |
|
19 | - Multi-core / Multi-threaded application host operations remove the burden of load balancing across cpu cores.
|
20 | - Out of the box webpacking with sane defaults. Don't worry you can override and/or add to them whenever you want :)
|
21 | - A unique and easy to use component-based model that is flexible with popular frameworks such as Angular, Vue.js, ReactJS.
|
22 | - Supports popular view templating engines such as Pug, EJS, Handlebars and plain HTML.
|
23 | - Supports Pino, Bunyan, and Fluentd logging frameworks.
|
24 |
|
25 | ## Installation
|
26 |
|
27 | ### NPM
|
28 |
|
29 | The latest stable release of Avian is available on [npmjs.com](https://www.npmjs.com/package/@flypapertech/avian).
|
30 |
|
31 | The most common scenario is to install Avian as a dependency of your project.
|
32 |
|
33 | npm install @flypapertech/avian
|
34 |
|
35 | or
|
36 |
|
37 | yarn add @flypapertech/avian
|
38 |
|
39 | And can be accessed as...
|
40 |
|
41 | node ./node_modules/.bin/avian
|
42 |
|
43 | Alternatively, Avian can be installed globally, making it possible to serve multiple applications with a single installation of Avian.
|
44 |
|
45 | npm install @flypapertech/avian -g
|
46 |
|
47 | or
|
48 |
|
49 | yarn global add @flypapertech/avian
|
50 |
|
51 | And can be accessed globally, but will need to be told where your Avian application is located...
|
52 |
|
53 | avian --home /path/to/avian/app/home
|
54 |
|
55 | ### System Requirements
|
56 |
|
57 | #### NodeJS
|
58 |
|
59 | Avian requires NodeJS version 8.0 and above.
|
60 |
|
61 | #### Redis Server
|
62 |
|
63 | Avian uses Redis Server for storing session data, caching component config object requests and arbitrary caching requirements you may have.
|
64 |
|
65 | Suggested Redis Installation Methods
|
66 |
|
67 | ##### macOS
|
68 | `brew install redis`
|
69 | ##### Ubuntu Linux
|
70 | `apt install redis-server`
|
71 | ##### Alpine Linux
|
72 | `apk add redis`
|
73 | ##### Windows (experimental)
|
74 | - [Windows with WSL (10 and higher)](https://redislabs.com/blog/redis-on-windows-10/)
|
75 | - [Windows without WSL (8.1 and lower)](https://redislabs.com/blog/redis-on-windows-8-1-and-previous-versions/)
|
76 | - Note: It is not recommended to use Redis in production on Windows with out WSL.
|
77 |
|
78 | ## Getting Started
|
79 |
|
80 | ### CLI Arguments
|
81 |
|
82 | Options:
|
83 | --help Show help [boolean]
|
84 | --version Show version number [boolean]
|
85 | --name, -n The name of your application[default: "localhost"]
|
86 | --home, -h The directory of your application.
|
87 | [default: current working directory]
|
88 | --mode, -m Deployment mode to run Avian in.
|
89 | [choices: "development", "production"] [default: "development"]
|
90 | --port, -p Which port to serve your application on.
|
91 | [default: 8080]
|
92 | --defaultComponent, --dc The point of entry to your application.
|
93 | [default: "index"]
|
94 | --spa Start Avian in a single-page-application
|
95 | configuration. [boolean] [default: false]
|
96 | --bundleSkip [boolean] [default: false]
|
97 | --bundleOnly [boolean] [default: false]
|
98 | --redisHost [default: "127.0.0.1"]
|
99 | --redisPort [default: 6379]
|
100 | --redisPass [default: undefined]
|
101 | --redisSessionDB [default: 1]
|
102 | --redisCacheDB [default: 2]
|
103 | --redisCronSchedulerDB [default: 3]
|
104 | --webpackHome [default: undefined]
|
105 | --logger, -l Which logging framework to use.
|
106 | [choices: "pino", "bunyan", "fluent"]
|
107 | --loggerFluentLabel, --lfl [default: "debug"]
|
108 | --loggerFluentTag, --lft [default: "debug"]
|
109 | --loggerFluentHost, --lfh [default: "127.0.0.1"]
|
110 | --loggerFluentPort, --lfp [default: 24224]
|
111 | --sslCert [string]
|
112 | --sslKey [string]
|
113 | --cronJobScheduler, --cjs Avian components are capable of scheduling
|
114 | cron-like jobs that are executed on the server.
|
115 | [boolean] [default: false]
|
116 | --compression Use express-compression [boolean] [default: false]
|
117 |
|
118 | ### Application Folder Structure
|
119 |
|
120 | ├── assets [optional, statically served at /assets]
|
121 | ├── static [optional, statically served at /static]
|
122 | ├── cache [auto-generated by Avian in production mode to hold cached files]
|
123 | ├── components
|
124 | │ ├── avian.service.(ts/js) [optional, used to add service routes to / path]
|
125 | │ ├── component_name.client.(ts/js) [optional, contains all JavaScript/TypeScript logic for a component. Will be bundled with Webpack]
|
126 | │ ├── component_name.view.(pug/ejs/html) [optional, renders output to a screen, e.g. a /component_name get request]
|
127 | │ ├── component_name.service.(ts/js) [optional, used to add service routes to /component_name]
|
128 | │ ├── component_name.config.json [optional, served at /component_name/config/objects.json and passed to view files at render time]
|
129 | │ ├── component_name [components can be in a flat folder or scaffolded like this]
|
130 | │ │ ├── component_name.client.(ts/js)
|
131 | │ │ ├── component_name.view.(pug/ejs/html)
|
132 | │ │ ├── component_name.service.(ts/js)
|
133 | │ │ ├── component_name.config.json
|
134 | ├── logs [auto-generated by Avian in production mode]
|
135 | ├── package.json
|
136 | ├── private [auto-generated by Avian to contain server side compiled files, e.g. component service files]
|
137 | ├── public [auto-generated, for compiled component bundles, statically served at /]
|
138 |
|
139 | ### Session Management
|
140 |
|
141 | Avian uses [express-session](https://github.com/expressjs/session) to manage client sessions. All sessions are stored in a Redis store.
|
142 |
|
143 | - Browser Based Clients
|
144 | - Avian uses secure [HttpOnly Cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies) for managing browser based client sessions.
|
145 |
|
146 | - Mobile Device and API Clients
|
147 | - Avian augments express-session to allow API and mobile device sessions management. Since those clients may not use coookies they simply need to send their session ID in the authorization header of all requests made to Avian. See below for an example header.
|
148 |
|
149 | ```json
|
150 | headers: {
|
151 | Authorization: "Bearer Session_ID"
|
152 | }
|
153 | ```
|
154 |
|
155 | ### Global Variables Added by Avian
|
156 |
|
157 | #### Properties Added to All Request Objects
|
158 |
|
159 | `req.argv` contains a copy of all arguments passed to Avian at start time.
|
160 |
|
161 | `req.cache` is a RedisClient instance hooked to Avian's config object cache. Feel free to use it for your own needs as well.
|
162 |
|
163 | `req.params` paramaters passed to your component. Typically this is used to determine the component name being rendered, e.g. req.params.component.
|
164 |
|
165 | `req.query` contains all query parameters passed to the componenent being requested.
|
166 |
|
167 | #### Developing w/ TypeScript
|
168 |
|
169 | To make TypeScript aware of the globals Avian adds to your application simply place the below import into any .d.ts file that is within your application.
|
170 |
|
171 | ```typescript
|
172 | import * as Avian from "@flypapertech/avian"
|
173 | ```
|
174 |
|
175 | ## Examples
|
176 |
|
177 | Examples are located in the [examples directory](https://github.com/flypapertech/avian/tree/master/examples).
|
178 |
|
179 | ## Contributors
|
180 |
|
181 | Dan Stephenson
|
182 | Nick Fredricks
|
183 |
|
184 | ## License
|
185 |
|
186 | MIT
|
187 |
|
188 | ## Copyright
|
189 |
|
190 | 2018 - 2020 FlyPaper Technologies, LLC
|
191 | 2016 - 2018 Thoughtpivot, LLC
|