diff --git a/tracks/README_FIRST.txt b/tracks/README_FIRST.txt index ab4df589..c0e0c8b7 100644 --- a/tracks/README_FIRST.txt +++ b/tracks/README_FIRST.txt @@ -3,7 +3,7 @@ The main README file is in tracks/doc/README_FOR_APP, and the change log in trac This will generate the documentation as above in tracks/doc/app. -Database schemas for MySQL, PostgreSQL and SQLite are available in tracks/db, along with some example contents in tracks_1.0.3_content.sql. +Database schemas for MySQL, PostgreSQL and SQLite are available in tracks/db, along with some example contents in tracks_1.031_content.sql. ** IMPORTANT ** @@ -12,5 +12,6 @@ Before you do anything else, you need to copy certain files and rename the copy: tracks/config/database.yml.tmpl -> tracks/config/database.yml tracks/config/settings.yml.tmpl -> tracks/config/settings.yml tracks/log.tmpl -> tracks/log + tracks/tmp.tmpl -> tracks/tmp You need to put your settings into database.yml and settings.yml. Just leave the .tmpl versions as they are. I'm sorry to impose this extra step, but it's important for the subversion repository not to have your super-seekrit MySQL database user name and password checked in to the repository for all to see! \ No newline at end of file diff --git a/tracks/doc/CHANGELOG b/tracks/doc/CHANGELOG index 03488937..958dabf2 100644 --- a/tracks/doc/CHANGELOG +++ b/tracks/doc/CHANGELOG @@ -13,7 +13,7 @@ Trac (for bug reports and feature requests): http://dev.rousette.org.uk/report/6 Wiki (deprecated - please use Trac): http://www.rousette.org.uk/projects/wiki/ -== Version 1.04 +== Version 1.031 1. Tidied up the interface a bit, fixing mistakes in the wording. 2. The number of actions reported is now correctly pluralized depending on the number of actions (e.g. 1 action, 2 actions). @@ -23,6 +23,7 @@ Wiki (deprecated - please use Trac): http://www.rousette.org.uk/projects/wiki/ 6. Rails based db creation and migration via rake. 7. Added loginhash to settings.yml. 8. Modify signup to prevent is_admin being set by malicious user. Begin work on standardising layout for login controller. +9. BIGGEST NEW FEATURE: Tracks is now properly multi-user, thanks to the work of Nicholas Lee. Any new users that you sign up can't view any of your next actions, contexts, projects or notes, and they get a clean slate to add their own. Great Things are planned in this direction... == Version 1.03 diff --git a/tracks/doc/README_FOR_APP b/tracks/doc/README_FOR_APP index e80a5679..57474733 100644 --- a/tracks/doc/README_FOR_APP +++ b/tracks/doc/README_FOR_APP @@ -2,8 +2,8 @@ * Homepage: http://www.rousette.org.uk/projects/ * Author: bsag (http://www.rousette.org.uk/) -* Contributors: Nicholas Lee, Lolindrath, Jim Ray, Arnaud Limbourg -* Version: 1.03 +* Contributors: Nicholas Lee, Lolindrath, Jim Ray, Arnaud Limbourg, Timothy Martens +* Version: 1.031 * Copyright: (cc) 2004-2005 rousette.org.uk * License: GNU GPL @@ -17,49 +17,68 @@ While fully usable for everyday use, Tracks is still a work in progress. Make su == Installation -Before you start, you need to make sure that you have Ruby 1.8.2, Rails 0.12.1 (it may work with versions down to 0.11.0, but it's much better to get the latest version), and Redcloth 3.0.3. By far the easiest way to get these installed is using gems (see instructions on getting gems here http://wiki.rubyonrails.com/rails/show/GemRails). You also need some kind of database. MySQL is probably the most popular, but it's also easy to use PostgreSQL or SQLite. 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). +Before you start, you need to make sure that you have Ruby 1.8.2, Rails 0.13.1 (it may work with versions down to 0.12.0, but it's much better to get the latest version), and Redcloth 3.0.3. By far the easiest way to get these installed is using gems (see instructions on getting gems here http://wiki.rubyonrails.com/rails/show/GemRails). You also need some kind of database. MySQL is probably the most popular, but it's also easy to use PostgreSQL or SQLite. 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). See http://dev.rousette.org.uk/wiki/Tracks/Install for more details on installing all the necessary components on all the supported platforms. === New users In the following, I'm assuming that you're using MySQL and the built-in WEBrick server. See the sections below for addtional instructions on using other databases and servers. -* Unzip tracks_1_03.zip somewhere in your home folder ( e.g. /Users/yourusername/Sites). -* Make a mySQL database called tracks for which you have full access rights. e.g. at the command line: +* Unzip tracks_1_031.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 are using MySQL, and that you want to call your database tracks, at the command line: mysql -uroot -p mysql> CREATE DATABASE tracks; mysql> GRANT ALL PRIVILEGES ON tracks.* TO yourmysqluser@localhost IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION; - -* Import the tables using the tracks_1.0.3_mysql.sql files (in tracks/db). If you'd also like some example data to play with, you can import it from tracks_1.0.3_content.sql (also in tracks/db). You don't have to use the example data, but if you don't, you'll need to visit [tracks_url]/contexts first to add a few contexts before you add any next actions. + +* Make sure that you've followed the instructions in tracks/README_FIRST.txt, and copied and renamed all the files and directories ending in .tmpl to remove the .tmpl extension. * Copy the files tracks/config/database.yml.tmpl and tracks/config/settings.yml.tmpl to the same file names without the *.tmpl extension (i.e. the extension should just be .yml). -* Copy the log.tmpl directory to log -* Open the tracks/config/database.yml file, and enter your username and password details for the database you set up before. If you're running in production mode, you only really need to set up the entry under 'production'. -* Open the tracks/config/setting.yml file, and enter your desired format for dates and your email address for the signup page, along with the other configuration settings. The comments in settings.yml should make it self explanatory. NB: It's very important that you don't use TABS in any of the .yml files. Just use spaces to indent. -* Check that the path to Ruby is correct in the tracks/public/dispatch.* files, and also /script/server. The default (#!/usr/bin/ruby) is fine for Mac OS X Tiger, but if you've installed Ruby yourself in /usr/local/bin, you'll need to change it. -* Open a terminal and navigate inside the tracks folder (e.g. cd /Users/yourusername/Sites/tracks). -* Run the following command (Important: If you already have an application running on WEBrick (Tracks or anything else), make sure that you stop the server, or run Tracks on a different port using the --port option): - ruby script/server --environment=production +* Copy the log.tmpl directory to log, and tmp.tmpl to tmp. +* Open the tracks/config/database.yml file, and enter your username and password details for the database you just set up. If you're running in production mode, you only really need to set up the entry under 'production'. 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. +* Open the tracks/config/settings.yml file, and enter your desired format for dates and your email address for the signup page, along with the other configuration settings. The comments in settings.yml should make it self explanatory. NB: It's very important that you don't use TABS in any of the .yml files. Just use spaces to indent. +* The file tracks/Rakefile contains various useful tasks, one of which is 'migrate': this will populate the database you've made with the correct table schemas. It also adds a table 'schema_info', which keeps track of which version you are using. This means that you can potentially also revert back to an earlier schema. Use it as follows at the command line: + + cd /PATHTO/TRACKS + rake migrate -* In a browser, 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, and visit /login to login yourself. Note that Tracks isn't truly multi-user: all your users will be able to view (and edit) your data. The login system is just to restrict access to your sensitive data. +* If you'd also like some example data to play with, you can import it from tracks_1.031_content.sql (in tracks/db). You don't have to use the example data, but if you don't, you'll need to visit http://YOURURL/contexts first to add a few contexts before you add any next actions. Note that no users are provided in the content file, so you'll need to visit the signup page (http://YOURURL/signup) to create some users. +* Check that the path to Ruby is correct in the tracks/public/dispatch.* files, and also /script/server. The default (#!/usr/bin/ruby) is fine for Mac OS X Tiger, but if you've installed Ruby yourself in /usr/local/bin, you'll need to change it. +* 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, or run Tracks on a different port using the --port option): + cd /PATHTO/TRACKS + ruby script/server -e production + +* In a browser, 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. * Have fun! -=== Upgrading from a previous version of Tracks +=== Upgrading from Tracks 1.03 + +==== MySQL or Postgresql -* Before you do anything else, BACK UP YOUR DATABASE (tables and content). Then make a separate export of the contents only (assuming that you want to move your data to the new version.) -* There are new fields in the projects and contexts table, so you might need to edit your contents dump accordingly. Use db/tracks_1.0.3_content.sql as a guide for the correct syntax. In particular, note that you will need to manually add values to the position columns in projects and contexts. If you import your old database dump into the new database schema, all rows will get the position value of 0, which will break positioning. Add values from 1 upwards to each row. Don't worry about the order, as you can alter it through Tracks itself later. If you were using Tracks 1.02a, you shouldn't need to edit either the users or todos table, but check db/tracks_1.0.3_content.sql if you are unsure. If you are upgrading from an earlier version of Tracks, it would be safer not to include the contents of your previous users table, but to create your users again through /signup. * For safety, rename your current Tracks directory to 'tracks-old' or something similar, and if you are able, create a new database for the new version. If you can't create a new database, delete the contents and tables in your old one MAKING SURE THAT YOU HAVE BACKED UP YOUR DATABASE FIRST. -* Import tracks_1.0.3_mysql.sql from tracks/db (or the appropriate schema for your database), then your own contents dump file into the new database. -* Copy the files tracks/config/database.yml.tmpl and tracks/config/settings.yml.tmpl to the same file names without the *.tmpl extension (i.e. the extension should just be .yml). -* Copy the log.tmpl directory to log -* Fill in the correct details in database.yml and settings.yml, referring to the old copies in tracks-old if necessary. Note that there are some new fields to be added in settings.yml, so make sure that you get a fresh copy, or you'll get errors. +* Make sure that you check settings.yml.tmpl for new info, and add any new fields to your settings.yml file. Some new settings have been added in the past couple of versions, and not having the correct settings is a common cause of errors. +* Before you do anything else, BACK UP YOUR DATABASE (tables and content). Then make a separate export of the contents only (assuming that you want to move your data to the new version.) +* If you are using MySQL or Postgresql, you can use the new Rakefile rake migrate task to update your tables. At your command line: + + cd /PATHTO/TRACKS + rake migrate + +* If this process reports errors that you can't fix, you'll need to adapt the instructions for manually loading the schema, given below for SQLite (schemas are also provided for MySQL and Postgresql). +* Import your old contents, and check that it looks sensible. In particular, check that the 'user_id' field in the todos, contexts and projects tables have the value of '1' (i.e. they are owned by your admin user, who should have an id of 1). +* Check that the path to Ruby is correct in the tracks/public/dispatch.* files, and also /script/server. The default (#!/usr/bin/ruby) is fine for Mac OS X Tiger, but if you've installed Ruby yourself in /usr/local/bin, you'll need to change it. +* From here, follow the remaining steps for new users above to start the server. Don't forget that if you've deleted your users table, you'll need 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, and if you are able, create a new database for the new version. If you can't create a new database, delete the contents and tables in your old one MAKING SURE THAT YOU HAVE BACKED UP YOUR DATABASE FIRST. +* If you're using SQLite/SQLite3, you'll need to create a new database and import the new schema (db/tracks_1.031_sqlite.sql), and then import your old contents. You need to check that the new fields have sensible contents. In particular, check that the 'user_id' field in the todos, contexts and projects tables have the value of '1' (i.e. they are owned by your admin user, who should have an id of 1). Use db/tracks_1.0.3_content.sql as a guide for the correct syntax. +sure that you get a fresh copy, or you'll get errors. * Check that the path to Ruby is correct in the tracks/public/dispatch.* files, and also /script/server. The default (#!/usr/bin/ruby) is fine for Mac OS X Tiger, but if you've installed Ruby yourself in /usr/local/bin, you'll need to change it. * From here, follow the remaining steps for new users above to start the server. Don't forget that if you've deleted your users table, you'll need 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. == Using databases other than MySQL -Rick Bradley kindly converted the MySQL schema for Tracks to Postgresql format, so I was able to use that as a model for the new version - see tracks/db/tracks_1.0.3_postgres.sql. There's also a schema for SQLite/SQLite3 (tracks/db/tracks_1.0.3_sqlite.sql). Remember that you'll also need to change the adapter line in database.yml: +Rick Bradley kindly converted the MySQL schema for Tracks to Postgresql format, so I was able to use that as a model for the new version - see tracks/db/tracks_1.031_postgres.sql. There's also a schema for SQLite/SQLite3 (tracks/db/tracks_1.031_sqlite.sql). Remember that you'll also need to change the adapter line in database.yml: adapter: postgresql or for SQLite3: @@ -70,7 +89,7 @@ If you're using SQLite 2.x, substitute 'sqlite' for 'sqlite3' above. Also note t == 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.12.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.12.1 ('Routes' in environment/routes.rb) mean that very little configuration is needed. +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. === Apache