Fork me on GitHub

Creating a Dumb App

The Dumb Store uses the GitHub's "Fork & Pull" Collaborative Model as its backbone.

Fork and clone

  1. Fork the Dumb Store repository to your own account.

  2. Clone the repository to your computer so that you can start writing code in it.

    $ git clone git@github.com:yourname/dumbstore.git

Implement your app

  1. Create a new file in the apps/ folder. Use a name that reflects the nature of your app. Currently The Dumb Store only supports Ruby apps.

    $ touch apps/my-app.rb
  2. A Dumb App is a Ruby class that inherits from Dumbstore::App. The name of the class must be a titlized verison of the file name. For example, weather.rb should have a class called Weather. A file called local-listings.rb should have a class called LocalListings.

    class Weather < Dumbstore::App
              author 'Ramsey Nasser'
              author_url 'http://nas.sr/'
              description 'My awesome weather app'
    
              text_id 'weather'
              def text params
                current_weather = WeatherApi.get_weather
                "<Response><Sms>The weather is #{current_weather}</Sms></Response>"
              end
    
              voice_id 'weather'
              def voice params
                current_weather = WeatherApi.get_weather
                "<Response><Say>The weather is #{current_weather}</Say></Response>"
              end
            end

    An app can operate over text (SMS), voice, or both.

    To support SMS, give your app a text ID as shown above and implement a text method that takes a single argument and returns a string. The text method will be executed when a user sends a message to the store with your app's text ID. The argument passed to the method is a hash of the original Twilio request. In the above example, params['Body'] would hold the value of the user's text message minus the app ID. The method must return a valid TwiML document in response to the user's text.

    Supporting voice is the same, except you give your app a voice ID and implement a voice method. Its parameters are different.

    You can implement whatever kind of logic you want in the text and voice methods. See the apps in the apps/ folder for reference.

    Do not use a text or voice ID of an existing app.

Take out a pull request

  1. Commit your changes to your local repository.

  2. Push the changes to your GitHub account and take out a pull request.

  3. Discuss the submission in the comments thread of the pull request. Once it's approved, it gets pushed to the store and made available to everyone!

  4. Add this logo to your site:

Running Your Own Dumb Store

The Dumb Store is a Sinatra app and can run on just about anything that can run Sinatra. Dumbsto.re runs on Heroku, but it doesn't have to.

Prerequisites

To install on your own web server, you'll want to install these things:

Securing Twilio Credentials

Dumbsto.re uses the Twilio REST API to send phone calls and text messages. Once you sign up for Twilio and buy a number you'll want to copy your Twilio SID and authentication token into environment variables (Heroku calls these "config vars") for the system user that Dumb Store is running under. With many web servers, that's typically a user called "www-data" or something similar. For that user you'll want to make sure these variables are available that user, and only that user:

DUMBSTORE_ACCOUNT_SID=[YOUR ACCOUNT SID]
DUMBSTORE_AUTH_TOKEN=[YOUR AUTH TOKEN]

Installation

The Dumb Store is configured to look for itself in /home/dumbstore. This can be changed in deploy/thin-config.yml. Otherwise though, to install the Dumb Store on a Debian-based GNU/Linux system, create the directory /home/dumbstore, clone the code from our git repository, and install gem dependencies like so:

sudo mkdir /home/dumbstore
sudo git clone git@github.com:[YOUR GITHUB USER]/dumbstore.git /home/dumbstore/.
cd /home/dumbstore/
bundle

Once all gems are installed from running bundle, you can start the Dumb Store using the system user you want it to run under with the included Thin web server like so:

ruby server.rb

You should then get something like this indicating which port Thin is using:

 == Sinatra/1.4.5 has taken the stage on 4567 for development with backup from Thin

In this case, the port is "4567", but it will probably be different in your install. In your browser, you should now be able to navigate to your server's IP address with the specified port to see your Dumb Store install live: http://[IP ADDRESS]:[PORT NUMBER]

Once you have either a domain name or even just your server's IP address set up, you can configure Twilio to send voice and text requests to your Twilio app:

Voice:
http://[YOUR DUMBSTORE URL]/voice
Messaging:
http://[YOUR DUMBSTORE URL]/text