threepio

Developer-Environment relations

Asynchronously set up your local environment.

Installation

$ npm i threepio -g

Configuration -- Priority

There are many ways to configure threepio, from a 'global' configuration json file to options passed directly into the commands you run.

The priority of configuration is listed below, from least to greatest priority.

1. The default configuration, as shown below. Additional configuration isn't necessary, but more than likely you'll need a global configuration file.

2. A global JSON configuration dot file in your home directory, ~/.threepio.

3. A local JSON configuration dot file, .threepio, located in your current working directory.

4. Options passed directly into the tasks you run. Available options are listed below. Simply append either a - or -- to the option key, such as $ threepio mysql --database deathstar. See example usage below for more on this configuration method.

Using multiple configuration locations is recommended for a more pleasurable experience as some things may never change, such as your MySQL username/password or vhost directory.

Note: Both the global and local .threepio files are expected to be vanilla JSON.

Options

To make setting up environments easier, threepio leverages Embedded JavaScript templates, or EJS, to make the process more dynamic, which in turn requires less setup and configuration on your part. Include EJS syntax in any option that's a string along with any configuration key as a variable and it will be rendered for you.

Option Key	Default Value	Description
siteName	Your current working directory name (sanitized with special characters replaced with a dash (-) and lowercased)	This is the "name" of your site as it relates to various development components. This name is used to create the local url, database, Apache log names and vhost filename.
localUrl	'<%= siteName %>.local'	This is the name of your local url which is rendered with EJS using siteName as the domain.
baseDirectory	Your current working directory	This value is used to create your VirtualHost directory. **Note**: This value is set separately from siteName. Although they both default to the current working directory, this is the full path and siteName is just the directory name itself.
database	A sanitized version of siteName with special characters replaced with an underscore ('_') and lowercased	The name to give the created database
hostsFile	'/etc/hosts'	The absolute filepath of your hosts file
httpPort	80	The port number used in the opening tag of your VirtualHost conf
vhostsDir	'/etc/apache2/extra/vhosts'	The directory to include a vhost .conf file.
customLog	'/http-logs/<%= siteName %>.log'	The filename and absolute path of your Apache custom log file.
errorLog	'/http-logs/<%= siteName %>.error.log'	The filename and absolute path of your Apache error log file.
mysqlUser	'root'	Your MySQL username
mysqlPw	''	Your MySQL password
apache24	true	When using Apache 2.4, you may experience a 403 when visiting the newly created url. This adds a directive to the vhost that fixes the issue if you do not have it changed in your global `httpd.conf` file.
templateDir	None	The directory to any templates used with this package, such as the template used to create a vhost .conf file.

Sample Configuration Usage

Here are some sample configuration usages going from lowest priority to highest priority in their values.

Method 1: No custom configuration

If you like the defaults, then there's not reason to use any other configuration methods. It is recommended that if you do use a local configuration dot file (.threepio) that be added to your .gitignore since everyone typically has their own local environment style.

Method 2: Global Configuration dot file

This is a file located in your home directory and named .threepio (aka ~/.threepio). This is a plain vanilla JSON file.

{
  "localUrl": "<%= siteName %>.dev",
  "customLog": "/Users/me/www/logs/<%= siteName %>.log",
  "errorLog": "/Users/me/www/logs/<%= siteName %>.error.log",
  "mysqlPw": "the-force-is-strong-with-this-one"
}

Method 3: Local Configuration dot file

"Local" in this instance means a dot file in your current working directory, which is more than likely the repo base directory. This is also vanilla JSON.

{
  "siteName": "r2d2",
  "database": "yavin4"
}

Method 4: Options passed to the cli

These option values are give the highest priority.

$ threepio open hosts --localUrl othersite.local --hostsFile /etc/apache/hosts

Usage 🐓💨

The intended use of threepio is globally. There is no need to add it to your package.json; the global installation should suffice.

A common use case for threepio would be a new Wordpress install. After downloading/cloning a new installation, there are certain things you need to do:

• Create a MySQL database
• Create wp-config.php
• Set up a vhost
• Update your hosts file with your inteded local url
• Rename the theme directory (depending on your typical dev process)
• Restart Apache
• Open that url in the browser and finish the installation

Wow, that's a lot of stuff. Albeit not too difficult or time-consuming, but the process can get a little dry. Enter threepio.

You would use threepio as soon as you downloaded a new WP install or forked and cloned a boilerplate like we do at 40digits. Instead of doing all that, you could set up some simple configuration as mentioned above and run something like this:

$ threepio mysql wp-config hosts vhost wp-theme restart-apache open

This would do everything you need in seconds, saving you some time.

While putting in individual commands isn't too bad, the above example is nearing cumbersome. Instead, you could use a workflow.

Workflows

Using the same Wordpress use case, let's say you've forked and cloned a boilerplate. What if that boilerplate also included threepio.json that had all of those tasks specified? Then you could run

$ sudo threepio

That's it. All that threepio.json file has is a JSON array of the tasks you need to run. Keep in mind that you need to run that command with sudo permissions due to editing the hosts file and resetting Apache.

[
  "mysql",
  "wp-config",
  "hosts",
  "vhost",
  "wp-theme",
  "restart-apache",
  "open"
]

Putting those 95 bytes with the repo would be even simpler.

Workflow Profiles

While using threepio.json is more modular, depending on your development style or habits, you may not need or want to define a separate file for every site you do. If you do a lot of Wordpress development, it would be easier if you had a globally defined Wordpress workflow instead of having to create a threepio.json for every project.

You can define workflow profiles in either the local .threepio or your global ~/.threepio files as an object called workflows. Here's an example:

{
  "localUrl": "<%= siteName %>.dev",
  "customLog": "/Users/user/www/logs/<%= siteName %>.log",
  "errorLog": "/Users/user/www/logs/<%= siteName %>.error.log",
  "workflows": {
    "wp": ["wp-config", "wp-theme"],
    "drupal": ["mysql", "vhost"],
    "laravel": ["mysql"]
  }
}

To run a profile (or chain them together for whatever reason), run:

$ threepio workflow:wp

You can name the profiles whatever you like, but the tasks defined within the profile must exist. You could have a profile named "vader". To run that profile, $ threepio workflow:vader.

Available tasks

Run $ threepio -h or $ threepio --help to see your current installation's available tasks. The idea is that this will be regularly updated, adding more available tasks to make the mundane a little less mundane.

This command will also show you some example usages and what the current configuration settings would be, including your configuration-defined workflow profiles, if you ran a task. This is helpful in case you're not sure if you have everything configured correctly.

Contributing

If you'd like to add a new task, great! Included in the root directory is _task-template.js to help get you started. There are a few requirements for your task to build threepio's vocabulary.

Your task's export must be an object with both a description property (used when $ threepio -h is ran) and a task function (which is where the action is), which has config and a callback from the taskRunner module (which is just a message saying the task is complete).

module.exports = {

  description: 'Your awesome module description here',

  task: function (config, callback) {
    // Your task stuff here
  }
};

Considerations

If the Apache log paths don't exist, you'll get weird behavior. So make sure those are valid paths by ensuring the default are adequete or use a global configuration setting defined in ~/.threepio.