Ember FastBoot App Server
The FastBoot App Server is an application server for hosting Ember FastBoot apps. It manages downloading the Ember app, starting multiple HTTP server processes, and detecting when new versions of the application have been deployed.
FastBoot allows Ember apps to be rendered on the server, to support things like search crawlers and clients without JavaScript. For more information about FastBoot, see FastBoot website.
Extensibility
The App Server is designed to be flexible and extensible enough to run in whatever environment you want to use to host FastBoot apps. In particular, you can provide a custom:
- Downloader, to control how app builds gets downloaded
- Notifier, to control how new versions of the build are detected
- HTTP Server, to use whatever stack you prefer for serving HTTP requests in Node.js
Requirements
FastBoot App Server requires Node.js v10 or later.
Quick Start
Put the following in a fastboot-server.js file:
const FastBootAppServer = require('fastboot-app-server');
const MY_GLOBAL = 'MY GLOBAL';
let server = new FastBootAppServer({
distPath: 'dist',
gzip: true, // Optional - Enables gzip compression.
host: '0.0.0.0', // Optional - Sets the host the server listens on.
port: 4000, // Optional - Sets the port the server listens on (defaults to the PORT env var or 3000).
buildSandboxGlobals(defaultGlobals) { // Optional - Make values available to the Ember app running in the FastBoot server, e.g. "MY_GLOBAL" will be available as "GLOBAL_VALUE"
return Object.assign({}, defaultGlobals, { GLOBAL_VALUE: MY_GLOBAL });
},
log: true, // Optional - Specifies whether the server should use its default request logging. Useful for turning off default logging when providing custom logging middlewares
chunkedResponse: true // Optional - Opt-in to chunked transfer encoding, transferring the head, body and potential shoeboxes in separate chunks. Chunked transfer encoding should have a positive effect in particular when the app transfers a lot of data in the shoebox.
});
server.start();Configure distPath to point to the dist directory you upload to
your server. (See Application Builds below.)
Run the server file:
$ PORT=8000 node fastboot-server.js
This will start an HTTP server on port 8000. To stop the server, type
Ctrl-C.
NOTE: If you want to continue running ember serve in development, name the file fastboot-server.js instead.
Application Builds
When you build an Ember.js app via ember build, it will build the app
for production and, by default, put the resulting files in your
application's dist directory.
Clustering
Because Node.js is single-threaded, you must run multiple processes to
take advantage of multi-core systems. FastBoot App Server takes
advantage of Node's clustering support out of the box, automatically
spawning one worker HTTP server per core. You can override this via options.workerCount.
The app server will automatically spawn a new worker if one dies while handling a request. When a new application deploy is detected, workers will automatically reload with the newest version.
Custom HTTP Server
You can customize HTTP server (add middlewares, subdomains, etc.), either directly:
// start.js
const FastBootAppServer = require('fastboot-app-server');
const ExpressHTTPServer = require('fastboot-app-server/src/express-http-server');
const httpServer = new ExpressHTTPServer(/* {options} */);
const app = httpServer.app;
app.use('/api', apiRoutes);
let server = new FastBootAppServer({
httpServer: httpServer
});
server.start();or extend the provided HTTP server and override any methods you need:
// my-custom-express-server.js
const FastBootAppServer = require('fastboot-app-server');
const ExpressHTTPServer = require('fastboot-app-server/src/express-http-server');
class MyCustomExpressServer extends ExpressHTTPServer {
serve(middleware) {
// put your custom code here, don't forget to add fastboot etc.
}
}
// start.js
const MyCustomExpressServer = require('./my-custom-express-server');
const httpServer = new MyCustomExpressServer(/* {options} */);
let server = new FastBootAppServer({
httpServer: httpServer
});
server.start();Pre and Post FastBoot middleware hooks
If you need something less than a custom server and just want to run some middleware before or after FastBoot runs, the server provides hooks for you to do so:
// Custom Middlewares
function modifyRequest(req, res, next) { /* do pre-fastboot stuff to `req` */ };
function handleErrors(err, req, res, next) { /* do error recovery stuff */ };
const server = FastBootAppServer({
beforeMiddleware: function (app) { app.use(modifyRequest); },
afterMiddleware: function (app) { app.use(handleErrors); }
})Logging
We provide simple log output by default, but if you want more logging control, you can disable the
simple logger using the log: false option, and provide a custom middleware that suits your logging needs:
let server = new FastBootAppServer({
log: false,
beforeMiddleware: function(app) {
let logger = function(req, res, next) {
console.log('Hello from custom request logger');
next();
};
app.use(logger);
},
});Downloaders
You can point the app server at a static path that you manage, but that means taking responsibility for uploading builds to each server whenever you want to deploy a new version.
Instead, you can provide the app server with a downloader, an adapter that knows how to download the current version of your application.
For example, to use the S3 downloader that downloads a zip file from AWS S3:
const S3Downloader = require('fastboot-s3-downloader');
const FastBootAppServer = require('fastboot-app-server');
let downloader = new S3Downloader({
bucket: 'S3_BUCKET',
key: 'S3_KEY'
});
let server = new FastBootAppServer({
downloader: downloader
});
server.start();Available Downloaders
Writing a Downloader
To write your own downloader, construct an object that conforms to the following interface:
download()
Returns a promise that resolves to the path to the downloaded dist
directory (which does not have to be named dist).
Note that download() may be called more than once in the lifetime of
an application, if a new version is deployed. Make sure your downloader
cleans up after itself to avoid running out of disk space.
Notifiers
Once the FastBoot App Server is up and running, it will happily chug away until the server dies or it reaches the inevitable heat death of the universe. Before that happens, presumably, you may want to deploy a new version of your application.
Notifiers are responsible for detecting when a new version of an app has been deployed and reloading the app server.
For example, here's how to use the S3 notifier, which polls the last modified date of a file on S3 to detect new versions:
const S3Notifier = require('fastboot-s3-notifier');
const FastBootAppServer = require('fastboot-app-server');
let notifier = new S3Notifier({
bucket: S3_BUCKET,
key: S3_KEY
});
let server = new FastBootAppServer({
notifier: notifier
});
server.start();Available Notifiers
Writing a Notifier
To write your own notifier, construct an object that conforms to the following interface:
subscribe(notify)
The subscribe() method on your notifier is passed a notify function.
If you detect that a new version of your app has been deployed (whether
via polling or a push notification), call this function to trigger a
reload.
Basic Authentication
You can enable Basic Authentication by providing username and password options:
const FastBootAppServer = require('fastboot-app-server');
let server = new FastBootAppServer({
username: 'tomster',
password: 'zoey'
});Scraper Issues
Twitter and LinkedIn
As of 2019-06-06, Twitter and LinkedIn's scrapers have a hard time extracting your site's metadata for sharing if chunkedResponse is set to true in your server.js file. Set chunkedResponse: false if your meta tags are in place but the Twitter card validator shows "Card not found" or LinkedIn's Post Inspector shows a 500 error.