*** Base now supports ***
- Username and Password Sign-in and Sign-up with password hashing
- Integration tests on server endpoints
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 out 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:
A starter kit and reference implementation for Facebook's ReactJS+Flux.
We love React+Flux and think you will too. 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.
Secure web application stack using OAuth2.
We wanted a starter kit that scaffolds out a baseline implementation of a modern secure web application.
A light and scalable Web Server
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.
An RDBMS Alternative
MongoDB is a very popular persistent store on the web, and with many good reasons. But we think 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.
Gulp + Webpack + React + Flux + Express + Postgres + Passportjs + Bootstrap + Jade + Mocha + Chai.
- React+Flux Scaffolding
- NodeJS Express web server
- PassportJS for OAuth2
- Username and Password Sign-in and Sign-up
- Social logins (Google and Facebook)
- HelmetJS for header protection mechanisms
- TLS/SSL By default
- XSS protections
- CSRF protections
- Secure sessions
Manual Install Requirements
Before running the install scripts for Base, there's a few manual steps that you'll need to do to get up and running.
- A running instance of PostgreSQL is required. The latest version of PostgreSQL can be found here: http://www.postgresql.org/download/. pgAdmin - the defacto admin platform for PostgreSQL can also be downloaded here: http://pgadmin.org/
- When you install Postgres, open up pgAdmin, and create a brand new empty database. The Gulp scripts don't create this database automatically. The name of this database needs to be indicated in your DB connection string in your .env file.
- To prep Base for social logins, you will need to setup your app's OAuth details for each of the respective providers you intend to use (Facebook login, Google login etc)- more details here auth.md
- To run Base locally in development and to use social logins, OAuth providers (Facebook, Google) need an actual resolvable domain to use for the redirect URI. localhost won't cut it for the redirect URI's. You will need to edit your hosts file (on a Mac /etc/hosts) and add the line:
Setting your environment settings and config
Configs are stores in
.env files in the root directory of Base that correspond to the running
NODE_ENV value. So if you're running in development, Base will look for
development.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
.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
production.env etc for each
NODE_ENV you have.
Base uses Gulp + Webpack as it's build system. To install base for your app:
$ git clone https://firstname.lastname@example.org: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
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.CA settings have default values for SSL used for development, so it's safe to copy these over to
- Check that you have a running instance of Postgres and that your DB is live.
- Make sure your port in your .env profile matches your running Postgres port
- Make sure that you have an empty DB already created. gulp bootstrap does not create a DB automatically, just the tables
then to run the application, type:
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 out 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