March 08, 2015

Posted by Sherri Flemings | File under : , , , , , ,
Install Laravel Homestead 2.0 on Windows
I've tried to set up Laravel's Homestead on Windows a few times before. Until now I always gave up because I just ran out of time trying to troubleshoot one error after another on both of my Windows machines. The Homestead setup guide and Laracast videos make it look so freaking easy, but they are not targeting Windows users so it sometimes becomes a very frustrating experience for us... and usually ends with reverting back to your XAMPP or WAMP installation and a promise to try again when you have more time.

I finally had some time to try this again, and although there were a lot of steps and some annoying errors it was actually pretty easy to get going! I know there are some web devs out there who might be intimidated using a command-line, or a virtual machine and some of the error messages you get might have you feeling like you're in way over your head but I wanted to break it down here for you step by step and explain some of the errors to help you get over the initial hurdle of installing Homestead on your Windows machine.

Warning - Before you begin you should verify in your system's BIOS that Intel Virtualization Technology is enabled. It will save you some troubleshooting time if you check now before you get started.

My goal is to install and setup Laravel 5 and Homestead 2.0 on my Windows 8.1 machine. I will be following the same steps on the Laravel install page,  but I will change the paths for Windows and share any errors I came across.

Dependencies:

Before we start make sure you have installed the following software:

Before you install Vagrant - Vagrant uses Ruby, and there is a known issue with Ruby and spaces in paths. My very first mistake was to change the Vagrant install location to %ProgramFiles% like a good Windows citizen and that was a spectacular failure. I opted to install it here on my machine: C:\Tools\Vagrant. I just do my best not to cringe when I see that clutter in the root of my system drive.

Step 1: Open Git Bash

I highly recommend that you use Git Bash as your command-line for the following steps since it will allow us to enter the same commands in the docs without having to manually edit files. If you are also planning to install the vagrant hostsupdater plugin, make sure you open Git Bash as an administrator:


Step 2: Add Vagrant Box

Verify that you have the recommended Vagrant version for Homestead which at the time of this post was Vagrant 1.6

Git Bash

$ vagrant version

Add the Laravel Homestead Box to Vagrant

Git Bash

$ vagrant box add laravel/homestead

This will take several minutes so feel free to grab a coffee or a sandwich depending on your Internet speed.

Step 3: Install HostsUpdater plugin (optional)

The hostsupdater plugin will save you from having to manually update your hosts when you add a new site to your homestead box. Since the Windows hosts file is protected you'll need to make sure you're running Git Bash as an admin (it's not really necessary to be running as admin during this step, but later when you start your homestead box).

Git Bash

$ vagrant plugin install vagrant-hostsupdater

Step 4: Install Homestead

Help: you will see references to your "home" directory, or "~" (tilde) within the Laravel docs. This is *nix vocabulary, the Windows equivalent is the user home path, or the env vars %HOMEDRIVE%%HOMEPATH%. If you are using Git Bash ~ (tilde) maps to the correct directory, however if you're using Windows cmd prompt you should use the above ENV vars to navigate to the home directory.

If you don't have PHP installed on your computer, go to Option 1, otherwise go to Option 2. I recommend Option 1 for most Windows users.

Option 1: You don't have PHP installed on your windows machine

This option assumes you have git installed and already working on your Windows machine. 

Git Bash

# ~ should take you to Windows User Home, %HOMEDRIVE%%HOMEPATH%
# typically it's C:\Users\{username}
$ cd ~
# Copy Homestead into: C:\Users\{username}\Homestead
$ git clone https://github.com/laravel/homestead.git Homestead
    

Once Homestead is installed we'll create the Homestead.yaml configuration file:

Git Bash

# go to the Homestead installation directory
$ cd ~/Homestead
# initialize Homestead configuration file
$ bash init.sh
    

Help - if something goes wrong, or for some reason you're not using Git Bash, you can just copy the files manually. From: C:\Users\{username}\Homestead\src\stubs  to  C:\Users\{username}\.homestead

More Help - You will see references in the docs to homestead commands like homestead init, homestead edit and homestead up. These commands will not be available if you install Homestead from git (Option 1). It's not a big issue, since most of the commands are just wrapping vagrant functionality or providing a shortcut to open the Homestead configuration file in your text editor. I wanted to point this out though since there tends to be some confusion with this.

Go to Step 5

Option 2: You have PHP and Composer already installed

This option will allow you to install the Homestead CLI which provides convenience commands like homestead init or homestead up. If you already have PHP and Composer installed and working on your Windows machine this might be a good option for you, however if you don't already have them installed I strongly recommend following Option 1 above to install Homestead.

Git Bash

$ composer global require "laravel/homestead=~2.0"

To take advantage of the Homestead CLI, make sure to add the Composer /bin directory to your PATH

Help - On Windows you can find the Composer /bin inside your AppData directory: %HOMEDRIVE%%APPDATA% typically this maps to C:\Users\{username}\AppData\Roaming

Git Bash

# initialize Homestead configuration file
$ homestead init

Help - if something goes wrong, or for some reason you're not using Git Bash, you can just copy the files manually. From: C:\Users\{username}\AppData\Roaming\Composer\vendor\laravel\homestead\src\stubs  to  C:\Users\{username}\.homestead

More Help - Although I installed the Homestead CLI using Composer, I actually never use the homestead commands, instead I use the vagrant commands. I just find it less confusing since I have some other vagrant boxes setup now too.

Go to Step 5

Step 5: Generate your SSH Keys

If you are using git, you probably don't need this step. I prefer to use a different SSH key for different tools, so I'm not re-using my git keys for this step. 

My SSH client of choice is Bitvise Tunnelier, and managing keys is super easy with the Keypair Manager included with this client. You can open it by typing 'keypair' into your Windows Start Menu search, or if you have the Bitvise client open you can select the 'User keypair Manager' link on the Login tab.

Run Keypair Manager from Start Menu
Run Keypair Manager from the Bitvise SSH client

After your keys are generated, you can export your public & private keys in OpenSSH format. I exported my keys as homestead_rsa.pub and homestead_rsa.

Export your public and private keys to your .ssh folder

Step 6: Configure your Homestead Box

If you installed the HostsUpdater plugin, you'll need to edit the homestead.rb file  and add an aliases section to your Homestead.yaml file.

%APPDATA%\Composer\vendor\laravel\homestead\scripts\homestead.rb

# Configure A Private Network IP
 ...
# ADD THE NEXT LINE TO CONFIGURE HOSTSUPDATER PLUGIN
config.hostsupdater.aliases = settings["aliases"]
    

Configure your Homestead.yaml file for your environment. Mine looks like this :

%HOMEPATH%\.homestead\Homestead.yaml

---
ip: "192.168.10.10"
memory: 2048
cpus: 1
provider: virtualbox

authorize: ~/.ssh/homestead_rsa.pub

keys:
    - ~/.ssh/homestead_rsa

aliases: ["laravel.app", "stitchcrafter.api"]

folders:
    - map: D:\Data\Code
      to: /home/vagrant/Code

sites:
    - map: laravel.app
      to: /home/vagrant/Code/Laravel/public
    - map: stitchcrafter.api
      to: /home/vagrant/Code/StitchCrafterAPI/public

databases:
    - homestead

variables:
    - key: APP_ENV
      value: local
    

A note about paths - You will notice that I am using the ~ (tilde) character to refer to my Windows HomePath. This should work for you and if you're sharing with a team this is the recommended approach. If you're a lone developer you can stick to hard-coded path if that's what you prefer C:\Users\{username}\.ssh

Ideally I would prefer to stick to the Windows env vars and use %HOMEDRIVE%%HOMEPATH% instead of the ~. Why? Because I don't know if ~ will also work on my Windows machines where the HomePath is not on C drive. Unfortunately Windows env vars are not currently supported.

Step 7: Launch it

So... this is where things sometimes start to unravel, hopefully I can help you get past the error messages so you can get your vagrant homestead box up and running.

A note about the different installation options - cd ~/Homestead will only work if you installed Homestead using git in your home path (Option 1). If you installed it using composer, you can call homestead up without having to be inside the Homestead folder (as long as composer\vendor\bin is part of your PATH). Otherwise you'll have to cd into that long path. In the steps below I follow the path less travelled and use the commands for a Git installation, if you installed with composer please use the commands recommended for that installation type.

Help - Some people are having trouble getting the homestead commands to work properly after installing with composer (Option 2). This is usually a result of not adding composer bin to your PATH. If you prefer to not add it to your path and you're using Git Bash you can take advantage of it and create a .bashrc file in your home path to create an alias (just change the Windows \ to / in the path)

C:\Users\{Username}\.bashrc

alias hs="cd C:/Users/{Username}/AppData/Roaming/Composer/vendor/laravel/homestead"

Now you can just use the hs command to get to the Homestead directory in a composer installation (if you need to).

OK. Let's get this box up and running now...

Git Bash

$ cd ~/Homestead
$ vagrant up

First Error: The first attempt got stuck and kept repeating this error line:
Error: Connection timeout. Retrying...

I opened the VirtualBox GUI to try running the Homestead box from there. This is where I saw what was actually happening. The error popup was helpful, the message started with  VT-x/AMD-V hardware acceleration is not available on your system...

If you see a similar error you will need to enable Intel Virtualization Technology in your BIOS settings. A bit of googling should help you find out how to do that for your specific motherboard.

After enabling virtualization I tried vagrant up again...

Second Error: 
This might look familiar:

Error: Connection timeout. Retrying...

Wait, that's the same error again? I double checked my Homestead.yaml file and realized the path to my private key was wrong.

After correcting my SSH key path I tried vagrant up again...

Third Error: 
... found a tab character that violate intendation while scanning a plain scalar
at line ...

Despite the spelling error (indentation) this error message is fairly obvious. I opened Homestead.yaml in Notepad++ and turned on whitespace and tabs then converted the tabs into spaces.

Alright, now we're good to go! Let's try this again...  vagrant up ...

Oh... what? Another error! Are you kidding me???

Another Error:
.../HostsUpdater.rb 'initialize': Permission denied - C:/Windows.system32/drivers/etc/hosts (Errno::EACCES) ...

You will see this error message if you installed the HostsUpdater plugin and aren't running GitBash as administrator.

Close GitBash and 'run as administrator'...

Git Bash

$ cd ~/Homestead
$ vagrant up

After a minute or so I finally see the words: Machine booted and ready!
Let's SSH in to make sure it's set up properly. I prefer to use the Bitvise SSH console, so as a test I logged in and looked around:

Copy/paste the Host and Port values from the vagrant startup sequence in your console. Above I was verifying that my default Laravel installation was mapped properly.

Step 8: Test your site

If all goes well you should now be able to open a web browser and see your site. My first sites entry looks like this:

Homestead.yaml

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Laravel/public

Let's see if this is working ... I type http://homestead.app in the browser ...

Success!!!

So, was all of this worth it? I think so! Honestly, I doubt I'll get much use out of the Homestead box because it doesn't really mirror my actual server environment, but after dealing with the errors and configuration issues I've become much more confident using Vagrant and VirtualBox. Now I'm setting up my own custom Vagrant box which mirrors my live server environment ... I use virtual machines for mobile and game dev all the time and I'm so excited that I finally took the time to get this working for my web dev environments too.

I hope this helps some wandering Windows user out there. If it does, let me know. I would also like to give a HUGE thanks to Github User Terre Porter whose Laravel.IO thread helped me fill in a few missing pieces and introduced me to the awesome hostsupdater plugin for Vagrant.

Check out this thread on Laracasts for any errors or updates that haven't made it into this post yet: https://laracasts.com/discuss/channels/tips/guide-to-install-homestead-2-on-windows-8

I would also recommend getting familiar with Vagrant commands and don't be afraid to open up some of the Homestead scripts and Homestead source files to poke around and understand what's happening under the hood.

Next up, I'll be integrating this into my Grunt workflow...

September 08, 2014

Posted by Sherri Flemings | File under : , , ,
I just discovered this nifty little tool to generate the API docs for Stitchcrafter. It's called apiDoc, and I had it integrated into my grunt build in a few minutes. 30 minutes later, I had my existing docblocks converted to the custom @api tags, and now I have a nice looking document for my API.
Screenshot of my first API document using the default template
There are a few issues I've noticed, but they're only minor, and compared to other tools I've tried in this category it has the best out-of-the-box results so far. I may end up forking this to address these issues and help keep this project awesome :)

My favourite bits:

  • very easy to integrate into any project 
  • the version compare feature
  • modern clean look as the default template
  • open source with the ability to create your own custom tag parsers
Response examples are automatically grouped into a tabbed pane with the default template.


Minor Issues:

  • It assumes error messages are 4XX (I may be able to fix this with a custom template)
  • I'd like to automate the endpoint versioning, I don't like the idea of always having to manually add/update the version with each code update. (This is something I may be able to set up using the grunt preprocess task though)
  • The ability to easily add documentation that isn't for an endpoint. Since all my error objects are the same shape, I wanted to group them under an 'Errors' heading. I managed to fudge it for now using the @api tags, but the template tries to format it as if it had a url endpoint. I think I can probably just create my own parser for this as well.

I haven't spent much time using it yet, but I think this is my new goto API generator. You can dig into it here:
Happy documenting :)

September 05, 2014

Posted by Sherri Flemings | File under : , , , , , , , , , ,
Please kids, don't try this at home!

Actually, you SHOULD try this. It was so much fun, even if it it didn't turn out quite the way I wanted, it did turn out to be one of the coolest birthday gifts I've made so far, for the coolest dude I know. I will try to overlook the horrendous event horizon of gross fluff that still haunts me and threw a dark shadow over my love for this cake and share the making of the most epic cake I've made so far.


I threw myself into this project. We talked about nothing else for about 2 weeks. Unfortunately I can't seem to find the original sketch, but our cake brainstorming went something like this:
J: Hey babe, I think I'd like a Stargate cake this year.
S: Cool. That might be tricky, but I think I can do it.
S: Oh man! What if we could have a tardis coming out of the stargate?
J: And spock!
S: Oh, and we could put a jaws fin in there too... we should keep it simple, and that's funny.
J: Maybe a sandworm too? That might be easy.
S: We could have the wicked witch of the east's feet sticking out of the bottom of the cake. That would be awesome.
It went on like this for a while, basically until there was waaaaay too much to fit on one cake.

After re-reading some of my cake decorating books, and blogs and you-tubing a whack of how-to's I set out on the main attraction, the TARDIS topper. I created a template that would fit within the cake and stargate measurements and stand about 4 inches tall.
12 pieces of hand cut and painted fondant. I didn't have a square cutter, so these panels took longer than I'd care to admit. The wood grain effect was created by dragging a modelling tool around the surface until it looked like wood.
I icing-glued the panels to a super squished compact GF rice cereal treat I made. It was tough to get it even, especially since I goofed and made all the panels the same size. I think they would have fit better if I made the 2 sides a bit smaller than the front and back pieces. I sculpted the door hardware and the lantern on top, the signage is courtesy of our printer.
I was really happy with how this turned out, even with the mistakes. I could have stopped here, and plopped this on any old cake and it would have been just fine... but Sherri doesn't stop at 'just fine'. I'll scrounge up the Lego figures in progress and add another post about them soon.

Just in case soon turns into 'not soon', here's a shot of the finished cake.
Did I mention it was gluten free? 

June 24, 2014

Posted by Sherri Flemings | File under : , ,
So, I got an email a few weeks ago from a total stranger asking if he could find Backronym Hero out in the wild. I was shocked to discover that anyone besides a few friends and family read this, and then I felt bad for neglecting my blog for so long! In my defense, it has been a crazy year, moving across Canada... again, 3 job changes, saying goodbye to my sweet little kitty after 17 years and did I mention all that moving and driving and job changing?

So what is the deal with Backronym Hero? Well, I have a super buggy alpha version that I haven't touched since last July. Chances are I may not get back to it for quite a while since my current priorities are steering me away from Flash, and away from games (for now)... GASP!

I've been very focused on another project that has been consuming most of my free time, and I'm also coding in PHP and javascript again, and surprisingly I'm loving it. I was investigating technologies to use for this new project, and I was purposely ignoring PHP since I had grown very tired of Zend, CodeIgniter and my beloved Yii. I was intrigued by Node.js, the thought of being able to use the same language for the back-end as well as the front-end is very appealing. I definitely enjoy working with node, but it wasn't a good fit for this particular project. Next, I went down the java road, then .net... and in both cases I found them to be cost-prohibitive. So, after struggling through the unpleasantness of working in PHP again I stumbled across a mention of Laravel (in a Yii forum actually).

I was definitely skeptical at first, since I've been bitten by PHP frameworks before, but I have to say that after working with it for about 6 months it really is a great framework to work with. I typically build my web apps so the server layer is just an api, I don't like to build my web pages with server code. A lot of my frustration comes from trying to separate out the view stuff from the server stuff. So far, it's been very easy to build my web apps the way I actually want to with Laravel. In addition to Laravel, the web has really matured in the past 2 years with a lot of great tooling. I seriously haven't been this excited to do web stuff in quite a few years.

Aaaaaanywaaaay, now that I'm settled into the new city, home and job I have a bunch of draft posts waiting to be edited, talking about a lot of the new tools I've been playing with, and this awesome project I'm working on. Until I get around to editing and publishing them, if you find yourself in pain PHP development hell, you should totally check out Laravel. I've also subscribed to Laracasts, I think it's well worth the price.


May 12, 2013

Posted by Sherri Flemings | File under : , , , ,
Backronym Hero coming to a web page near you
I've been spending a lot of free time these days working on a game (for me... for a change). It's almost ready to share. YAY! I've even somehow managed to convince +Jordan to code the multiplayer and game logic for me :)

It's inspired by Acrophobia, my favourite word game of the 90's. I've searched for versions of it online and on my phone but the only one I could actually play was extremely buggy. Why not make my own? Sure! It's great to work on games you truly love playing, and I get to brush up on my uber rusty UI design skills.


I've modernized it a fair bit and was inspired by the retro comic book style, I'm so excited to see it starting to come to life. I'm not an artist, I enjoy drawing and designing, but I really struggle with getting what's in my head down on paper, or on the screen in this case, so I've been trying to practice getting the outcome I envision. (I'm sure there's an artistic term for that) I decided to simplify the theme, to help make it an easier target for me to hit, and so far I'm loving the results.

There's nothing new or earth shattering in the design, but I think it's fun and simple, and most importantly it really does remind me of those old comic books of my youth.
Here's a peek at the main menu screen.

I managed to find some Photoshop colour swatches so I could stay true to the colour palette of the day, and I also learned a bunch of new stuff along the way.
Some in-game action. This screen is not quite finished yet.


My original design included a super cute hero character, but I've had to dial back my expectations a bit. Realistically I just don't have the time, so maybe he'll be part of the 2.0 version. These screenshots are my second draft version of the game's UI, and I like it, so this is what we're using for the first release to Facebook (then Android).  I can't wait to share the results with my word-game loving friends :) If you want to be part of the test group let me know and I'll set you up. For now I should get back to work.