# Tracks: a GTD web application, built with Ruby on Rails

- Homepage: http://www.rousette.org.uk/projects/
- Trac (for bug reports): http://dev.rousette.org.uk/report/6
- Wiki (more info on installation): http://dev.rousette.org.uk/wiki
- Author: bsag (http://www.rousette.org.uk/)
- Contributors: Nicholas Lee, Lolindrath, Jim Ray, Arnaud Limbourg, Timothy Martens, Luke Melia, John Leonard (for great installation tutorials on Windows XP), Reinier Balt, Jacqui Maher, James Kebinger
- Version: 1.04
- Copyright: (cc) 2004-2007 rousette.org.uk
- License: GNU GPL

While fully usable for everyday use, Tracks is still a work in progress. Make sure that you take sensible precautions and back up all your data frequently. Full changenotes can be found in `doc/CHANGENOTES.txt`. Full API documentation can be found at `doc/app/index.html`, once you have run `rake appdoc`

IF THIS CRASHES YOUR MACHINE AND LOSES YOUR DATA, IT'S NOT MY FAULT!

## Installation

Before you start, you need to make sure that you have Ruby 1.8.2 installed. Rails 1.0 and RedCloth are now included in the vendor directory of the distribution, so you don't need to install them yourself. You also need some kind of database. MySQL is probably the most popular, but it's also easy to use PostgreSQL or SQLite/SQLite3. Note that upgrading via the `rake db:migrate` command is quite a bit more tricky currently with SQLite and SQLite3. If you have Mac OS X Tiger, you already have Ruby 1.8.2 and SQLite3 installed, so all you need to do after installing Rails and Redcloth is to install the sqlite3-ruby gem (1.1.0). If you're using MySQL, you might want to install the native MySQL bindings to improve performance:

    sudo gem install mysql

On Mac OS X, you need the following:

    sudo gem install mysql -- --with-mysql-dir=/usr/local/mysql

See the wiki for more details on installing all the necessary components on all the supported platforms.

### New installations

#### MySQL

In the following, I'm assuming that you're using MySQL and the built-in WEBrick server. See the sections below for additional instructions on using other databases and servers.

- Unzip `tracks_1.04.zip` somewhere in your home folder ( e.g. `/Users/yourusername/Sites`).
- Make a database for which you have full access rights. e.g. assuming that you want to call your database `tracks104`, at the command line:

        mysql -uroot -p
        mysql> CREATE DATABASE tracks104;
        mysql> GRANT ALL PRIVILEGES ON tracks104.* TO yourmysqluser@localhost \
         IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION;

- Copy the file `config/database.yml.tmpl` to `config/database.yml`, `config/environment.rb.tmpl` to `config/environment.rb` and `log.tmpl` to `log`.
- Open the `tracks/config/database.yml` file, and enter your username and password details for the database you just set up under the 'production' and 'development' sections. NB: If you do set up the entry for 'test', make sure that you specify a different database, or when you run tests, they will overwrite your data. It's very important that you don't use TABS in any of the `*.yml` files. Just use spaces to indent.
- Open the file `config/environment.rb` and look at the last line which should read: `SALT = "change-me"`. Change the word change-me to something else of your choosing. This string will be used as a 'salt' to encrypt your password and make it a bit more secure. Also look at the timezone setting at the bottom. You can leave it commented out if your server is in the same time zone as you, but you may need to adjust it if your server is in a different time zone.
- Run 'rake db:migrate', which will create the necessary tables in your database, including some required contents:

        cd /PATHTO/TRACKS
        rake db:migrate

- If you find that 'rake db:migrate' doesn't work for you (there have been reports of it not working well with the MySQL distributed with InstantRails on Windows), you can use the command `rake db_schema_import` which will do the same thing.
- (Optional step) If you want to import some example next actions, projects and contexts, use the command `rake load_fixtures`. This will import data into your database, including two users: an admin user with the login 'admin' and password 'abracadabra', and a normal user 'jane' with password 'sesame'.
- Check the shebang lines of the `public/dispatch.*` files and all the files in the script directory. They are set to `#!/usr/bin/env ruby` by default. This should work for all *nix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like `#c:/ruby/bin/ruby`.
- Run the following command at your command line (Important: If you already have an application running on WEBrick (Tracks or anything else), make sure that you stop the server (Ctrl-C in the terminal running the server), or run Tracks on a different port using the `--port` option):

      cd /PATHTO/TRACKS
      ruby script/server -e production

- In a browser (if you haven't loaded the example data), go to `http://0.0.0.0:3000/signup`. This will allow you to choose a username and password for the admin user. Thereafter, anyone else trying to access `/signup` will get a message that they are not allowed to sign up, and are given your email address to contact for permission. When you are logged in as the admin user, you can visit `/signup` to sign up additional users (who will not be able to view any of your next actions, contexts, projects or notes, but can set up their own separate tasks), and visit `/login` to login yourself.
- Add some contexts at `http://0.0.0.0:3000/contexts` (you must do this before adding any next actions) and projects at `http://0.0.0.0:3000/projects` and then you're ready to add all your next actions.
- You can set various preferences by visiting `http://0.0.0.0:3000/users/preferences`. These are stored on a per-user basis in the database.
- Have fun!

#### SQLite/SQLite3

The instructions are the same as those for MySQL above, except that I have provided an SQLite3 database, pre-loaded with the correct schema (`db/tracks-104.db`). All you need to do is to insert that filename in database.yml. e.g.:

    adapter: sqlite3
    database: /PATH/TO/TRACKS/db/tracks-104.db

### Upgrading from Tracks 1.03

#### MySQL or Postgresql

- For safety, rename your current Tracks directory to 'tracks-old' or something similar.
- Before you do anything else, BACK UP YOUR DATABASE (tables and content) and keep the SQL dumps somewhere safe so that you can recreate the old database if necesary.
- Copy the file `config/database.yml.tmpl` to `config/database.yml`, `config/environment.rb.tmpl` to `config/environment.rb` and `log.tmpl` to `log`.
- Open the file `config/environment.rb` and look at the last line which should read: `SALT = "change-me"`. Change the word change-me to something else of your choosing. This string will be used as a 'salt' to encrypt your password and make it a bit more secure. Also look at the timezone setting at the bottom. You can leave it commented out if your server is in the same time zone as you, but you may need to adjust it if your server is in a different time zone.
- In `database.yml` insert your old database name, user and password under the 'development' section.
- Run the command `rake extract_fixtures` inside the Tracks directory. This will populate the `db/exported_fixtures` directory with `*.yml` files corresponding to the contexts, projects and todos table from the contents of your old database.
- Open `db/exported_fixtures/todos.yml` and search for the lines starting `created:` and replace with `created_at:`.
- Create a new MySQL database (named tracks104, for example).
- In `database.yml` insert this new database name, user and password under the 'development' and 'production' sections.
- Run the command `rake db_schema_import` inside the Tracks directory. This should import the upgraded schema for 1.04 into your new database.
- Run the command `rake load_exported_fixtures` which will import the contents of your old database from the fixtures files in `db/exported_fixtures`.
- Check the shebang lines of the `public/dispatch.*` files and all the files in the script directory. They are set to `#!/usr/bin/env ruby` by default. This should work for all *nix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like `#c:/ruby/bin/ruby`.
- From here, follow the remaining steps for new users above to start the server. Since your users table was deliberately not imported, you'll have to re-create your users via `/signup`. Signup is now at `http://0.0.0.0:3000/signup`, and login at `http://0.0.0.0:3000/login`.

#### SQLite or SQLite3

- For safety, rename your current Tracks directory to 'tracks-old' or something similar (making sure that you keep your old database safe), create a new directory for the new version.
- Copy (NOT MOVE!) your old database into the new tracks/db directory.
- Copy the file `config/database.yml.tmpl` to `config/database.yml`, `config/environment.rb.tmpl` to `config/environment.rb` and `log.tmpl` to `log`.
- Open the file `config/environment.rb` and look at the last line which should read: `SALT = "change-me"`. Change the word change-me to something else of your choosing. This string will be used as a 'salt' to encrypt your password and make it a bit more secure. Also look at the timezone setting at the bottom. You can leave it commented out if your server is in the same time zone as you, but you may need to adjust it if your server is in a different time zone.
- In `database.yml` insert your old database name, user and password under the 'development' section.
- Run the command `rake extract_fixtures` inside the Tracks directory. This will populate the `db/exported_fixtures` directory with `*.yml` files corresponding to the contexts, projects and todos table from the contents of your old database.
- Open `db/exported_fixtures/todos.yml` and search for the lines starting `created:` and replace with `created_at:`, and `done: "0"` with `done: "f"` and `done: "1"` with `done: "t"`. You need to replace the similar 'done' lines in `projects.yml`, and in `contexts.yml` replace `hide: "0"` with `hide: "f"` and `hide: "1"` with `hide: "t"`.
- In `database.yml` insert the name of the provided `tracks-104.db` the 'development' section.
- Run the command `rake load_exported_fixtures` which will import the contents of your old database from the fixtures files in `db/exported_fixtures`.
- Check the shebang lines of the `public/dispatch.*` files and all the files in the script directory. They are set to `#!/usr/bin/env ruby` by default. This should work for all *nix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like `#c:/ruby/bin/ruby`.
- From here, follow the remaining steps for new users above to start the server. Since your users table was deliberately not imported, you'll have to re-create your users via `/signup`. Signup is now at `http://0.0.0.0:3000/signup`, and login at `http://0.0.0.0:3000/login`.

## Other servers

WEBrick is the easiest server to get working to test out Tracks, and will be fine if you have Tracks installed on your own machine. One nice feature in Rails 0.13.1 is that WEBrick runs by default on the IP address 0.0.0.0, which means that you can access it via 127.0.0.1 when you are on the same machine, or via the external IP address of the machine running Tracks, so long as you can access the network of that machine from your current location. However, it is possible to use other servers, and the new re-writing rules of Rails 0.13.1 ('Routes' in `environment/routes.rb`) mean that very little configuration is needed. With Rails 1.0, if you have lighttpd installed, running `script/server` starts lighttpd instead of WEBrick, creating the appropriate lighttpd.conf file automatically.

### Apache

See the file `tracks/README_RAILS` for an example of an Apache conf. The file `tracks/public/.htaccess` contains the necessary re-write rules to call `dispatch.cgi` or `dispatch.fcgi`. All other rules are handled by `routes.rb`

### Lighttpd

Again, see `tracks/README_RAILS` for a working example of a lighttpd.conf file. Note that you'll want to change the line: ``"bin-environment" => ( "RAILS_ENV" => "development"` to `"bin-environment" => ( "RAILS_ENV" => "production"`.

## Contacting me

I'd love any suggestions you have for improvements, bug-fixes etc. Email me at: butshesagirl@rousette.org.uk

You can also leave bug reports, feature requests, and comments at: http://dev.rousette.org.uk/report/6

Subscribe to the tracks-discuss mailing list here or by sending an email to tracks-discuss-join@lists.rousette.org.uk.