| Staging | Production |
|---|---|
 |
 |
For small-to-mid sized projects - centralize and define:
- development solutions
- best practices
- workflows
- toolsets
From the command line:
$ git clone git@github.com:RayPatterson/project-boilerplate.git; cd project-boilerplate
$ ./setup.sh
After the gem bundling is complete,
Middleman will begin running a server and display something like:
middleman server -p 8888
== The Middleman is loading
== LiveReload is waiting for a browser to connect
== The Middleman is standing watch at http://0.0.0.0:8888
== Inspect your site configuration at http://0.0.0.0:8888/__middleman/
Open you broswer to http://localhost:8888 or run:
$ rake browser:chrome
The browser should display a small set of modules.
INFO
To run the server on a different port: ``` $ rake mm:s[1234] ```
In the interests of segregating the top-level Middleman framework configuration workstream from any related to application development, the source directory is imported from a separate GitHub project.
The default configuration is using the development branch. If you wish to begin your project with another branch run:
$ rake source:change[<branchname>]
Each <branchname> listed expands on the previous one. Current options are:
- minimal - Modernizr and Normalize.css, application bootstrapping
- single-page - Component architecture, Bourbon and Neat, clowncar image, placeholders
- multi-page - Backbone Marionette, Mediaelement.js + YouTube, some carousels
If you don't have rbenv, now's the time to get it.
$ brew update; brew install rbenv ruby-build rbenv-gemset
Homebrew will prompt you to add the following to your .bash_profile.
export RBENV_ROOT=/usr/local/var/rbenv
if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi
In order for rbenv commands to be found you will also need to add the line:
export PATH="$PATH:/usr/local/opt/rbenv/shims:/usr/local/opt/rbenv"
$ mkdir /usr/local/var/rbenv/plugins; git clone https://github.com/sstephenson/rbenv-gem-rehash.git /usr/local/var/rbenv/plugins/rbenv-gem-rehash
$ rbenv install 1.9.3-p247
This will require installing a few things if you want the Favicon Maker and Image Optim extensions to work.
If you don't have Homebrew, God help you. If you do:
$ brew install imagemagick advancecomp gifsicle jhead jpegoptim jpeg optipng pngcrush
Pngout is still in the stone age at the time of writing, so:
- Click here to download the universal Mac binaries.
- Unzip and copy the
pngoutbinary to/usr/bin
Now run:
$ rake mm:build:development
A build directory should appear in the project root.
source Contains all source files that are processed and compiled by Middleman into the build directory.
data Contains YAML files used to define parameters for Rake tasks and Middleman template data.
lib Contains all Rake tasks. Some can be used for any project, however some have very specific uses and require configuration.
INFO
Not sure what these [dotfiles](http://dotfiles.github.io/) and configs do?
Don't worry, it's safe to leave them in your project.
######Important
- .gitignore - If you find some of your files or folders are not being committed, check this file to see if they are being ignored. Chances are you don't need to version them.
- .ruby-version - Specifies Ruby version for rbenv (recommended) or RVM (legacy).
- Gemfile - Used by Bundler to define Ruby gem dependencies.
Gemfile.lockis generated from this file and should not be edited directly. - config.rb - The Middleman configuration file. Activates and configures Middlman extensions.
######Miscellaneous
- Rakefile - Requires all Rake tasks inside
lib/tasksfolder. - .editorconfig - Editor config.
- .jsbeautifyrc - For use with jsFormat Sublime Text plugin.
- .rbenv-gemsets - Specifies Gemset name for rbenv Gemset plugin.
This is a configured Middleman project. The project utilizes MM to "build" or "compile" the code base for deployment. Commands have been wrapped in Rake tasks to target development and production build types.
The data folder contains some externalized data that is used by Middleman in config.rb, some of the deployment tasks in lib/tasks and can also be read directly into Middleman templates though the data object.
The Middleman config.rb can also be used to pass the values from data/config.yaml into the application templates. An example of this can be seen in source/assets/js/app.js where the helper <%= build_version %> is used to assigned the build version ID to a JavaScript variable.
INFO
In [Sprockets](https://github.com/sstephenson/sprockets), files can be converted to multiple types by multiple processing engines during compiling routine. The order is dictated by the chaining of file extensions. The process for the default Middleman [templating](http://middlemanapp.com/templates/) is explained [here](https://github.com/sstephenson/sprockets#invoking-ruby-with-erb) but in short, if you add the `.erb` extension to any file, you can write Ruby in it access the data object as well as Middleman [Template Helpers](http://middlemanapp.com/helpers/).
There are currently 4 types of builds to support a variety of workstreams and approval processes:
| Environment | Audience | Task |
|---|---|---|
| Production | User | $ rake mm:build:production |
| Staging | Tester | $ rake mm:build:staging |
| Review | Stakeholder | $ rake mm:build:review |
| Development | Developer | $ rake mm:build:development |
Activating deployments and their repective targets is configured in: data/project/deployment.yml
Available build targets are:
The option to deploy review builds to Heroku with basic auth is forthcoming.
By default, the development build is configured to automatically deploy to GitHub Pages.
INFO
Setting up [S3](http://aws.amazon.com/s3/) origin buckets and corresponding [CloudFront](http://aws.amazon.com/cloudfront/) CDN distributions is currently beyond the scope of this documentation.
AWS is configured in: data/project/aws.yml
staging:
region: "us-west-1" # S3 bucket region
bucket: "project-boilerplate-staging" # S3 bucket name
subdomain: "d3j8fwmkh3oq8e" # CloudFront subdomain
distribution_id: "E36OCSKSYBD2LH" # CloudFront distribution id
Deployment is configured in: data/project/deployment.yml
staging:
active: false # Activates deployment process
target: "aws" # Defines deploy target
INFO
Setting up [Travis CI](https://travis-ci.org/RayPatterson/project-boilerplate/) is currently beyond the scope of this documentation.
Pushing to either the staging or production branches will trigger Travis to perform a build and deploy.
Encypting your AWS keys:
$ travis encrypt S3_ACCESS_KEY_ID=AKQA… --add env.global
$ travis encrypt S3_SECRET_KEY_ID=SHHH… --add env.global
Replace the the secure keys in: .travis.yml
env:
global:
- secure: m7ET...
- secure: Nr2R…
INFO
When the site debugging flag is `true` the Travis build number will be visible within the console.
E.g. `Build Version --> 99`
Versioning is configured in: data/project/deployment.yml
staging:
increment: true # Increments the build version
The build version ID will be visible in the console.
E.g. Build Version --> v0099
The build can be manually versioned with:
$ rake version:increment
Tagging is configured in: data/project/deployment.yml
production:
tag: true # Activates tagging process
message: "Today is the day" # Optional Message
The build can be manually tagged with:
$ rake version:tag
Then push with the following:
$ git push --tags
The relationships between desktop/tablet/mobile apps for each environment are set within the data/config.yaml file.
INFO
In both the middleware and client-side soltions, Android tablets are treated the same as Android mobile devices.
If the redirect needs to rely on JavaScript you may follow these steps:
- Open
source/assets/js/lib/redirect/redirect.js - Replace "REDIRECT-URL-{DEVICE}" with the appropriate redirect URL's.
- Replace "REDIRECT-SEARCH-PATTERN" with the appropriate search patterns.
- Optionally replace "REDIRECT-URL-IGNORE" if you want to bypass the redirect on specific URL's.
- If you are running on a local port other than "8888" replace as necessary.
- Embed this file into the tag of
source\index.html.erb.
INFO
Once the redirects have been verified, it's recommended for optimial performance that you minify this script and replace the embed of the external file and copy the minified code block into the script tags.
If you are deploying to a hosting service such as Heroku that supports Rack middleware, you may use a middleware based solution.
The current solution in place is https://github.com/talison/rack-mobile-detect
There is some additional configuration that can take place within the Rack config config.ru file.