INSTALL.txt

= Setting up Comas

== Get the code

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.

== Base application setup

=== Install the dependencies

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.

=== Rails' profiles

Comas was written using the {Ruby on
Rails}[http://www.rubyonrails.org] 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.

=== Set up your database

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.

=== Base mailing configuration

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).

== First steps for Comas' administration

=== Administrating Comas: Via the command line

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

=== Administrative user

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.

=== Meet the Web interface!

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 http://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.

=== Base system catalogs

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.

=== SysConf: configuration entries

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.

=== Translations

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.

== Enjoy!

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>

=== Thanks

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.