Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
246 lines (176 sloc) 8.94 KB
= 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.