apache-bridge v0.3.1

apache-bridge

Start, stop, and configure Apache via Node.

apache-bridge is a Node wrapper for Apache HTTP Server. This is not a replacement for Apache, so you must have Apache installed in order to use apache-bridge to connect.

Table of Contents

• Background
• Installation
• Basic Usage
• Advanced Usage
• Extensions
• Documentation
  • apache.createServer([confListener])
  • Class: apache.Server
    • Event: 'close'
    • Event: 'configure'
    • Event: 'error'
    • Event: 'listening'
    • server.bin
    • server.close([callback])
    • server.listen([port][, hostname][, callback])
    • server.listening
  • apache.createConf([finishedListener])
  • Class: apache.Conf
    • Event: 'finished'
    • conf.addArgument(argument, value) - To be deprecrated in v1.x.x
    • conf.addDirective(directive)
    • conf.afterConf(directive) - To be deprecrated in v1.x.x
    • conf.beforeConf(directive) - To be deprecrated in v1.x.x
    • conf.define(parameter)
    • conf.end(directive)
    • conf.file
    • conf.finished
    • conf.include(path)
    • conf.loadModule(moduleName, modulePath)
    • conf.prependDirective(directive)

Background

This project allows the use of Node-based build tools to develop Apache-based web applications. The API is modeled after Node's http.Server class to accommodate light interchangeability. In lieu of a 'request' event, apache-bridge provides a 'configure' event along with the apache.Conf class.

Note: This module is designed for development use only. Do not try to manage a live web server with apache-bridge.

// http module
var http = require('http');
var server = http.createServer(requestListener);
server.listen(8000, 'localhost', callback);

// apache-bridge module
var apache = require('apache-bridge');
var server = apache.createServer(confListener);
server.listen(8000, 'localhost', callback);

Installation

Install and inject into package.json as a devDependency:

npm install apache-bridge --save-dev

or install globally:

npm install -g apache-bridge

Basic Usage

Create instance of Server class

var apache = require('apache-bridge');
var server = apache.createServer();

Set path to Apache

If the path to your Apache httpd file is not inclued in your $PATH environment variable, you can specify the path explicitly via server.bin:

server.bin = '/path/to/apache/bin';

You can also manually add the path to process.env.PATH:

process.env.PATH = '/path/to/apache/bin:' + process.env.PATH;

Start server

server.listen(8000, 'localhost', function() {
    // Apache is listening on localhost:8000!
});

Stop server

server.close(function(err) {
    if(err) {
        // Apache already stopped!
    } else {
        // Apache stopped!
    }
});

Advanced Usage

The server configuration can be manipulated on the fly by adding a listener to the 'configure' event:

var path = require('path');
var server = apache.createServer(function(conf) {
    conf.file = '/path/to/httpd.conf');
    conf.addDirective('Define docroot ' . path.resolve('./src'));
        .include(path.resolve('./conf/extra/file.conf'))
        .end();
});
server.listen(8000);

The snippet above sets Apache's default config file to the one found at /path/to/httpd.conf and adds the following directives:

Processed before httpd.conf:

Define docroot /path/to/src

Processed after httpd.conf:

Include /path/to/conf/extra/file.conf

See apache.Conf for more details about configuration options.

See Apache documentation for more details about configuration directives.

Extensions

The following other libraries are built using apache-bridge:

• apache-connect - Configureware for Node apache-bridge.
• apache-webpack-plugin - Start Apache via webpack-dev-server.

Coming soon

• grunt-apache-connect - Start an Apache web server via grunt and apache-connect.
• gulp-apache-connect - Start an Apache web server via gulp and apache-connect.

Documentation

apache.createServer(confListener)

• confListener <Function>
• Returns: <apache.Server>

Class: apache.Server

This class is used to start and stop Apache.

Event: 'close'

Emitted when the httpd child process exits.

server.on('close', function() {
    // Apache stopped!
});

Event: 'configure'

• <apache.Conf>

The 'configure' event is emitted after server.listen() is called but before the httpd child process is spawned.

var server = apache.createServer(function(conf) {
    // Manipulate conf settings...
    conf.end();
});

Event: 'error'

• <Error>

The 'error' event is emitted whenever:

1. The httpd child process could not be started, or
2. The httpd child process could not be stopped

Event: 'listening'

Emitted when the server has been bound after calling server.listen().

server.on('listening', function() {
    // Apache is ready!
});

server.bin

• <string> Defaults to ''.

Set path to Apache bin directory where Apache httpd is located. This may be necessary if the path is not defined in your system's $PATH environment variable.

server.close(callback)

• callback <Function>
• Returns <apache.Server>

Kills the httpd child process.

server.close(function(err) {
    if(err) {
        // Apache already stopped!
    } else {
        // Apache stopped!
    }
});

server.listen(port, callback)

• port <number> Port of remote server. Defaults to 80.
• hostname <string> A domain name or IP address of the server to issue the request to. Defaults to localhost.
• callback <Function>
• Returns <apache.Server>

Start an Apache server listening for connections on the given port and host.

server.listen(8000, 'localhost', function() {
    // Apache is ready!
});

server.listening

• <boolean>

A Boolean indicating whether or not the server is listening for connections.

apache.createConf(finishedListener)

• finishedListener <Function> Called after 'finished' event is emitted
• Returns: <apache.Conf>

Class: apache.Conf

This class is used to configure Apache.

Event: 'finished'

Emitted after conf.end() is called.

conf.addArgument(argument, value)

To be deprecated in v1.x.x.

This method adds arguments to the httpd process at runtime. To minimize the number of runtime arguments and to avoid having to escape complex directives, directives are now added to temporary Include files via the conf.prependDirective() and conf.addDirective() methods. Use the following methods (or property) instead of the corresponding runtime arguments:

• -f: conf.file
• -c: conf.addDirective()
• -C: conf.prependDirective()
• -D: conf.define()

conf.addDirective(directive)

• directive <string>
• Returns: <apache.Conf>

Process the configuration directive after reading conf.file.

See Apache documentation for more details about configuration directives.

conf.afterConf(directive)

To be deprecated in v1.x.x.

Use conf.addDirective() instead.

conf.beforeConf(directive)

To be deprecated in v1.x.x.

Use conf.prependDirective() instead.

conf.define(parameter)

• parameter <string>
• Returns: <apache.Conf>

Sets a configuration parameter which can be used with <IfDefine> sections in the configuration files to conditionally skip or process commands at server startup and restart.

// apache-bridge
if(process.env.NODE_ENV === 'development') {
    conf.define('TEST');
}

conf.addDirective('<IfDefine TEST>')
    .addDirective('Define servername test.example.com')
    .addDirective('</IfDefine>');

# Directive
Define TEST

<IfDefine TEST>
Define servername test.example.com
</IfDefine>

See Apache documentation for more details about the Define directive.

conf.end(directive);

• directive <string>

Emits the 'finished' event and sets conf.finished to true. Once this method is called, no more changes to the apache.Conf instance are permitted. This prevents server.listen() from starting Apache before any asynchronous configuration actions are completed.

Note: conf.end() will be called automatically on server.listen() if no listeners are bound for the 'configure' event.

conf.file

• <boolean> | <string> | <null>

Boolean, string, or null value that indicates whether Apache should load its default httpd.conf file (true|null), another config file (string path to config file), or no config at all (false).

conf.finished

• <boolean>

Boolean value that indicates whether the conf is ready to be processed. Starts as false. After conf.end() executes, the value will be true.

conf.include(path)

• path <string>
• Returns: <apache.Conf>

Add an Include directive to be processed after reading conf.file.

// apache-bridge
conf.include('/usr/local/apache2/conf/ssl.conf');

# Directive
Include /usr/local/apache2/conf/ssl.conf

See Apache documentation for more details about the Include directive.

conf.loadModule(moduleName, modulePath)

• moduleName <string>
• modulePath <string>
• Returns: <apache.Conf>

Add a LoadModule directive to be processed after reading conf.file.

// apache-bridge
conf.loadModule('status_module', 'modules/mod_status.so');

# Directive
<IfModule !status_module>
LoadModule status_module "modules/mod_status.so"
</IfModule>

See Apache documentation for more details about the LoadModule directive.

conf.prependDirective(directive)

• directive <string>
• Returns: <apache.Conf>

Process the configuration directive before reading conf.file.

See Apache documentation for more details about configuration directives.