12factor.net app platform for node.js, built on express 3
$ sudo npm install -g base12$ base12 new projectname && cd projectname$ make open
$ make setup
$ make simple
$ make open
$ make run
$ make run 1
$ make cycle
$ make cycle 1
$ make profile
$ make profile-lazy
$ make debug
$ make debug-brk
assets -- place to store assets for project (graphics, src files, etc.)components -- place to store components for small piecs of functionality in app/dashboard -- default dashboard example component/errors -- default component for handling server errors/user -- default component for user functionality using mvc pattern (signup, signin, signout, settings)doc -- documentationlib -- app specific and non-npm-published node.js libraries/balance -- uses cluster to create and blance multiple processes/config-load -- loads available config files/flash -- flash messaging/inject --/locals -- add resuable local helpers to app views/middleware -- sets up express middleware (stylus, sessions, logs)/mongoose -- connects mongoose to mongodb/mongoose-util -- provides mongoose helpers (validations, plugins, etc)/redis -- provides app-wide redis connection/reload -- watches for file changes and reloads apppublic -- static files are hosted herescripts -- scripts (eg admin, deployment, migrations)test -- tests (mocha by default)tmp -- your app can store temporary files hereapp.js -- runs your appconfig.default.js -- default config (no sensative passwords or location specific options)config.local.js -- local config (ignored by git, create to store sensative information and location specific options)config.test.js -- config for running testsMakefile -- automated task makefilepackage.json -- npm package.json
All base12 components have the same signature:
// ...return my_module;
The component or lib is responsible for supplying the app with the needed interface hooks. For example, a component might look like:
appget'/dashboard'return resrenderrequire'path'join__dirname 'dashboard'user: reqsessionuser;;;
Application constants (values that do not change from machine to machine) are located in
moduleexports =http_port: 3000cluster: truerequest_timeout: 100000session_secret: "base12secret"log_requests: falsestylus_compress: 1stylus_debug: 1stylus_force: 1test: falseredis_host: "localhost"redis_port: 6379redis_pass: ""redis_debug: falsemongoose_url: "mongodb://localhost/base12";
Environment config (values that can change from machine to machine) are located in
config.local.js, which is not tracked by git.
You can create this file whenever needed and it values will override the defaults if both exist.
moduleexports =http_port: 80mongoose_url: "mongodb://username:firstname.lastname@example.org/base12";
"One codebase tracked in version control, many deploys."
Base12 uses git-based deployments exclusively.
"Explicitly declare and isolate dependencies."
npm install both locally and in deploys to manage dependencies.
Manage your dependencies in
"Store config in the environment."
Base12 uses the untracked config.local.js file to manage environment config. Once tooling is better supported on hosts, it will likely move to environment variables.
"Treat backing services as attached resources."
Backing service configuration is stored in config.local.js on each host.
"Strictly separate build and run stages."
make build builds a base12 app's assetes, while
make run executes it.
make cycle watches local files and cycles between build and run phases for rapid development.
"Execute the app as one or more stateless processes."
Base12 apps are stateless. The built-in session manager is backed by redis, and apps can be run as any number of independent processes forked from app.js. The directory structure provides /tmp for temporary file manipulation, but provides no permanent file storage mechanism since that should be done through a backing service.
"Export services via port binding."
Ultimately, base12 relies on node's built-in http server to field requests. No http container or helper is needed.
"Scale out via the process model."
Using deployment-specific process managers (eg, upstart), base12 keeps the master node.js process running.
base12.balance uses cluster to spawn and monitor multiple processes on a single machine.
New process types can be created by writing modules with a
start() method, and passing that process module to
base12.balance() in run.js.
"Maximize robustness with fast startup and graceful shutdown."
Base12 uses a crash-only design. Uncaught errors exit the process, triggering the balancer to replace it. Startup is nearly immediate.
"Keep development, staging, and production as similar as possible."
We encourage you to keep your config.local.js configurations as similar as possible across machines to maximize parity.
"Treat logs as event streams."
Base12 logs events directly to stdout and stderr.
"Run admin/management tasks as one-off processes."
All admin processes are handled with scripts in the /scripts directory. Built-in scripts include provisioning and deployment, tests, dependency management, and generators.
Copyright (c) 2013, Skookum Digital Works
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.