| Path: | INSTALL.txt |
| Last Update: | Sun May 03 16:56:47 -0500 2009 |
The first step towards Comas bliss is, of course, getting the Comas code. You can clone from its public Git repository at:
git://github.com/gwolf/comas.git
As stable releases arrive, I will also have them for direct download at our homepage. Comas’ homepage is:
http://www.comas-code.org/
There, you will be able to find latest releases and documentation.
Install Comas’ dependencies on your system. They are outlined in the Dependencies section of the README file - Instead of maintaining two separate lists (prone to get out of sync), please refer to that file.
Comas was written using the Ruby on Rails web framework (or Rails, for shortness). Rails implements the concept of three different default environments to better serve the application development/tuning, testing and production uses - They are aptly named development, test and production and have some different characteristics. I suggest you to look at a Rails reference for further explanation.
At least, you will want to go through the next steps for both the development and producition profiles. There are many ways to do this, but probably the easiest is to set the RAILS_ENV environment variable:
$ export RAILS_ENV=production
or
$ export RAILS_ENV=development
If you don‘t specify it, the default will be development.
You should now configure config/database.yml - It is a YAML file. You can copy it from config/database.yml.orig and edit to suit your site. Please note that Comas was developed with PostgreSQL in mind - It will most probably not work with other databases. And then again, why would you want to use anything else? ;-)
Once your database is created, run Rails’ migrations to create Comas’ tables:
$ rake db:migrate
If everything goes well, you should have a working (although minimal and probably unusable) Comas installation. Congratulations! You now need to make your system useful.
Now, set up the configuration to send the mail generated by your system. To do this, create the file config/mail_settings.rb - You can copy mail_settings.rb.orig and use it as a template.
The most basic configuration (which means "no mail should ever be sent") is:
ActionMailer::Base.perform_deliveries = false
Do not forget to set the ActionMailer::Base.default_url_options[:host] key, with the hostname for your Comas installation, as it will be used to generate the mails sent to your attendees (so it is imperative it links back into your system).
As Comas is a Rails application, probably the most powerful administrative interface is Rails’ _interactive console_. Of course, it will require you to know some Ruby - but it will allow for the greatest of powers.
To run the interactive console, enter Comas’ main directory and type:
$ ./script/console
Rails defaults to opening the console in the development environment - If you intend to perform queries or change values on your production environment, specify so when starting the console:
$ ./script/console production
The first thing you should do -specially if you are not very comfortable with the interactive console- is to create an administrative user with enough privileges to do anything else you will need via the Web front-end.
If you are not well-versed in Ruby, you might want to create your first administrative user via the provided create_user script. Take this example run:
$ ./script/create_user
This script will create a new user for your Comas system.
In order to abort, just answer with a blank line.
Note we are running under the -={development}=- environment
Login: admin
First name: John
Family name: Doe
E-mail: john@doe.org
Password (WILL be displayed): johnny
Please select any administrative tasks this person should have. Enter
just the task IDs (i.e., just the numbers), separated by commas
1- Attendee administration
2- Conferences administration
3- Academic committee
4- Attendance management
5- System configuration
6- Certificates generation
7- Translation management
Desired tasks for John Doe: 1, 5
The person was created successfully!
You can give any tasks to your administrative user, and create as many users as you need - Just make sure you have a user with "Attendee administration" rights. That is as the One True Power - A user that can perform "Attendee administration" tasks can -from the Web interface- grant and revoke such rights from any other user. In this example, we also added "System configuration" rights, as we will use it right away.
So, you are ready to use your newly installed Comas system! You just have to launch the Web server (or, to be more precise, the application server, which happens to speak HTTP):
$ ./script/server
Open your browser, and point it to localhost:3000/ (that means, "this same machine, on port 3000" - Of course, you will later be able to change that into something more meaningful). You will be greeted by an empty Comas instance. Congratulations!
Log into the system by clicking on "Log in" on the menu. You will see many new options, depending on the admin tasks you chose to give to this user.
The system is NOT yet ready, however, for you to create a conference and start accepting proposals. You should first populate the base catalogs with categories meaningful to you. Click on "Catalogs management", and fill in some values. We suggest you to add said values in English - Refer to the Transalations section later on for details on translations.
The catalogs that should always be present in your system are:
| prop_statuses: | What status can a proposal be? Typical values include new, accepted, rejected, further details requested, withdrawn, etc. If you don‘t mark it otherwise in the configuration (explained further on), the PropStatus with the lowest ID will be the default for newly registered proposals, and the one with the highest ID will be what is shown as accepted proposals. |
| prop_types: | What kind of proposals are we accepting? Typical values might be talk, tutorial, workshop, plenary, panel… |
| rooms: | Provide here a list of the rooms you will have for your sessions (i.e. "auditorium 1", "computer lab", etc). This will be mainly used for scheduling and attendance tracking. |
The SysConf table is a sort of registry used for global configuration settings, and some values are created at database build time.
The most important value to set here is the mail_from entry - It should be an existing mail address (i.e. one which is read by humans). It will be used for all the mails sent by Comas. I will stress this again: As this will probably be used by your potential attendees to contact you, it NEEDS to be a valid address.
Comas has been built with internationalization in mind, and the whole system can be translated. As of now, the system is fully available in English (the default language) and Spanish.
The translation is achieved through two subsystems:
| GetText: | The powerful GNU GetText system is used for all static strings - This means, for all strings that are generated and appear literally in the system‘s source code. GetText‘s translation template can be found in po/comas.pot. |
| Translation: | This is a homegrown, ad-hoc solution, and admittedly not as complete or
complex as GetText. This second infrastructure was introduced because
GetText has the disadvantage that it needs to be compiled, and it is not
well suited to represent the dynamic information not appearing in the
sources, such as any dynamic catalog or column names or catalog values.
This subsystem is handled through the Language and Translation models, and filling it up should be automatically. The languages list are automatically taken from GetText‘s known languages. In order to complete the translations, you need a user with the translation administrative task; a corresponding link will be shown in the Comas main menu. |
This walk-through should have been enough to get you a working, altough basic, Comas installation. Was it easy? Was it hard? Perhaps more important: Was it clear enough?
Please don‘t hesitate to contact me for any help or addition:
Gunnar Wolf <gwolf@gwolf.org>
This software was developed thanks to the time allotted to it by my employer, Instituto de Investigaciones Económicas UNAM. I wholeheartedly thank the Institute for agreeing to share the code as Free Software.