Base is a seed / starter kit for a modern web application stack, scaffolded out with a baseline level of security. Built with ReactJS, Flux, Express, and Postgres.
View the demo at https://demo.basestackjs.com
Check out the contribute.md
The philosophy around Base was to roll out a baseline set of security features for protection against common web application threats to give developers a kick start when building our their app.
We're not trying to be a silver bullet, but we are aiming to give developers as big a kick start as possible.
Some of the other why's include:
We love React Flux and think you will to. Base scaffolds out React components along with related Flux actions and stores, and provides a starter framework for getting a ReactJS front-end chatting with an Express / Postgres back-end.
We wanted a starter kit that scaffolds out a baseline implementation of a modern secure web application.
Express and NodeJS provides a powerful and scalable web stack as a base. Other than this, we don't impose any other framework choice on the server side.
MongoDB is a very popular persistent store on the web, and with many good reasons. But we thnk there are many apps out there where an RDBMs is still the most relevant choice. We chose Postgres as a fast, scalable, open source, and well supported RDBMS option.
The Stack:
Gulp Webpack React Flux Express Postgres Passportjs Bootstrap Jade Mocha Chai.
- React Flux Scaffolding
- React-router
- WebPack Gulp
- Postgres
- NodeJS Express web server
Security:
- PassportJS for OAuth2
- Social logins (Google and Facebook)
- HelmetJS for header protection mechanisms
- TLS/SSL By default
- XSS protections
- CSRF protections
- Secure sessions
- A running instance of PostgreSQL is required. The latest version of PostgreSQL can be found here: http://www.postgresql.org/download/.
- To prep Base for social logins, you will need to setup your app's OAuth details for respective providers - more details here auth.md
Base uses Gulp Webpack as it's build system. To install base for your app:
$ git clone https://[email protected]:adeperio/base.git MyApp
$ cd MyApp
$ npm install -g gulp # Install Gulp task runner globally
$ npm install # Install Node.js components listed in ./package.json
Configs are stores in .env
files that correspond to the running NODE_ENV
value.
So if you're running in production, Base will look for production.env
config in the root directory of your project.
Config is loaded into your app using dotenv
, and can then be accessed throughout your app using config.js
By default .env
files are in .gitignore
to avoid checking in secrets and settings, so you will need to manually create .env
files in your repository.
NEVER check in your configs to repositories. Secrets, credentials and other sensitive settings generally exist in these files so we need to make sure these are kept out of VCS.
There is however a sample.env
file (not used by Base, and excluded from .gitignore
) that exists with an example list of settings that Base recognizes and supports.
You can use sample.env
as a starting point to fill out your config settings. Copy this file and rename the copies to development.env
, test.env
, production.env
etc for each NODE_ENV
you have.
Once you clone the repo, install the dependencies, and set your configs, you will need to bootstrap the database with the initial tables.
To bootstrap a NEW database, simply run:
$ gulp bootstrap
BE CAREFUL to run this on any existing DB instance and this will wipe and reset the database to initial Base settings. This includes wiping all data, tables, and schemas
The bootstrap script also creates self signed certs for use in development. In the sample.env
file, the TLS.KEY
, TLS.CERT
, and TLS.CA
settings have default values for SSL used for development, so it's safe to copy these over to development.env
.
And finally, to run the application, type:
$ gulp
Base has a suite of tests that runs against a test database. Mocha Chai are used as the test frameworks.
To run the tests, you will need to make sure you have a running instance of a test Postgres DB.(e.g. postgres://postgres:postgres@localhost:5432/base-test).
The settings for your test environment can be entered in your test.env
config file. NODE_ENV=test
uses only a small number of settings that are present in other environments, for example, the Oauth login settings aren't relevant for test runs.
More test coverage coming, an ongoing task...
Once this is setup, run the tests by:
$ gulp test
Base can build out a production distribution in a dist
folder. To build out a version for distribution type:
gulp build:dist --release
This will copy over a production.env
file into the dist
folder, whilst keeping our any self-signed certs generated.
SFTP the contents of this folder to your VPS and run npm install
to install all of the dependencies.
After this, you can point ForeverJS (or PM2) to your server.js
file in your dist
folder on your production server to run the app.
On the roadmap, Yeoman generators, and Heroku deploys
Base is under MIT license - LICENSE.txt