kaplan/middleman_dev_approaches.md

## middleman_dev_approaches.md

      
    Raw
  

              middleman_dev_approaches.md
            
          
    Middleman Local Dev Approaches

Update 03-03-2015

I've moved over to a new MacBookPro running 10.10.2. I think I'm going to leave POW off this machine. I've been trying to use more Vagrant VMs in general, but the Localhost is so fast for just getting something in the browser, especially when testing things out on the front end in the browser. One thing I'm noticing about the 2nd approach is that the build with a vhost works great, but just getting the .git setup was a little tricky. I had to make the main directory, the build directory and git init in each. Then, I added the remotes from the working (development) repository for the source and the staging server repo for the build. Looks like I might install Passenger on this new machine so that I can use a vhost for the source files. Otherwise I need to use the http://0.0.0.0:4567/ or http://localhost:4567/ which isn't a bad thing vs installing Passenger?
Udpate 03-03-2015

Wow, just installed Phusion Passenger in about 15min using the guide and the RubyGem version

I’m using a Mac running OS X 10.9. I’ve tried a couple different ways to serve Middleman projects locally as I work on them. Middleman is built to generate static sites, but I like to start the  middleman server for the source, then I can play around, see changes (using live reload), view on a few browsers, and when I'm ready I middleman build. Then I do a little more testing before I upload.
(I'm really only on my first real middlman project, so there’s still tons to learn. I’m also new to Ruby. And I'm usually wrong the first time around so any tips or corrections are welcomed.)

Approach 1: Source and Build both use Pow
Approach 2: Source uses middleman server and a port. Build uses a vhost
Source and Build both use Apache and Passenger

In all 3 approaches you can test what your making on other devices by using xip.io. In the example code you’ll see a local IP with .xip.io and that allows me to view on an iPhone or the super old HP box in my little office.

1.0 Source and Build both use Pow

The basic idea is to symlink the source folder in ~/.pow. The symlink (mmapp1) determines the hostname (mmapp1.dev) to access the middleman source ~/Projects/mm_app1. Visit http://mmapp1.dev to see the source.
This approach doesn’t require the use of middleman server to start up the site or app. This approach doesn’t require a servername vhost setup in /etc/apache2/extra/httpd-vhosts.conf or hostname setup in the /etc/hosts. The Pow manual will give you all the details. The Pow site also has a nice video showing how easy it is to use. If you want to run Apache alongside Pow, you can find out how at Running Pow with Apache you can do that.
Getting Started

Make a default middleman project directory with a config.ru file
$ middleman init mm_app1 --rack
A couple of things I found out while trying this approach:

It seems like activate :livereload doesn’t work with the Pow approach.
Instead of livereload, there needed to use a tmp/always_restart.txt to see any changes.
Using always_restart.txt has a slight delay in my starting the source.
If you don't use always_restart you can touch tmp/restart.text or use the Activity Monitor to stop/start Pow.
Pow requires a public folder to serve static files.
Middleman makes a build folder for static, but you can set :build_dir, 'build/public' in the config.rb
If you add a public directory you can symlink to build in ~/.pow and it finds the public folder
You can use xip.io with this approach http://mmapp1.10.0.1.129.xip.io/

1.1 Symlink to source in ~/.pow

Setup a symlink with Pow and use that host address for Source (current working state)
$ cd ~/.pow
$ ln -s ~/Projects/mm_app1 mmapp1
$ open http://mmapp1.dev

# See it from another device on your network (use your local IP, mine was 10.0.1.129)
$ open http://mmapp1.10.0.1.129.xip.io/

1.2 No livereload, make it restart

Because I couldn't get livereload working I added a tmp directory and a restart.txt or always_restart.txt file to the project. It seems like there is a small delay to the page load with a restart. This is sort of a bummer, that delay during the restart could start to be a hassle.
$ cd ~/Sites/mm_app1
$ mkdir tmp
$ touch tmp/restart.txt  

# or always_restart is another way to force a reload
$ touch tmp/always_restart.txt

1.3 Symlink to build in ~/.pow

Pow can serve static files (like the ones in the build without a config.ru), but the directory needs to be named ‘public’. Middleman compiles to a directory named ‘build’ so in the mmapp1/config.rb add a public dir to the build directory set :build_dir, 'build/public'. Now when you build the static files are compliled into the public directory and Pow will serve them.
# in the /mmapp1/config.rb
set :build_dir, 'build/public'  

# in the shell
$ cd ~/.pow
$ ln -s ~/Projects/mm_app1/build mmapp1.build

$ cd ~/Projects/mm_app1
$ middleman build

# View the compiled static site-app 
$ open http://mmapp1.build.dev

# See it from another device on your network (use your local IP, mine was 10.0.1.129)
$ open http://mmapp1.build.10.0.1.129.xip.io/


2.0 Source uses middleman server. Build uses Apache vhost.

This approach seems nearest to Middleman’s Development Cycle. From the project folder, in the shell do middleman server and browse to the localhost with the port where you can see the source. To play around and see changes to source files, turn on activate :livereload. This approach also works well with .xip.io for viewing the site-app from local devices.
Do middleman build in the shell to compile. To view the build in a browser this approach adds a virtual host that points to that build directory.
A couple of things I found out while trying this approach:

This is a great approach for quick reloading of changes to the source.
Using a vhost for the build makes reviewing compiled version easy.
Works great with .xip.io for both source and build to view on devices within the network.

Getting Started

Make a default middleman project, doesn't seem like this approach needs to have --rack
$ cd ~/Projects/
$ middleman init mm_app2

2.1 Start the Middleman Server for Source

$ cd ~/Projects/mm_app2
# start the middleman server
$ middleman server (give a port with -p if you want)

# View the source on your local machine 
http://localhost:4567/

Depending on the server settings, you should be able to see the source at http://localhost:4567/
# or using a device on the local network 
# at the time my IP was 10.0.1.129, you can find yours in the System Preferences/Network
http://10.0.1.129.xip.io:4567/

2.2 Compile Source to Build

From the project directory in a shell
$ cd ~/Projects/mm_app2
$ middleman build

2.3 Set up a hostname and vhost for the compiled Build

Use your favorite editor and add the nameserver to the /etc/hosts file. (I’m using Sublime Text 2). I'm still a little hazy on this hosts vs directory settings, I swear I've left out the hostname from /etc/hosts and it worked, but idk, I just played around with refreshing and restart apache to see what works. It seems like adding the ServerName to the /etc/hosts definitely works whether or not there are <Directory> settings in the vhosts.conf
One thing to note, is the ServerAlias has .xip.io added to it. I've also used a * instead of including my current IP and that worked too (ServerAlias mmapp2.build.*.xip.io). Adding xip.io here will make it so you can see the compiled build from devices in the local network.
$ subl /etc/apache/extra/httpd-vhosts.conf

<VirtualHost *:80>
    ServerName mmapp2.build
    DocumentRoot /Users/davekaplan/Projects/mm_app2/build
    ServerAlias mmapp2.build.10.0.1.129.xip.io
</VirtualHost>

$ subl /etc/hosts
127.0.0.1 mmapp2.build

# restart the apache server
$ sudo apachectl restart

# See the build at:
$ open http://mmapp2.build/

Using .xip.io in the domain, you can view the compiled build from a device within your network.
http://mmapp2.build.10.0.1.129.xip.io/

3.0 Source and Build served from Apache and Phusion Passenger

A lot like the Pow approach, this approach uses Phusion Passenger, with a vhost setting, to serve the source files and then an Apache vhost setting to serve the compiled build.
Note: This was the first time I setup Passenger and it wasn't too bad. I'm using RVM on the machine I used for these examples. There are some good examples to get up and running with Passenger. Once passenger is working, using it for Middleman should work too. (to do: Add my super distilled Passenger notes link here.)
A couple of things I found out while trying this approach:

You need a ~/Projects/mm_app3/public directory to make Passenger work. I left it empty.
Needs a mm_app3/tmp/restart.txt file to reload changes, but feels a little faster than Pow (?).
I thought it worked with activate :livereload, but I don't think so, seems like it did then it didn't.
Need to point the source vhost to the public folder, which was empty in my example.
Using a vhost for the build makes reviewing compiled version easy.
Works great with .xip.io for both source and build to view on devices within the network.

Getting Started

Make a default middleman project directory with a config.ru file
$ middleman init mm_app3 --rack
3.1 Compile Source to Build

From the project directory in a shell
$ cd ~/Projects/mm_app3
$ middleman build

3.1 Set up a vhosts for source and build

$ subl /etc/apache/extra/httpd-vhosts.conf

# inside httpd-vhosts.conf
# I used .loc instead of .dev so not to confuse myself with Pow
# Pointing to the empty public folder in the project to make Passenger work with Source files.

<VirtualHost *:80>
    ServerName mm_passenger.loc
    DocumentRoot "/Users/davekaplan/Projects/mm_app3/public/"
    <Directory "/Users/davekaplan/Projects/mm_app3/public">
        AllowOverride all
        Options -MultiViews
        Order allow,deny
        Allow from all
    </Directory>
</VirtualHost>


<VirtualHost *:80>
    ServerName mmapp3.build
    DocumentRoot "/Users/davekaplan/Projects/mm_app3/build/"
    <Directory "/Users/davekaplan/Projects/mm_app3/build/">
        AllowOverride all
        Options -MultiViews
        Order allow,deny
        Allow from all
    </Directory>
</VirtualHost>

3.1 Set up a hostnames for source and build in /etc/hosts

Add the ServerNames to the /ect/hosts file.
$ subl /etc/hosts
# I used .loc for the source so that it didn’t get weird with Pow, 
# I think something happens when Pow is running too.
127.0.0.1 mmapp3.loc
127.0.0.1 mmapp3.build

# View the source development:
$ open http://mmapp3.loc/

# View the compiled build:
$ open http://mmapp3.build/

# Works with xip.io too for source and build
http://mmapp3.loc.10.0.1.129.xip.io/
http://mmapp3.build.10.0.1.129.xip.io/

It’s like Pow. You can restart the app by having a tmp/restart.txt
I thought it worked with livereload activated, but I'm not sure.
or restart in shell $ touch tmp/restart.txt
Overall it seems like the (#2) Build with Middleman Development Cycle, a vhost for the build along with .xip.io are the best. It's fun to play around with other approaches. This was a great way to learn about Pow and Passenger, get more comfortable in the shell, and explore that idea of seeing a couple paths and trying them all when time allows.