Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Shogun is a modern web framework

branch: develop


Latest Version: 0.0.0

Shogun is a light weight, and yet powerful Ruby PAC web application framework. It's robust design allows for distributed web applications that span multiple servers, databases, and APIs. What does that mean, though?

  • Shogun is a PAC architecture, the only one
  • Shogun as a framework is database, template, style, script, testing library, and even language agnostic (to a degree)
  • Shogun uses Zed Shaw's famous (and reliable) web server named Mongrel 2

To find out more about Shogun's internal you'll need to read the Shogun Book of War.


To start with Shogun all you need to do is have Ruby 1.9, a database (try MongoDB or Riak), and Mongrel 2:

$ brew install mongrel2
$ rvm install 1.9.3 && rvm --create
$ gem install shogun

Now you've got a stable install of Shogun and are ready to make your first app.

From here you can start using the special shogun-create command that comes with Shogun. Except for the initial shogun-create command all of Shogun's tools and tasks use the thor gem. Shogun strives to design by the principle of least surprise. The flags in [] are optional, and the values given are the default:

$ shogun-create appname [--abstractor mongoid]  [--presenter dapperdan]  [--style sassy] [--script coffeescript] [--test rspec] [--automator guard]

You can always access the list of thor tasks by using the below command:

$ thor shogun:tasks
$ thor shogun:build daimyo [--scaffold] [--no-presenter][--no-abstractor] [--no-control]
$ thor shogun:build domain Accounts [--abstraction email:string, password:encrypted, age:number] [--controller index show new create edit update] [--presenter index show new edit]

The final command starts the server. The --port flag allows you to choose a specific port on which to receive connections. With the --environment flag, you can choose an environments to run the server in (with options matching the config/environments files). Finally, the --agent flag gives you the ability to specify which agents (daimyo, domains, and clans being the options) you wish to serve.

$ thor shogun:serve [--port 3000] [--environment development] [--agent all]


An example twitter application:

  - daimyo/
    - "See: The Daimyo"
  - domains/
    - "See: Your Domains"
  - database/
    - "See: Databases"
  - lib/
    - environments/
      - "See: Environments"
    - application.rb
  - tests/
  - vendor/
  - logs/
  - tmp/
  - Gemfile
  - Gemfile.lock
  - Guardfile
  - Thorfile

The Daimyo

  - presentation.rb
  - presentations/
    - pages/
      - splash.html.erb
      - beta.html.erb
      - jobs.html.erb
      - policy.html.erb
      - terms.html.erb
  - abstraction.rb
  - control.rb

The daimyo directory is where all of the top level application logic is stored. This is very similar to the app directory of a rails application. Notice, in this example, two things:

  • Shogun's Presentation, Abstraction, and Control concepts are contained in three ruby files.
  • There's another folder, which contains a generic Presentation (pages/).

As the pages/ category is generic enough, they're allowed to exist in the daimyo directory. If you were to compare this to a rails application, the controls.rb file would also contain the routes.rb logic.

# Shogun.root/daimyo/controls.rb

Shogun::Control.routes do
  push :account, to: AccountRoku
  push :stream, to: StreamRoku

  push get: "login", to: AccountRoku.route :session, :new
  push get: "signup", to: AccountRoku.route :authentication, :new
  push get: "signout", to: AccountRoku.route :session, :destroy


    - accounts_roju/
      - presentations/
      - abstractions/
      - controls/
      - authentication_clan/
        - presenters/
        - abstractions/
        - controls/
      - authorization_clan/
        - presenters/
        - abstractions/
        - controls/
      - session_clan/
        - presenters/
        - abstractions/
        - controls/
      - profile_clan/
        - presenters/
        - abstractions/
        - controls/
    - streams_roju/
      - presentations/
      - abstractions/
      - controllers/
      - list_clan/
        - presentations/
        - abstractions/
        - controls/
      - feed_clan/
        - presentations/
        - abstractions/
        - controls/
Something went wrong with that request. Please try again.