Configure Waxx

Waxx uses a simple YAML file for config. Each environment has its own directory with a config.yaml file and any other environment-specific files.

In the installation directory, there is a folder opt/:

|-- active -> dev          # A symbolic link to the the active config folder (dev in this case)
|-- deploy.yaml            # How to deploy to each environment (servers and commands to run, see below.)
|-- dev                    # The dev environment
|   |-- config.yaml        # The config file (see details below)
|   |-- nginx.conf         # The webserver config file
|   `-- ssl                # The container for SSL keys and certs
|       |-- fullchain.pem  # Self-signed cert for development
|       `-- privkey.pem
`-- prod                   # The production environment
    |-- config.yaml        # The config file (see details below)
    |-- deploy             # A deploy script that is run on the production server(s) (see below)
    `-- nginx.conf         # The production webserver config (could be Apache or HAProxy too)
                           # SSL certs for production are stored on the production servers (or you can put them here)
# stage and test folders are also here.

The Waxx Config File

  host: localhost                             # IP or host name to listen on
  port: 7777                                  # Port to listen on
  min_threads: 4                              # Start this many threads (each thread has a database connection)
  max_threads: 4                              # Additional threads will be added up to max if the queue is full
  idle_thread_timeout: 300                    # Kill a thread that is idle for this many seconds
  log_dir: log                                # Where to put the logs
  pid_dir: tmp/pids                           # Where to store the pid file (used for stopping and restarting the processs)

  name: The name of your app or site
  support_email:             # The email used to send email from by default. (This is bogus address for the docs) 
  url:                   # The URL of your site. This is normally not the same as the server/host above.

encryption:                                   # Every waxx installation should have its own random strings here. DO NOT COPY THESE!!!
  cipher: AES-256-CBC                         # The encryption cypher to use (anything supported by OpenSSL)
  key: S0M3-r@nd0m-32-CHAR-5TR!NG......       # The 32-character key (random string - DO NOT COPY!!!)
  iv:  A-16-CHAR-5TR!NG                       # The 16-character initiation vector (random string - DO NOT COPY!!!)

cookie:                                       # Cookie options. Waxx uses two cookies
  user:                                       # A short-lived session cookie
    name: wxu                                 # Session cookie name
    expires_after_login_mins: 1440            # Expires in minutes after login
    expires_after_activity_mins: 480          # Expires in minutes after last activity
    secure: true                              # Only send over HTTPS
  agent:                                      # A long-lived cookie for things like preferences or login name
    name: wxa                                 # Client cookie name
    expires_years: 30                         # Expires in years. Use decimals for less than 1 year: .25 = 3 months
    secure: true                              # Only send over HTTPS

debug:                                        # How to handle bugs
  level: 9                                    # The level to print to the logs (0 = no debugging, 9 = all debugging)
  on_screen: true                             # Show the error report on the screen (normally for dev mode and maybe staging)
  send_email: false                           # Send an email bug report (normally for production, maybe for staging)
  email:                     # Who to send the email to (This is a bogus address)
  auto_reload_code: true                      # Detect code changes and reload if changed (set to false for production)

databases:                                    # You can have zero or more database connections. Each connection must have a unique name here.
  app: postgresql://waxx@localhost:5432/waxx  # A sample postgres connection string. This connection is available as anywhere in the system.
  blog: sqlite3:///home/waxx/dev/db/blog.db   # An sqlite file db.
  forum: mysql2://waxx@localhost/waxx         # A MySQL or MariaDB connection.

default:                                      # Defaults path info. If path is "/" then the 'index' runner of the App::Website module will be run
  app: website                                # Default module (
  act: index                                  # Default runner (x.act)
  ext: html                                   # Default extension (x.ext). This drived the Content-Type response header too if there is no extension in the path 

smtp:                                         # SMTP settings. Only needed if your app sends email.
  server:                         # Server host name
  user: smtp-user-name                        # Login
  pass: smtp-password                         # Password
  port: 587                                   # Port
  tls: true                                   # TLS (should be true or authentication should not be plain)
  authentication: plain                       # Change for other authentication types

file:                                         # Waxx has a primitive file server for dev puposes if needed
  serve: false                                # Serve files (not recommended for production)
  path: public                                # The path relative to the install directory (Waxx::Root or Conf/:opts/:base)

You can add any other params you want to config.yaml like keys and passwords to third-party services.

All values set here are available system-wide in the Waxx::Conf[] constant or the shorcut Waxx[]. For example these are all equivelant:

  • Waxx::Conf['site']['name']
  • Waxx['site']['name']

Waxx has very few patches to Ruby standard classes. One of them is the Hash#/ method that gets hash values by string or symbol. Think of it as "dividing the hash by key". So the config options are also available like so:

  • Waxx::Conf/:site/:name
  • Waxx/:site/:name

All four options above will return the name of your site.

When you are ready to put your app in production, see Things to change for production Waxx installations