Nanobox Boxfile Configuration
Understanding Boxfile Sections
A Boxfile is the core configuration file for Nanobox applications, defining how your application is built, deployed, and run. It is structured into several key sections, often referred to as "nodes." These nodes allow for granular control over different aspects of your application's lifecycle. The primary sections include run.config, deploy.config, web, worker, and data. Each section serves a specific purpose in managing your application's environment and behavior.
Run Configuration (run.config)
The run.config section is crucial for defining the build, environment, and general configuration for your application's web and worker components. This is where you specify the build engine, runtime environment, directories to be cached, extra packages to install, build triggers, and custom build steps. It ensures that your application is set up correctly before it starts running.
# *****************************************************************************
# SECTIONS OF THE BOXFILE
# *****************************************************************************
# Boxfiles consist of a handful of sections or "nodes": run.config, deploy.config, web, worker, data.
# These are covered in detail in the next few docs, but here are some quick descriptions:
# run.config - Defines the build, environment, and configuration for web and worker components.
# deploy.config - Defines deploy hooks and possible code transformations.
# web - Defines settings unique to each web component.
# worker - Defines settings unique to each worker component.
# data - Defines settings unique to a specific data component.
# *****************************************************************************
# RUN.CONFIG
# https://docs.nanobox.io/boxfile/run-config/
# *****************************************************************************
run.config:
# Engine
engine: engine-name
# Configuration used by the engine
engine.config:
runtime: ruby-2.3
# Contents of these dirs to be cached inside of Nanobox
cache_dirs:
- vendor
- packages
# Extra Packages (in addition to what the engine installs)
extra_packages:
- nodejs
- newrelic
# Dev Packages
dev_packages:
- psutils
# Build Triggers - Changes to these files automatically
# trigger a new build the next time a build is required.
build_triggers:
- Gemfile
- Gemfile.lock
- package.json
# Additions to $PATH
extra_path_dirs:
- vendor/bin
# Custom commands to prepare the environment
extra_steps:
- npm install
# Enable filesystem watcher
fs_watch: true
Deploy Configuration (deploy.config)
The deploy.config section handles the deployment process, including custom commands to prepare the production environment, code transformations, and deployment hooks. You can define commands that run before activation (before_live, before_live_all) and after activation (after_live, after_live_all) for specific components. This section is vital for ensuring a smooth and controlled deployment.
# *****************************************************************************
# DEPLOY.CONFIG
# https://docs.nanobox.io/boxfile/deploy-config/
# *****************************************************************************
deploy.config:
# Custom commands to prepare the production environment
extra_steps:
- mv config-prod.yml config.yml
# Run after your code has been deployed to your live app,
# but before everything is locked down with read-only permissions and distributed into new containers/servers.
transform:
- 'sed -i /HOST/$DATA_DB_HOST/g config/database.xml'
- 'if [ "$ENV" = "prod" ]; then mv config-prod.yml config.yml; fi'
# Run command on any one instance of web.main component before activation
before_live:
web.main:
- 'bundle exec rake clear-cache'
# Run command on all instances of web.main component before activation
before_live_all:
web.main:
- 'bundle exec rake register-nodes'
# Run command on any one instance of web.main component after activation
after_live:
worker.mail:
- 'bundle exec rake prime-cache'
# Run command on all instances of web.main component after activation
after_live_all:
worker.mail:
- 'bundle exec rake prime-local-cache'
# Set a timeout for your deploy hooks
hook_timeout: 300
Web Component Configuration
The web section defines settings specific to your web components. This includes the start and stop commands, current working directory, routing rules, port mappings, network storage configurations, writable directories, custom log watching, and cron jobs. You can also specify if a component should only be provisioned locally.
# *****************************************************************************
# WEB
# https://docs.nanobox.io/boxfile/web/
# *****************************************************************************
web.site:
# Start Command
start: start-command
# Stop Config
stop: stop-command
stop_force: false
stop_timeout: 60
# Current Working Directory
cwd: directory
# Routing
routes:
- 'sub:/path/'
- '/admin/'
# Port Mapping
ports:
- tcp:21:3420
- udp:53:3000
# Network Storage
network_dirs:
data.files:
- path/to/directoryA
- path/to/directoryB
data.unfs:
- path/to/directoryC
# Writable Dirs
writable_dirs:
- path/to/dirA
- path/to/dirB
# Custom Logs
log_watch:
app[error]: /app/path/to/error.log
# Cron
cron:
- id: flush_cache
schedule: '0 0 * * *'
command: rm -rf app/cache/*
- id: echo_msg
schedule: '*/3 */2 1-3 2,6,7 2'
command: echo i\'m a little teapot
# Only provision component locally
local_only: true
Worker Component Configuration
Similar to web components, the worker section allows you to configure settings unique to your worker processes. This includes start and stop commands, working directory, network storage, writable directories, custom log watching, and cron jobs. This enables you to manage background tasks and processing units effectively.
# *****************************************************************************
# WORKER
# https://docs.nanobox.io/boxfile/worker/
# *****************************************************************************
worker.jobs:
# Start Command
start: ruby worker.rb
# Stop Config
stop: stop-command
stop_force: false
stop_timeout: 30
# Current Working Directory
cwd: directory
# Network Storage
network_dirs:
data.storage1:
- path/to/directoryA
- path/to/directoryB
data.storage2:
- path/to/directoryC
# Writable Dirs
writable_dirs:
- path/to/dirA
- path/to/dirB
# Custom Logs
log_watch:
job[error]: /app/path/to/error.log
# Cron
cron:
- id: flush_cache
schedule: '0 0 * * *'
command: rm -rf app/cache/*
- id: echo_msg
schedule: '*/3 */2 1-3 2,6,7 2'
command: echo i\'m a little teapot
# Only provision component locally
local_only: true
Data Component Configuration
The data section is used to define settings for your data components, such as databases. You can specify the Docker image to use, configuration options exposed by that image, and cron jobs for data management tasks like backups. It also allows for the installation of extra packages and custom commands to prepare the environment for data services.
# *****************************************************************************
# DATA
# https://docs.nanobox.io/boxfile/data/
# *****************************************************************************
data.db:
# Image
image: nanobox/mysql:5.6
# Config Options Exposed by the Image
config:
plugins:
- federated
- audit_log
event_scheduler: 'Off'
# Cron
cron:
- id: backup
schedule: '0 0 * * *'
command: 'bash /path/to/scripts/backup.sh'
- id: echo_msg
schedule: '*/3 */2 1-3 2,6,7 2'
command: 'echo i\'m a little teapot'
# Extra Packages (in addition to what the image installs)
extra_packages:
- perl
- curl
# Additions to $PATH
extra_path_dirs:
- /custom/bin
# Custom commands to prepare the environment
extra_steps:
- wget -o /path/to/scripts/cron.sh http://example.com/cron.sh
# Only provision component locally
local_only: true
For more in-depth information on each section and its parameters, refer to the official Nanobox documentation. Understanding these configurations is key to effectively managing your applications with Nanobox.
Explore the official Nanobox documentation for comprehensive details on each configuration option: