File Structure & Configuration
JaxServer Directory Structure
JaxServer's file layout should be familiar to developers accustomed with other web application servers such as Apache Tomcat:
- - jax apps are stored here
- - reference CRUD app using CouchDB
- - where this documentation is stored, the docs are also an app
- - jaxserver reference examples
- - the virtual hosts application
- - startup scripts and jax commands
- - where gzipped cached static files are generated and stored
- - configuration files, mime types, ssl config etc.
- - javascript libraries
- - the Jaxcore API
- - http access and error log files
- - a global /static directory shared between all apps
- - default directory where uploads are saved
App Directories
When a jax app is created, a directory structure and two files are automatically generated. In the previous chapter when we created a "helloworld" app, a corresponding helloworld directory was created in ~/jaxserver/app:
-
- - application file, the "controller"
- - reusable MVC templates go here
- - JXP template for the "index" view
- - public web files go here
Try adding new files to the application by putting them in the "web" directory:
cd ~/jaxserver/app/helloworld/web echo "this is a test" > test.html
Start the server again, and visit http://localhost:8000/test.html
You can also try adding new directories:
mkdir mydir echo "this is a test" > mydir/test.html
Then visit http://localhost:8000/mydir/
The next chapter, Controllers and Routing, will go into detail about application files (helloworld.js), and JaxServer Pages (JXP) will explain everything about JXP templating.
Server Configuration
Configuration file structure:
- - primary configuration file
- - security password used for session handling
- - folder to store ssl keys
- - shows how to generate test key/cert
- - a simple nodejs script for testing ssl keys
- - file extention to mime-type mappings
- - virtual host configuration, domain to app mappings
Command Options
All of JaxServer's configuration options can be set in the /conf/config.js file. There are two types of options: command options, and runtime options. Command options can be altered from the jax cli to alter any of the other options at runtime.
| Option | Description | Default |
|---|---|---|
| env | Environment variable to differentiate between development and production systems. This option is used to modify other options at startup and runtime, choose either "dev" or "prod" | dev |
| serverRoot | base jaxserver directory | ~/jaxserver |
| ipaddress | bind HTTP server to a specific IP address, use null to listen on all available IP's | null |
| port | HTTP server's port | 8000 |
| loglevel | this determines which jax.log commands are sent to stdout, choose one of: trace debug, info, warn, error, fatal | trace |
| quiet | send jax.log commands to stdout | false |
| locale | sets the server's locale for date formating | ISO |
| logfiles | record all access and error logs in /jaxserver/logs | true |
| configFile | location of the config file | /conf/config.js |
| vhostsConfig | location of virtual host configuration file | /conf/vhosts.js |
| sslHost | set which domains ssl keys will be used, see SSL for details | null |
These options can be added to the jax command line interface using the format --option=value. This is a quick way to launch an app on a different port, or to quickly test different environments.
For example, to run the welcome app on port 8001, in production mode, using SSL keys for a fictional domain "example.com", type:
jax run welcome --port=8001 --env=prod --protocol=https --sslHost=example.com
Runtime Options
Runtime options are different from command options in that they cannot be set from the command line and are often conditionally set based on the environment. Since the config.js file is executed as a regular JavaScript file, any commands available to NodeJS can be performed in config.js upon server startup.
| Option | Description | Default |
|---|---|---|
| accessLogFormat | determines how access.log file stores it's information, based on Apache log formats | combined |
| httpLogTrace | send the http request logs to jax.log.trace, this will output every HTTP request in the server consule, useful for development | true |
| accessLogFile | filename to record http request activity, this reduces server performance slightly with the benefit of recording every access | /logs/access.log |
| errorLogFile | filename to record errors | /logs/error.log |
| hideDotFiles | return a 404 error on any file that starts with a dot | true |
| libRoot | location of the jaxscript, jaxserver, and required libraries | /lib |
| jxpRoot | location of built-in templates (error messages, directory list) | /lib/jaxcore/jxp |
| jaxscriptRoot | location of JaxScript distribution | /lib/jaxscript |
| uploadDir | default location where uploaded files are written | /upload |
| appRoot | application directory | /app |
| sessionExpires | how many minutes sessions are active for | 60 |
| cacheStaticFiles | whether or not to store static files in memory, in large sites this option should be turned off or static files served elsewhere | true |
| jxpCache | sets whether compiled JXP templates will be stored in memory. In production systems this should be turned on, but with the knowledge that every JXP file will remain in memory. Also, the JaxServer will need to be restarted when a JXP has been changed. | false |
| jxpDebug | enables jxp debugging, use only in development | true |
| directoryIndexes | generate directory lists when no index (view, jxp, or html) is defined | true |
| directoryCache | whether or not to cache directory lists, this requires memory but will improve directory list performance if it is used often | |
| globalAliases | determines which directories and files will be served globally to all apps, see Static File Caching | /static /favicon.ico |
| cacheDir | where gzipped static cached files are generated and stored | /cache |
| staticGzipTypes | file extensions used to determine if they will be gzipped into the static cache | html htm txt xml xsl js json css |
| staticGzipBuffer | will buffer gzipped static cached files in memory for fast access | true |
| useCache | turn caching of any type on or off (default is off for development, on for production) | false |
| consoleColors | colors to use for jax.log commands | [37,90,34,31,91,95] |
| iconPath | where icons used in directory listings are served from | /static/icons |
| sessionManager | which session management system to use | session-memory |
jax.config.*
At any time inside JaxServer applications or JXP templates you can refer to these configuration options using:
jax.config.OPTIONNAME
For example, to only perform an action in a production server, use:
if (jax.config.env==='prod') {
/* production code here */
}
else {
/* development code here */
}
The jax config command line tool can be used to show all configuration options:
$ jax config jax.config.env = dev jax.config.serverRoot = ~/jaxserver jax.config.ipAddress = null jax.config.port = 8000 jax.config.loglevel = error jax.config.quiet = false jax.config.locale = ISO jax.config.logfiles = true jax.config.sslHost = null ....
A specific configuration option can be printed with extra options:
$ jax config port 8000 $ jax config accessLogFormat accessLogFile combined ~/jaxserver/logs/access.log