teamster

A simple bare-bones extensible web portal for individuals or small teams

Dependencies

To run teamster, there is a few dependencies:

  • Only supported in OS X and linux. Not test on Windows. YMMV.

Install

Teamster has been packaged into a gem. To install, simply run gem install teamster.

Usage

  • Create a new folder where you want your site to live and navigate into it: mkdir new-site && cd new-site
  • Initialize teamster and answer some configuration questions: teamster init
  • Run teamster: teamster start

Open a browser and point to http://localhost:9292. A bare teamster page should be shown.

Login Credentials

Right now, the default login credential is "Administrator/password". There is no way to create new users, short of modifying the users file directly.

Running In A "Production" Environment

I do not recommended this application be exposed to the wide Internet just yet, but it should be secure enough for an individual or small team to use over their private LAN.

When the --prod flag is passed, teamster will not run using rackup, but will utilize the Puma app server to serve itself. It will create and bind itself to a UNIX socket file and a Puma state file.

Use With Nginx

Personally, I'm using this in conjunction with the popular Nginx web server. To follow these, Nginx must already be installed on your system.

  • Run teamster in production mode: teamster start --prod --socket-file /tmp/teamster.sock --state-file /srv/my-site/app.state

  • In the nginx site configuration file, add the following:

    upstream app { server unix:///tmp/teamster.sock; }

    server { server_name my-site.example.com;

    location / { proxy_pass http://app; } }

  • Restart nginx.

Open a browser and point to http://my-site.example.com. A bare teamster page should be shown.

Create Modules

To create your custom modules:

  • Navigate to the site folder root: cd /path/to/root/folder/of/my-site
  • Run: teamster --create-module MODULENAME.

This will create the following files in your site folder:

  • lib/teamster-modules/MODULENAME.rb
  • lib/teamster-modules/MODULENAME/views/MODULENAME.erb

In MODULENAME.rb, a class MODULENAME will be created. It is subclassed from Sinatra::Base and it also includes some helper class methods from Teamster::Modules::BaseModule. When developing it, you can treat it just like a Sinatra web application.

Conventions To Adhere To

Your teamster module application should reside in the lib/teamster-modules folder, and all other files should be in the lib/teamster-modules/<modulename> folder. Thie will help greatly when importing and exporting. If you need to modulename configuration, data or other content, please store them in subfolders, for example, lib/teamster-modules/<modulename>/conf.

The only exception to this rule are css & javascript files. Name your files as <modulename>.css & <modulename>.js and place them in the public/css & public/js folders respectively.

When creating HTTP routes, your base route should always be /<modulename>. Other routes for your teamster module should be children of this route.

When creating views, your summary view should be named <modulename>_summary.erb in lowercase. It is highly encouraged for other views of the same module to be prepended with <modulename>_.

Helpers Available To Modules

This is a small list of helper methods that can be used in your modules.

  • logged_in?

This returns true or false. Useful to check if a user has logged in.

get '/login_checker' do
  if logged_in?
    "User has logged in."
  else
    "You are not logged in."
  end
end
  • login_required

This halts a route from being run if a user has not yet logged in. Once a user has logged in, the route will be reloaded. The way to use this helper is:

get '/protected_route' do
  
  do_stuff
end
  • current_user

This just returns the username of the currently logged in user.

get '/show_name' do
  
  puts "Hello, #{current_user}"
end