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
- 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.xconf.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 viagrunt
andapache-connect
.gulp-apache-connect
- Start an Apache web server viagulp
andapache-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'
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:
- The
httpd
child process could not be started, or - 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 to80
.hostname
<string>
A domain name or IP address of the server to issue the request to. Defaults tolocalhost
.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.