Giving people the tools they need to share knowledge and advance open society through social software.

Roundhouse users guide

Roundhouse is a lightweight social blogging tool. It is released under The GNU General Public License and maintained by Tom Calthrop at Barnraiser. For an overview of features please see the product page.

Installation

Roundhouse includes with it an installer. An understanding of domain name setup, FTP, changing directory privileges and web servers is required. Please read the terms of the license prior to installation.

Requirements

Roundhouse requires a web server running either Apache 1.3/2.x or IIS5/IIS6 with PHP5.x installed including GD library, Curl and BCMath. The installer does its best to detect these for you so if you are unsure simply proceed to installation.

Roundhouse can be installed for a single user or for multiple users. For a single user you can use any domain name or subdomain (example www.example.org or tom.example.org). For multiple users you need a master domain or subdomain name (example example.org or id.example.org). Each user will get a subdomain as their OpenID (example tom.example.org or tom.id.example.org). Choose your installation requirement carefully before proceeding. More information on setting up domains and subdomains can be found in Appendix A.

Installation procedure

Download the latest release of Roundhouse and unzip/untar it onto your local computer. FTP all the files up a directory on your web server. Make a note of the path to the index.php file which will be something like "/public_html/roundhouse_20080920/roundhouse/". The above path will be used for all following examples.

Note: Please ensure the ".htaccess" file (a hidden file) is also copied up when you FTP.

Point your domain name(s) to the directory which contains index.php. Change any permissions to allow PHP access to the scripts.

Point your browser to your domain name and follow the instructions on screen.

Using Roundhouse

If you are not the person who installed Roundhouse you will need to register.

Registration

Enter the main installation domain name into your browser. If registration is permitted you will see a registration button on the page. Click it and follow the instructions.

Logging in

To log in to your account type your OpenID into a web browser. You will be directed to your OpenID account profile web page. At the base of the page click the "Manage" link. Type in your password to log in.

Account screen

Once you are logged in you will see an "Account" link at the top of your web page. Press it. From the account page you can change your profile information, password and email address.

Please note that the memorable date will be requested should you request a new password.

You can upload a JPG, GIF or PNG picture to use for your profile picture.

Profile editor

Once you are logged in you will see an "Edit" link at the top of your web page. Press it. From the profile editor page you can change your masthead (the image at the top of the page), the title of your web page and the theme.

You can add any content to your web page by typing it into the HTML box. This includes things like embedded YouTube movies. You can format your content using HTML. To learn more about HTML you can follow the w3schools tutorial.

You can style your HTML by using CSS. For an introduction to css visit the w3schools tutorial.

Administering Roundhouse

Any account holder can be elevated to be a 'maintainer' (or administrator). As a maintainer they can send new passwords, add language packs and generally maintain the system. If you are a maintainer you will see an additional link at the top of your web page labelled 'Maintain'.

System settings

From the maintain screen you can change the following system settings:

General

  • Allowable HTML tags
    These are the HTML tags that you allow within the profile editor.
  • Language configuration
    Roundhouse defaults to English. If you would like to overrule this by installing a language pack please visit the Roundhouse product page, download the language pack and follow the instructions written within it.

Multiuser only

  • Forbid certain OpenID account names
    Unorthorized OpenID names are OpenID names that you do not allow. These are effectively subdomain names that you do not allow. This could include company branded names, offensive language or subdomains that you are using for an alternative purpose. Use a comma to separate each name.
  • Allow registration
    If you want to allow visitors to register with your installation of Roundhouse the check the "allow registration" checkbox.
  • Maintainer configuration
    Each account holder has an OpenID name (which is also the subdomain). You can give certain account holders permission to enter this maintain screen by adding them. Use a comma to separate each name.
  • Authorized email domains
    You may want to setup Roundhouse to only allow registration from certain email domains such as example_company.com or example_organisation.org. You can limit registration to these by entering them. Leave the field blank to allow any email domain to register. Use a comma to separate each domain name.

Account administration

If you have installed Roundhouse for multiple users you will see an account summary box on the maintain page. This displays a summary of accounts.

An account has one of two states. Pending which indicated that the user has registered, but not clicked the link in the registration email yet, and Live which means the account is operational.

Press the "view accounts" link to list all accounts. Each account is listed with the OpenID name as a link. Select a user and press their OpenID name.

If the account is pending you will have the option to update their details and send them another confirmation email.

If the account is live you will have the option to update their details and send them an email containing a new password.

Customising Roundhouse

The GNU General Public License allows you to customise Roundhouse in anyway you like. We supply three standard approaches to help you acheive this; themes, templates and language packs.

Themes

A theme is a "style" or "look and feel" that a user can apply to their profile web page. Themes can be downloaded and copies into the "themes" directory. Roundhouse will automatically detect it and display it as an option in a users profile edit page.

The easiest way to customise a theme is to copy a current theme, rename it and edit the files within it. Each file is named after the page that it is used on. A common CSS file is used across each page. You can customise the theme using a combination of CSS and images.

You are welcome to put the theme as a zip or tar file on your website and include the same GPL license that we use for Roundhouse. If you do and you tell us we will add the theme to our list of available themes.

Templates

The template is set and is not exchangeable by a user (unlike a theme is). The template can be edited by anyone with an understanding of HTML. The wrapper.tpl.php file builds the main top and bottom menus. A second template is inserted which displays the relevant page information. If you are going to edit a template backup your work first.

Language support

To install another interface language download the relevant language pack from the Roundhouse product page and follow the instructions located in the install.txt file.

Language packs are created using "gettext". If you want to create a language pack you can download a graphical user interface from http://www.poedit.net and follow their instructions to edit the language pack.

You are welcome to put the language pack as a zip or tar file on your website and include the same GPL license that we use for Roundhouse. If you do and you tell us we will add the language pack to our list of available language packs.

Appendix

Subdomain setup

If you want to create an OpenID service you will need to be able to allocate any subdomain to a users account so for instance a user "tom" will be allocated "tom.example.org". This is called a "wildcard subdomain" and it means .example.org gets directed to the Roundhouse installation.

You will only be able to use wildcard subdomains if you have full control over your webserver or if your Internet service provider allows it. If not, then you only perform a single user installation or manually set subdomains and ask users to register with an OpenID account that matches the name of your manually set subdomain.

Each Internet service provider has a different way to set up this. Look through your control panel and if in doubt contact your Internet service provider support team and ask them "How do I point http://example.org to /public_html/roundhouse_20080920/roundhouse/ "?

Once you have pointed all subdomains to the directory containing index.php test it by typing example.org and foo.example.org into your browser. Each should point to your directory. If they do not please ask your Internet service provider for assistance.

Change log

Roundhouse will be available in CVS shortly

Getting support

Please visit the Roundhouse support network in our network to submit any feedback on this document. This includes and tips and tricks you find that may help others in our community.

Contributing

Our goal is that Roundhouse remains lightweight and simple to use. If you have ideas that follow along these lines then please tell us by visiting our network and adding to our Roundhouse feedback network.