Machete: Hack together an API Blueprint Workflow Generator

This generator will create a vagrant box configuration, clone in a base box config, and a base api blueprint. This is a development workflow for a Service Oriented Architecture

First you should cache the box on your local machine by running:

vagrant box add camdesigns/basebox

To install generator-machete from npm, run:

npm install -g generator-machete

This may not be recommended, but I did it:

This will allow the generator to modify your hosts file for you. Otherwise, edit your /etc/hosts file as recommended by the generator each time, this will allow all of the virtual hosts to render properly via nginx.

sudo chown <username> /etc/hosts

Initiate the generator:

yo machete

Initiate the Parser Sub Generator [ALPHA]: (Eventualy will pass to adapter sub generators for: laravel, sails, angular, etc. )

This will follow the convention to find the resource eg. (../base-api-blueprint/users.md)

yo machete:parse users --sails-api --angular

The VM should be running or you can run vagrant up from the base-box dir

• you can now ssh is and work with your project
• base.dev api.base.dev .. etc. are now all available URLs

Requirements

• vagrant 1.6.3+
• virtualbox 4.3.14+

The Conventions established will create a directory structure similar to this:

base-box
│   README.md
│   machete.yaml (symlinked to base-box-config/machete.yaml)
│
└─── base-box-config (implementation of the box)
|        |    machete.yaml
|        |    readme.md
|        └─── nginx (server configuration)
|           |    base.conf
|           |    base.api.conf
|
└─── base-api-blueprint (the API Blueprint)
|       |     README.md
|       |     template.txt (used for scripting that will come later)
|       └───  resources
|             |     users.md
|
└─── base-api (your api implementation)
└─── base-ui (you ui implementation)
└─── tools (server tooling / monitoring and ui)
        └─── beanstalkd
        └─── genghis
        └─── opcache
        └─── test

Box definition ( Ubuntu 14.04 )

• https://vagrantcloud.com/camdesigns/boxes/basebox

Troubleshooting

• Ports 3306 and 27017 will be forwarded on the VM to the host machine to allow for Mongo and MySQL connections
• ensure you have a ~/.ssh/id_rsa key or remap the key in the machete.yaml file
• screens will be running in sudo so to see what servers / processes are running try sudo screen -ls (get familiar with screens if you are not already)

Workflow

• In the base-box-config directory you can script your box to do all the things you need (add / configure packages, add scripts for seeding, migration, etc. so your ENV si fully reproducible everytime)
• In the base-api-blueprint Define your API following the standards in http://apiblueprint.org/
• In the subsequent base-? directories implement your APIs and SPAs as needed.
• https://www.npmjs.org/package/api-mock will be running the initial mock server at mock.base.dev
• https://www.npmjs.org/package/aglio will be running the initial docs server at docs.base.dev
• npm install dredd is availbe for api testing
• go HAM

Contributing

• Request Access to Gitlab [email protected] or #sdphp IRC @camdesigns or twitter @camdesigns
• Fork the Repo
• Create branch name thusly: /
• Submit Merge Request (MR) tagged with [WIP] Immediately
• Comment in the Merge Request "Fixes #"
• Merge will happen after Code Review