Nuclear Pizza Machine

    apache-bridge
    TypeScript icon, indicating that this package has built-in type declarations

    0.3.1 • Public • Published

    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

    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:

    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])

    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:

    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][, hostname][, 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:

    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.

    Keywords

    none

    Install

    npm i apache-bridge

    DownloadsWeekly Downloads

    25

    Version

    0.3.1

    License

    ISC

    Unpacked Size

    59.2 kB

    Total Files

    16

    Last publish

    Collaborators

    • mattscott2040