Aaron Lerch

Casual Minecrafting

2014-12-24T13:05:00+00:00

When it comes to gaming, I’m what you would call “cutting edge”. So naturally my kids and I have only recently started playing Minecraft.

I saw qrush post something on twitter about running a custom server for weekends-only survival mode play, but what was really cool was the google maps-style map they had for it. Check it out at pickaxe.club.

My kids are young enough I don’t yet want them playing on a public server, so the idea of a weekends-only-ish survival mode server for friends and family was appealing, and the map interface was just too cool to pass up. I know you can easily create a Minecraft Realms server, which has better server management integration and a hard to beat price point of $10/month, but man, that map. And, let’s be honest here, the fun is usually in the process and not the result (for me).

So I bring you:

How to set up your own vanilla Minecraft server with some cool add-ons in a bunch of moderately-easy steps

I tried to be reasonably thorough in the steps to follow, not assuming too much about any previous experience you might have, so skim and skip as you see fit.

I also originally set up my server using Digital Ocean but I’m going to walk you through it using Amazon Web Services because it’s cheaper, and frankly it’s also just easier to handle a “sometimes-on” server in AWS.

If you don’t care about the hosting of a server but just want to know how to set up and configure the maps, skip ahead.

Prerequisites

I assume you’ve got an AWS account and are at least somewhat familiar with how AWS works. It’s pretty easy, so it doesn’t take a ton of knowledge, but I will skip some of the generic AWS-isms to save time.

I also assume you’ve got a domain name of some sort for which you can control the DNS.

Let’s get started with some basic security setup.

Security

In AWS this is done through IAM roles (access) and EC2 Security Groups (networking).

Go to the EC2 area of the AWS console (no command line stuff here, sorry!) and under the “Network & Security” section choose “Security Groups”. Click the “Create Security Group” button and set it up:

Name: minecraft
Description: Minecraft Server
VPC: [select your VPC in the list – you likely only have one]

This Security Group is basically configuring a firewall. We’ll need to allow SSH traffic, the minecraft server port, and I like to enable HTTP access as well for testing the map generation. (More on that later.) So add the following rules:

Type: SSH
Protocol: TCP
Port Range: 22
Source: Anywhere (let’s live dangerously!)

Type: HTTP
Protocol: TCP
Port Range: 80
Source: Anywhere

Type: Custom TCP Rule
Protocol: TCP
Port Range: 25565
Source: Anywhere

Go ahead and create the group.

IP Addresses

We’ll want a consistent DNS name to access this server, and if you are hosting your DNS using Amazon’s Route 53 service, you have more options available to you. Most of us probably aren’t, though, so we need an Elastic IP so that it stays constant.

Quick aside: in AWS, when you stop and start an instance, it gets a new IP address assigned to it each time. So if we stop our Minecraft server on Monday morning, and start it back up on Friday evening, it’ll have a new IP address unless we leverage an Elastic IP.

Under “Network & Security” in the EC2 console, choose “Elastic IPs”. If you don’t have any available, click the “Allocate New Address” button. I believe you get 5 with no questions asked. If you need a new one, just specify that it’ll be used in VPC (and not EC2).

We can’t use it until we have our server instance up and running, so let’s do that now.

Server Instance

Launch a new Ubuntu EC2 instance. I use the “Quick Start” AMI because, well, because I don’t need anything special so “starting quickly” sounds good. The general recommendations online for running a Minecraft server are to have at least 2GB of memory, so we’ll start there. For my server, I’ll be hosting about 10 people max, so it’s pretty light-weight. I don’t want to spend a lot on this, so I’m using a t2.small instance size which gives me one CPU and 2GB of memory. This currently runs at $0.026 per hour. A t2.medium doubles your specs, and the price.

Make sure you specify the minecraft security group when creating it, and make sure to leave “Shutdown behavior” set to the default of stop. You want to keep this thing around.

After your instance has been launched, head back to “Elastic IPs” and associate your EIP with the newly launched instance.

DNS

Set up an A record to point to your new instance. This is how people will connect to your server when they want to play, and setting it up now will make it easier to SSH in as you move forward also.

For example, you could set up something like minecraft.example.com.

Quick Review

So we haven’t even touched Minecraft yet, but now we have a server, with a dedicated IP address, and a tad bit more locked down network layer for access to the box. It’s time to hop on and set up Minecraft.

Java

Minecraft requires Java. Java doesn’t ship on any OS by default, because how else would they ensure that you get asked “Do you not not not not not want to install the Ask Jeeves Yahoo Plus Plus Toolbar Extension, Spyware Edition?” [DEFAULT ANSWER IS YES, MEANING NO].

OpenJDK is really easy to install on Ubuntu, since the packages are available in the preconfigured repos. Some guides online say that you shouldn’t use it to run a server due to “issues” but for right now, we’re going to use it for ease. If you run into issues with it, tweet at me and I’ll update this post. (Here are some additional helpful hints for installing Java on Ubuntu.)

Install the OpenJDK JRE:

sudo apt-get update
sudo apt-get install openjdk-7-jre-headless
java -version

You should see something like java version "1.7.0_65" as a result. Good enough.

MSM or Vanilla

You can just download and run a Minecraft server pretty easily. However we want the server to automatically start when the server boots, and we’d like it to stop cleanly when the server is going down, etc. The less I have to SSH into the server for, the better.

None of this is rocket science, but I found the Minecraft Server Manager to be pretty convenient at automating this, and some basic level of security (separate user account, etc.) Let’s be clear: MSM does a ton of stuff, almost all of which we won’t need. Just look at the bullet list on their homepage if you want to get a feel for it. The parts I want are the automatic setup and organization, so for this guide we’ll go with MSM.

The installation docs are pretty good, especially if you’re the kind to trust the “wget this URL and execute it” setup helpers.

Don’t curl or wget scripts from the web to bash.

- me

Normally I think it’s a terrible idea to just execute random stuff you’ve downloaded. However, in this case, I’m strongly favoring convenience over security given the nature of what I’m setting up, so let’s just go for it. Accept the defaults except for the last question (which has a trick default answer if you aren’t paying attention):

wget -q http://git.io/Sxpr9g -O /tmp/msm && bash /tmp/msm

Now we’ve got MSM installed and ready to be set up. There’s just one teeny problem, MSM stopped pointing to the latest version of Minecraft a while back. But you can get around it pretty easily. The short version of the commands below is that MSM is also a Minecraft version manager, which lets you manage and run different versions of Minecraft for different servers you might be hosting. Yadda yadda yadda, we just want the latest version of Minecraft for our server, which is pretty easy. We have to invoke a magic hack the MSM folks put in and then tell MSM to download the latest version:

msm jargroup changeurl minecraft minecraft
msm jargroup getlatest minecraft

The last step is to create the server – just pick whatever name you want.

msm server create myserver

Here’s the biggest and stupidest gotcha of all of this. You need to accept the EULA before you can run your server, but MSM doesn’t handle that very elegantly… or at all. The server will not give any indication it failed to start, but running msm myserver status will indicate that it’s still not running. The fix is simple but inane. Switch to the minecraft user and update the eula.txt file in the server’s directory.

sudo su - minecraft
echo eula=true > /opt/msm/servers/myserver/eula.txt

Now, start your server.

msm myserver start

Boom. Now’s a great time to test it out, after one more step: make yourself the operator on your server, assuming that’s something you want.

msm myserver op add your-username

Test It Out

Fire up Minecraft and connect to your new server to make sure everything is working.

Maps

Now that we’ve got a self-hosted server up and running, what about those sweet maps?

Those are borne from the power of The Minecraft Overviewer, a magic and customizable python script that knows how to render maps and bits of info into a Google Maps-style interface. You can make it do a TON of things, but I’ll walk you through a general setup with just a few minor customizations that I use to produce minecraft.aaronlerch.com. Check out the documentation for all the details of what overviewer can do.

What we’re going for is this:

configuration to instruct overviewer to render two map layers (Daytime and Caves) and two sets of points of interest (Signs and Players)
local web server (nginx) for easy testing and local hosting
Amazon S3-hosted static website
cron job to render maps and sync to AWS S3

Setup

First, get your prerequisite utilities in place, nginx for a web server and the AWS command line tools.

sudo apt-get install nginx
sudo apt-get install awscli

AWS S3 and Security

Always with the security, I know. Hosting a website in S3 is the cheapest option you’ll ever find. And the AWS command line tools support for synchronizing a directory into an S3 bucket is hard to beat too. Let’s get S3 set up and ready.

Create a new S3 bucket and configure it for static website hosting. I won’t cover how to do that here, but Amazon has some documentation that helps. Just make sure the Index Document for your S3 website is set to index.html.

For the purposes of the rest of this, I’m going to assume the name of the bucket you created is map.example.com.

On the server we’ll need to have valid credentials to access the S3 bucket and upload files to it. We could leverage EC2 IAM Roles for permissions, but for now let’s just create a single-purpose IAM user and configure things using this user’s credentials.

Create a new IAM user named minecraft and make sure “Generate an access key for each user” is checked, we need API access. Capture the Access Key ID and Secret Access Key, those are important.

Edit the user in IAM and under Permissions click “Attach User Policy”. Select “Custom Policy”, give it a unique name (doesn’t matter what), and use the following document, making sure to use the correct bucket name.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Stmt1418101359000",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectAcl",
        "s3:GetObjectVersion",
        "s3:ListAllMyBuckets",
        "s3:ListBucket",
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": [
        "arn:aws:s3:::map.example.com"
      ]
    },
    {
      "Sid": "Stmt1418101444000",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectAcl",
        "s3:GetObjectVersion",
        "s3:ListAllMyBuckets",
        "s3:ListBucket",
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": [
        "arn:aws:s3:::map.example.com/*"
      ]
    }
  ]
}

This security policy is perhaps a teeny bit overly permissive, but I’ve found there are few things I dislike more than trying to guess precisely which permissions are needed for various AWS “things”. Mostly I’m going for “this user can’t cost me tons of money if compromised”.

Okay, S3 is ready to go – let’s get generate something to put there.

Overviewer Configuration

There’s a little bit to setting up and configuring overviewer, unfortunately, so stay with me here.

First up, install Overviewer following their Ubuntu install directions.

# Add the custom repo to the list
sudo echo deb http://overviewer.org/debian ./ >> /etc/apt/sources.list

# Get the key for the signed repo
wget -O - http://overviewer.org/debian/overviewer.gpg.asc | sudo apt-key add -

# Update the repo sources and install overviewer
sudo apt-get update
sudo apt-get install minecraft-overviewer

Then, create the Overviewer configuration.

# Switch to the minecraft user
sudo su - minecraft

# Create a directory to hold the overviewer config
mkdir /opt/msm/.overviewer

# Start with (and customize!) an example overviewer.conf file, or
# create one using the content in the next code block
wget -O /opt/msm/.overviewer/overviewer.conf https://gist.githubusercontent.com/aaronlerch/15369228265cda5bbd3d/raw/114f0e7419af9e798f38cab6cbf0bd1ae6df262b/overviewer.conf

worlds["myserver"] = "/opt/msm/servers/myserver/world"

def playerIcons(poi):
    if poi['id'] == 'Player':
        poi['icon'] = "http://overviewer.org/avatar/%s" % poi['EntityId']
        return "Last known location for %s" % poi['EntityId']

def signFilter(poi):
    if poi['id'] == 'Sign':
        return "\n".join([poi['Text1'], poi['Text2'], poi['Text3'], poi['Text4']])

renders["normalday"] = {
    "world": "myserver",
    "title": "Daytime",
    "rendermode": smooth_lighting,
    "dimension": "overworld",
    "markers": [dict(name="All signs", filterFunction=signFilter),
                dict(name="All players", filterFunction=playerIcons)],
}

renders["caves"] = {
    "world": "myserver",
    "title": "Caves",
    "rendermode": cave,
    "dimension": "overworld",
    "markers": [dict(name="All players", filterFunction=playerIcons)],
}

# Uncomment the line below if you want to customize the default index.html
# customwebassets = "/opt/msm/.overviewer/customassets"
outputdir = "/usr/share/nginx/html/map"

In a nutshell, this is configuring the primary server world to include two render layers, each with two sets of markers, and to put the results into a subdirectory of the default nginx html directory. Speaking of which, we need to create this directory and give the minecraft user permissions to it.

sudo mkdir -p /usr/share/nginx/html/map
sudo chown minecraft:minecraft /usr/share/nginx/html/map

The only thing left to configure Overviewer is to download the map textures, since Overviewer doesn’t ship with them, it relies on Minecraft itself for them. The easiest way to do this, if not a bit inefficient, is to install the minecraft client locally. Overviewer has helpful instructions because this changes a bit over time. Using the current latest version, 1.8.1, the following works:

sudo su - minecraft
VERSION=1.8.1
wget https://s3.amazonaws.com/Minecraft.Download/versions/${VERSION}/${VERSION}.jar -P ~/.minecraft/versions/${VERSION}/

And that’s it! (That was a lot.)

Give it a try, it’ll take a while to run but not horribly long on a brand new world. Overviewer runs in 2 passes if you are also generating points of interest. Future runs will only render differences from the previous render, so speeds should be faster.

overviewer.py --config=/opt/msm/.overviewer/overviewer.conf --genpoi
overviewer.py --config=/opt/msm/.overviewer/overviewer.conf

After it runs, because we opened port 80 in the AWS Security Group, we can hit the server directly to see the results: http://minecraft.example.com/map.

Success! (Hopefully.)

Upload to S3

If you are running a server 24/7, you can probably just host the maps from the server itself. But if you, like me, are hosting this casually, it’s more fun if the maps are always accessible regardless of the server’s availability.

Configure the AWS CLI to use the Access Key ID and Secret Access Key for the IAM user you created above by running aws configure. Leave the default region name and default output format empty.

Test the upload/sync is successful with this command (don’t forget to use your bucket name)

aws s3 sync /usr/share/nginx/html/map/ s3://map.example.com/

After it completes successfully, you should be able to visit http://map.example.com/ and see your map!

cron

The last step is to set up a cron job to automate the map generation and S3 upload process. I have a simple helper script called update-map.sh that can give you a starting point.

sudo su - minecraft
wget -O /opt/msm/update-map.sh https://gist.githubusercontent.com/aaronlerch/15369228265cda5bbd3d/raw/1915441bac0c8556e9c15d5d829ff946b1764e4b/update-map.sh
chmod 775 /opt/msm/update-map.sh
# Don't forget to update the script to use your bucket name

Then configure cron to run this every 20 minutes, or however frequently you want the map updated.

sudo su - minecraft
crontab -e

*/20 * * * * /opt/msm/update-map.sh >/dev/null 2>&1

Wrapping up

And there you have it, you’ve got an available minecraft server with automatically updating independently-hosted maps! And, you made it all the way through this mini-guide, gold star for you.

There’s plenty of room for customization, and I made some assumptions about the level of sophistication in hosting your Minecraft server and generated maps. Hopefully it’s a good starting point, if nothing else. Above all else, have fun!

Spelunking

2013-11-20T14:57:00+00:00

Writing software is 10% inspiration, 90% grepping through source from github trying to find how the broken internals of a third party dependency work.

- me

It seems like a joke, like something that just couldn’t possibly be true. But in today’s world of increasingly componentized software units, we find ourselves spending a disproportionate amount of time figuring out how and why some 3rd party library works, or doesn’t work.

Can you imagine what a closed-source compiled world would be like?

*shudder*
Thank goodness for OSS.

Today’s “OSS cave” was foreman. Foreman is great, but we are using it to export upstart configuration files and the config files it created result in orphaned processes after a new deploy.

As it turns out this is a long-standing known issue: #97. In the issue, jarthod has a resolution which involves using a customized template to generate a working upstart configuration file. What’s non-obvious is how to incorporate this custom template.

Customizing foreman upstart templates

The foreman upstart exporter uses three templates: upstart/master.conf.erb, upstart/process_master.conf.erb, and upstart/process.conf.erb. jarthod offered a replacement for process.conf.erb.

After looking through the command line options and the source for the upstart exporter, the answer was fairly easy.

Create process.conf.erb in any folder you like
Invoke foreman with the -t option to specify a custom template directory: foreman export upstart /etc/init -t path/to/templates/

The documentation says that the foreman exporter base class uses the method export_template which looks for templates in 3 locations: the -t command-line provided option, ~/.foreman/templates, and finally the templates shipped with the gem itself.

The trick is that if you look at the source for the default upstart exporter, you might be tempted to put the templates in an upstart/ subdirectory, but templates from the -t command-line option are looked for just in the root of that directory.

Here’s the frustrating part

After writing all that down, it seems STUPIDLY SIMPLE. Because it is. But yet it took longer than I wish to find and/or figure all that out. Ugh.

Sinatra, Bundler, and the global namespace

2013-10-26T23:04:00+00:00

Either my google-fu is waning or I ran into an issue most people haven’t so I want to quickly document it.

The scenario

A Rails 4 app mounting a modular-style Sinatra app to service a particular route, kind of like this.

routes.rb

MyApp::Application.routes.draw do
  mount MySubApp => 'subapp'
end

my_sub_app.rb

require 'sinatra/base'

class MySubApp < Sinatra::Base
  # stuff
end

The problem

The Gemfile looks like what you’d expect if you just added gems ‘normally’.

source 'https://rubygems.org'

# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '4.0.0'

# yadda yadda yadda

gem "sinatra", "~> 1.4.3"
gem "sinatra-contrib", "~> 1.4.1"

The problem comes because Bundler is really helpful and requires the gems for you automatically, using the gem name by default. Unfortunately this means that Bundler will end up running require 'sinatra' (and require 'sinatra-contrib') and when used this way Sinatra adds its DSL to the global namespace.

That means that when you run rake, for example, you could see odd error messages like “rake aborted! undefined method ‘task’ for Sinatra::Application:Class”

In my case, sinatra-contrib was intercepting rake’s DSL and obviously failing.

The solution

The solution is to fix the Gemfile to instruct Bundler how to correctly require the sinatra gems.

gem "sinatra", "~> 1.4.3", require: 'sinatra/base'
gem "sinatra-contrib", "~> 1.4.1", require: false

This change results in Sinatra being required correctly for modular app use, and turns off automatic requiring for sinatra-contrib so you can require just the bits you need at the place you need them, since sinatra-contrib is just a set of helpful modules.

It’s not complex or difficult, but the error message (and backtrace) was a little non-obvious.

Preventing Rack::Session on a Per-Request Basis

2012-01-14T22:55:00+00:00

This is admittedly a rare need, but the other day I found myself needing to conditionally enable and disable sessions in Sinatra on a per-request basis. Sinatra uses the Rack::Session middleware to manage sessions. I searched around for a while but couldn’t find out how to do it. There are options for the session that can be set per-request, like this:

get '/' do
  request.session_options[:renew] = true
end

The documentation shows a :defer option that seems to do what I want, but the terminology didn’t make it abundantly clear whether it did or not.

:defer will not set a cookie in the response.

Actually that does sound like what I want, sorta, but mentally I was thinking “turn off” or “disabling” and not “deferring the setting of a cookie.”

With most ruby projects, or for that matter, any interpreted language that isn’t compiled , I’ve found that I end up spending a decent amount of time reading the code from my dependencies. Some unscientific polling of ruby devs I know showed that to be a pretty standard practice.

Doing a little digging through the Rack::Session middleware showed an option that didn’t appear in the documentation:

:skip will not a set a cookie in the response nor update the session state

Now that matches the mental model of what I was looking for, and the behavior as well. Turns out it’s not in the docs because it was added recently from a Rails core team member to support the new asset pipeline in Rails 3.1, and the docs haven’t been updated yet.

So if, on a per-request basis, you want to disable using sessions entirely, simply do:

request.session_options[:skip] = true unless use_session?

(where “use_session?” is your method that figures out whether or not to use sessions)

What’s the diff between :defer and :skip, you ask? Well the answer is in the pull request description

This will not send a cookie back nor change the session state.

The :defer option did not send the cookie back but did change the session state in the backend.

This is useful for assets requests that still go through the rack stack but do not want to cause any change in the session (for example accidentally expiring flash messages).

App Extensibility, Follow Up

2011-10-09T22:35:00+00:00

My last post about introducing an extensibility point got some good feedback. I realized two things:

Following the pattern of rails generators was huge overkill
I wasn’t thinking correctly about the problem to begin with

Rails generators need to support a lot of things. For example, they need to process command line arguments, consume or produce templates, and update existing files in a non-destructive way. The potential complexity in generators is handled by the complexity in the extensility model implemented in rails. Arbitrarily duplicating this complexity (magic class names, inheritance, etc) is just wrong. Which, of course, is why I said:

OK, I’m doing something wrong, I just know it

If I was going to continue down this road (I’m not, see below) I would take a cue from something like Sinatra and take advantage of global methods to reduce/remove requirements on the configuration code.

configure do |host|
  # do something with 'host' to configure your app
end

But that’s all irrelevent. Jeff Lindsay set me straight in a comment on my previous post.

The hooks that most SCM use, like post-commit or post-receive, are based on running shell scripts. This is my favorite approach so far because it’s not language specific.

DUH. I love those things that I look back and think “of course.”

I was thinking about this as a ruby problem, because localtunnel’s client is written in ruby. But it’s not a ruby problem. Localtunnel is a utility. I can write hooks for Git in anything I want, it doesn’t matter what language Git is written in. The same is true for localtunnel.

Taking this approach greatly simplifies the solution. And the simpler solution is always always always the better solution. In this case, we can add a quick check followed by a system call to enable users to provide a shell hook to configure whatever system(s) they want:

SHELL_HOOK_FILE = "./.localtunnel_callback"

...

if File.exists?(File.expand_path(SHELL_HOOK_FILE))
  system "#{SHELL_HOOK_FILE} ""#{tunnel['host']}""" if File.exists?(File.expand_path(SHELL_HOOK_FILE))
  if !$?.success?
    puts "   An error occurred executing the callback hook #{SHELL_HOOK_FILE}"
    puts "   (Make sure it is executable)"
  end
end

Bam. Localtunnel now provides an extensibility point that can be implemented in any language. Well, it will when/if my pull request is accepted. :)

Thanks, Jeff!

App Extensibility in Ruby

2011-09-08T18:13:00+00:00

I ran into an interesting problem recently. There is a utility called localtunnel which connects a public URL to a local port. Extremely useful when it comes to developing an app that leverages services that expose web hooks.

The problem is that the public URL is only valid while the script is running. Which means every time you start it, you potentially need to go update the web hook URL in whatever service you’re using. For example, with Twilio you configure an app that is available at a particular URL. With GitHub you can add post-receive hooks.

What needs to happen is that localtunnel needs to give you a chance to run some custom code after it registers and connects up ports, but before it sits and waits.

It needs an extension point.

One fork seeks to do this by having localtunnel call a web hook. It works, even if it feels a bit ironic. ;) But that involves maintaining another service simply to configure your first service, which is less than ideal. I took a different approach and I’d love to get feedback here, since I’m still so new to this.

Most stuff on the web about extending ruby has to do with class design, or monkeypatching, or something else that assumes all the code is already loaded and executing. In this case, there’s an existing app (not framework) and I want to have it load my code dynamically at runtime. In my code, I want to configure whatever service I need to.

Being a n00b, I’m not the most widely read yet, so I looked at an example of something that I already knew exposed an extension point in a similar way: rails generators.

You can see my code here and the updated readme here, but here’s how it works.

Specify the config to run

This part was easy, I just extended the existing command line processing to add a “-c NAME” argument specifying which configuration you want to run. For example:

$ localtunnel -c twilio 9292

will create a public URL connecting to local port 9292, and will look for an auto configuration implementation named “twilio” and execute it.

Discovery via magic names, I mean, convention

This is a nice, but sometimes frustrating thing about Rails. There’s lots of stuff that magically happens if you organize or name your code a certain way.

In this case, to make it easy to specify via the command line, I opted for a similar “magic name” approach. Name your file foo_auto_config.rb and when you specify “-c foo” I’ll look for your file under a ‘localtunnel’ subdir. This is a way to try and avoid loading a lot of code unnecessarily.

https://github.com/aaronlerch/localtunnel/blob/master/lib/localtunnel/autoconfig.rb
def self.lookup(name)
  including_current = $LOAD_PATH.dup
  including_current << '.'
  including_current.each do |base|
    Dir[File.join(base, "localtunnel", "#{name}_auto_config.rb")].each do |path|
      begin
        require path
      rescue Exception => e
        puts "   [Warning] Could not load autoconfig #{path.inspect}. Error: #{e.message}.\n#{e.backtrace.join("\n")}"
      end
    end
  end
end

This has a few issues with it. Because this is running as a script, if you’re using bundler, the $LOAD_PATH won’t include all the gems unless Bundler.require has been called. So looking in the load path for auto configuration files is probably pointless. Not that gems would include a custom auto configuration anyway. I should probably remove this. (Thoughts?) Secondly, I manually added the local directory because ruby 1.9.2 took it out of $LOAD_PATH by default due to security reasons. And if you consider the use-case, this is typically executed from within ~/MyApp and not randomly throughout the directory structure. Again, similar to rails generators, you run it from the root of your application directory.

Discovery via class name + base class

Now that we’ve figured out which files to load, we still don’t know what code to call. We need to be able to pass in parameters such as the new URL that is reserved, so we probably want a method to call and not just loading a file.

Ruby gives us a feature that allows you to know when a new base class is created: the inherited method. It gets called when a new subclass is created.

I created a base class, LocalTunnel::AutoConfig::Base, which keeps track of all subclasses:

https://github.com/aaronlerch/localtunnel/blob/master/lib/localtunnel/autoconfig.rb
class Base
  def self.inherited(base)
    super

    if base.name && base.name !~ /Base$/
      LocalTunnel::AutoConfig.subclasses << base
    end
  end
end

When someone specifies “-c foo” on the command line, I look for any subclass of LocalTunnel::AutoConfig::Base that is named FooAutoConfig and has a method called “configure”. If I find that, then that’s the auto configuration code that will be called.

https://github.com/aaronlerch/localtunnel/blob/master/lib/localtunnel/autoconfig.rb
def self.find(name)
  lookup(name)

  names = Hash[subclasses.map { |klass| [autoconfig_name(klass).downcase, klass] }]
  klass = names[name]
  return nil if klass.nil?

  configurator = klass.new
  if configurator.respond_to? :configure
    configurator
  else
    nil
  end
end

Then I can call that method on an instance of the matching class, and pass it the new URL.

https://github.com/aaronlerch/localtunnel/blob/master/lib/localtunnel/tunnel.rb
if !@autoconfig.nil?
  configurator = LocalTunnel::AutoConfig.find(@autoconfig)
  if configurator
    configurator.configure(tunnel['host'])
  else
    puts "   [Warning] Unable to find an automatic configuration plugin for '#{@autoconfig}'"
  end
end

Do your custom configuration

The configuration code can then run and do whatever it wants. Usually it’s specific per app. Here’s an example of me using this to configure Twilio.

require 'rubygems'
require 'localtunnel/autoconfig'
require 'twilio-ruby'
require 'uri'

class TwilioAutoConfig < LocalTunnel::AutoConfig::Base

  TWILIO_ACCOUNT_SID = # my account Sid
  TWILIO_AUTH_TOKEN = ENV['TWILIO_AUTH_TOKEN']
  TWILIO_APP_SID = ENV['TWILIO_APP_SID']

  def configure(host)
    # set up a client to talk to the Twilio REST API
    #     client = Twilio::REST::Client.new(TWILIO_ACCOUNT_SID,
          TWILIO_AUTH_TOKEN)
    app = client.account.applications.get(TWILIO_APP_SID)

    # Grab the current voice_url and status_callback and swap out the
      host
    voice = URI.parse(app.voice_url)
    voice.host = host
    status_callback = URI.parse(app.status_callback)
    status_callback.host = host

    app.update({:voice_url => voice.to_s, :status_callback =>
status_callback.to_s})
    puts "   Configured twilio app #{app.friendly_name} for new host
#{host}"
  end
end

OK, I’m doing something wrong, I just know it

I am sure I either overcomplicated this, or just plain did it wrong. Some thoughts I have (in hindsight now) are that perhaps I could’ve exposed a global method for the autoconfig code to call. Then, instead of a base class and magic class name, I’d just load the specified file (magic name is still nice) and in that file I could call “host” to get the new host name.

Leave a comment, create a gist, fork my fork, or tweet at me, but somehow let me know how I could make this better.

n00b

2011-08-25T18:17:00+00:00

It’s been a long time since I’ve spent significant time to learn an entirely new technology. And I’ve had a blast digging into ruby, rails, sinatra, padrino, javascript (okay, I really mean jQuery), and tons of other related frameworks. In spite of some of the excellent, and not-so-excellent, documentation out there, it can be an incredibly frustrating experience. Especially when trying to learn something new – like something really new – not just new to me. Expect to see posts here related to what I’m learning, that make as few assumptions as possible about what you already know.

For example, I recently worked on getting a test environment set up for my app that involves sinatra, mongoid, and twilio APIs. It was an interesting experience. I’m sure seasoned ruby devs wouldn’t have had the same issues, but I’m a firm believer in “you’re not alone” so I’ll be posting about the process to hopefully help someone else in my shoes.

New Content, New Blog

2011-08-22T16:23:00+00:00

For the past 6 months to a year, I’ve been getting more and more into web development on the side (I used to be a web developer, a long time ago.) I’ve been focusing exclusively on ruby-based frameworks. It serves two purposes, I get to learn a new language, and there are plenty of options out there for me to explore.

In that spirit, instead of changing the focus of my existing blog, I’m going to take a cue from Ben Scheirman and start a new blog and just start updating this one more often. Which, given the number of things going on in my life right now, will not be often at all. :)

If you haven’t checked out octopress you should it’s pretty sweet! I love the idea of a file-based blog engine using git.