Sonntag, 18. November 2012

Using 37signals/sub inside a vagrant virtual machine

Todays topic may be a bit specialized, but I guess it could be interesting for some! 37signals released their shell script toolset (which has a very small footprint) to the public calling it "sub". You can find the code in their github repository and the relating blog post on their signal vs. noise blog.

As I am running windows, it seems that this toolbox is useless for me. But I am working with vagrant all the time, so there is always a linux running in a virtualbox. It goes without saying that using sub within a vagrant box is not as comfy as running your shellscripts locally, but it's better than scattering your scripts all over the place.

When trying sub, I realized that as SharedFolders cannot contain symlinks (at least this is the case when running vagrant on a windows host), sub will not work. In this blog post I would like to describe a setup which makes it possible to run sub within your vagrant box.


Before going into detail, I would like to write a few sentences about sub. What sub does is really simple. It trys to organize your shell scripts by placing them in one specific folder, giving them a defined layout (with usage, description and help texts) and making them auto-completeable. Additionally, there are some scripts like "commands" or "help", which show you which commands are available or how to use a certain command.

You can also add additional auto-completion for your commands, making it even more efficient! I didn't look into this topic yet but I guess it's not that hard and could really add a benefit. You can use any scripting language your system can execute, so beside normal shell and bash, you can do python, ruby, php, perl and many more.

We use sub for some scripts which download logs from our servers, do some healthcheck stuff or execute commands on some of our servers. We write normal shell scripts, bash scripts and python to do this. We have our sub in a private git repository, so evertime somebody adds a command, a git pull and the command is available to me. And as the scripts follow certain rules, it's very easy to work with them.

symlinking not allowed

When using vagrant, you cannot simply install sub as you would on a normal system as you cannot use symlinks and sub places your main executable file as a symlink inside the bin folder.

What I did is placing the symlink inside my /home/vagrant/bin folder. Actually that's not to hard. But you may want to automize this so when you destroy your base box and boot it again, you can use sub without manual installation steps.

But let's start at the beginning. You first need to clone the sub repository into your workspace and add it as a shared folder to your vagrantbox:

config.vm.share_folder "sub", "/home/vagrant/sub", "/path/on/host/to/sub"

Before you execute the script, you need to remove the symlink creation or the script will fail midway. You can use my changed file if you like:


Alright, now you can go ahead as described in the output and initialize your own sub repository. 

To create the symlink inside your ~/bin folder, I created an script. Place it inside your sub folder. It creates the bin folder and places the symlinks inside. Run the init script as often as you like - It only creates new symlinks to new subs and does not overwrite or delete anything:


Last step would be to change your .bash_profile and add the ~/bin folder to the PATH as well as adding the eval line needed for sub. Again, I have added this file to the gist.

After restarting your session, you should be able to use your sub. You can go ahead and use sub as you would with a normal system.

Some more work

There is one problem left: The moment you destroy your machine, everything is gone. Well, not everything: Your sub will persist (it's only a shared folder), but the symlinks and the .bash_profile will be gone.

As you can run the init script more than once without any harm done, you can add the script to your provisioning (chef, puppet or whatever you use). And you should add the lines from the .bash_profile to some template you may have or create a template which you may want to change according to the above.

If both scripts are in place, destroying and provisioning a base box results in no changes for your sub folder.

Happy "subing"

Getting sub running is really easy and pays of almost the moment you installed it. For us, it's mainly that we have a strcuture on where to place scripts and how to document them. Before sub, everybody had some scripts here and there, some without any documentation and some not known to anybody else.

Now the sub commands command shows us which scripts there are and what they do. A sub help command also gives us the usage and the help, which if done properly means nobody has to read the script to use it. Nice!

Keine Kommentare:

Kommentar veröffentlichen