en · jin · sane
This is an experimental project that aims to lower the barrier to entry for developers interested in using the nginx Web server. It tries to accomplish this by distilling and organizing information about nginx's core and module configuration settings. The information is conveniently formatted as a collection of configuration files, thus allowing developers to import this project's files directly into their nginx configuration directory.
After the initial installation of nginx, the first task a developer faces is configuring nginx by editing the nginx.conf file, usually located at /etc/nginx/nginx.conf. Currently, the content of the nginx.conf file that ships with the software is not immediately useful, as it requires the developer to look up the various directives in nginx's online documentation.
Nginsane will attempt to address this issue by bringing the documentation into the configuration file itself. Nginsane precedes each nginx directive with a comment block that provides relevant information about the directive, for example:
- syntax
- context
- example
- default values
- accepted values
- required arguments
- optional arguments
- brief description
- (compatability)*
- (module)**
- (status)***
* Could be eliminated if nginsane became part of the nginx build, because presumably nginsane would only document directives that are compatible (and non-deprecated) for its corresponding nginx build/release.
** Could be eliminated if nginsane files convey this information through file names and directory structure.
*** I grabbed this info type from [Apache's docs](http://httpd.apache.org/docs/current/mod/directive-dict.html#Statu s), but it may not be necessary or useful to have in a config file. Frankly, I haven't worked with nginx enough to know at this point.
Idea: In order to avoid overloading users with too much
information (or information that doesn't pertain to their nginx build),
nginsane could use the build parameters to determine whether or not to
include certain pieces of information. For example, the error_log
directive:
When nginx is built with --with-debug, nginsane prints:
# syntax: error_log (%file|stderr) [debug|info|notice|warn|error|crit|alert|emerg];
When nginx is built without --with-debug, nginsane prints:
# syntax: error_log (%file|stderr) [info|notice|warn|error|crit|alert|emerg];
To the extent possible, nginsane will provide safe defaults and make it reasonably difficult for inexperienced developers to shoot themselves in the foot.
To the extent possible, nginsane will provide information and working examples that follow current best practices and adhere to established conventions.
Nginsane acknowledges, appreciates, and respects the incredible amount of work that has gone into the Apache HTTP Server project and the Apache HTTP Server Documentation sub-project. Nginsane also acknowledges that many (most?) new nginx users already have some level of experience or familiarity with the Apache webserver. Therefore, nginsane will implement its own features with a deliberate awareness of how Apache achieves similar functionality. New practices and conventions will not be established arbitrarily if Apache has already established a usable system.
-
Nginx documentation - the official source of information used to build nginsane.
-
PHP function definition syntax - inspiration for defining nginsane's syntax.
-
Apache default installation directory structure - does nginx have something comparable to this? Couldn't find anything. It would certainly help automate a lot of this configuration file mumbo jumbo.
-
Nginx GNUmakefile - ideally, nginsane could become part of the nginx build process.
-
GNU Make makefile convensions - if I'm to make an attempt to incorporate nginsane into the nginx build process, I'll probably need to learn GNU Make at some point.
-
XSLT - here's another standard I'll probably need to learn. The nginx.org svn repository uses XSLT as part of their build process to turn documentation into several formats (e.g., HTML, XML). Or at least I think that's what they're using it for.
-
svn://svn.nginx.org/nginx- svn repo URL for nginx source. -
svn://svn.nginx.org/nginx.org- svn repo URL for nginx.org website source. If I actually automate nginsane to build alongside nginx, then this repo is where I'll checkout the docs to use as source files.