-
- mysql -uroot -p
- mysql> CREATE DATABASE tracks15;
- mysql> GRANT ALL PRIVILEGES ON tracks15.* TO yourmysqluser@localhost \
- IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION;
-
-
-
-### Configure variables [config] ###
-
-1. Open the file `/config/database.yml` and edit the `production:` section with the details of your database. If you are using MySQL the `adapter:` line should read `adapter: mysql`, `host: localhost` (in the majority of cases), and your username and password should match those you assigned when you created the database. If you are using SQLite3, you should have only two lines under the production section: `adapter: sqlite3` and `database: db/tracks-15.db`.
-2. Open the file `/config/environment.rb`, and read through the settings to make sure that they suit your setup. In most cases, all you need to change is the `SALT = "change-me"` line (change the string "change-me" to some other string of your choice), and the time zone setting.
-3. If you downloaded Tracks 1.5 via Subversion, you need to duplicate the files `database.yml.tmpl` and `environment.yml.tmpl` and remove the `*.tmpl` extension from the duplicates. Similarly, duplicate `/log.tmpl` and remove the `*.tmpl` extension, then edit the files as described in steps 1 and 2 above.
-4. If you are using Windows, you may need to check the 'shebang' lines (`#!/usr/bin/env ruby`) 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` to point to the Ruby binary on your system.
-
-### Populate your database with the Tracks 1.5 schema [rake] ###
-
-Open a terminal and change into the root of your Tracks 1.5 directory. Enter the following command:
-
-`rake db:migrate RAILS_ENV=production`
-
-This will update your database with the required schema for Tracks 1.5. If you are using SQLite3, it is not strictly necessary, because the SQLite3 database included with Tracks already has the schema included in it, but it should not do any harm to run the command (nothing will happen if it is up to date).
-
-### Start the server [startserver] ###
-
-While still in the Terminal inside the Tracks 1.5 root directory, issue the following command:
-
-`script/server -e production`
-
-If all goes well, you should see some text informing you that the Mongrel server is running: `** Mongrel available at 0.0.0.0:3000`. If you are already running other services on port 3000, you need to select a different port when running the server, using the `-p` option. You can stop the server again by the key combination Ctrl-C.
-
-### Visit Tracks in a browser [signup] ###
-
-Visit `http://0.0.0.0:3000/signup` in a browser (or whatever URL and port was reported when you started the server in the step above) and chose a user name and password for admin user. Once logged in as admin, you can add other (ordinary level) users.
-
-### Customise Tracks [customise] ###
-
-Once logged in, add some Contexts and Projects, and then go ahead and add your actions. You might also want to visit the Preferences page to edit various settings to your liking. Have fun!
diff --git a/tracks/doc/installing.html b/tracks/doc/manual.html
similarity index 53%
rename from tracks/doc/installing.html
rename to tracks/doc/manual.html
index 2a66fb50..f0bd8821 100644
--- a/tracks/doc/installing.html
+++ b/tracks/doc/manual.html
@@ -6,18 +6,26 @@
+
-
-
- Tracks 1.5 has been thoroughly beta tested by a large number of people, and should be fully stable for everyday use. However, once set up, Tracks will contain the majority of your plans for your work and personal life, so it’s only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in doc/CHANGELOG. Full API documentation can be found at doc/app/index.html, once you have run rake appdoc
~/Sites for Mac OS X users).svn co --username=guest http://www.rousette.org.uk/svn/tracks-repos/tags/current tracks
+
+ svn co --username=guest
+ http://www.rousette.org.uk/svn/tracks-repos/tags/current tracks
+
+
+
+The Tracks interface is accessed through a web browser, so you need to run a webserver to serve the Tracks pages up to you. This isn’t as daunting as it sounds, however: Tracks ships with a built-in web server called Mongrel which you can run on your own computer to serve the Tracks application locally. If you want to be able to access Tracks from any computer connected to the Internet, then you need to install Tracks on a publicly accessible server, and you will probably be better off using a more robust server such as Apache or Lighttpd to serve the pages, particularly if it will be used by many people.
Tracks stores its data in a database, and you can either use SQLite3, MySQL or PostgreSQL. SQLite3 is the best choice for a single user (or a small number of users) on a local installation, while MySQL or PostgreSQL is better for multiple users on a remote installation.
-This is the easiest solution for Mac OS X 10.4 or Windows users wanting to run Tracks locally.
@@ -44,7 +58,7 @@If you don’t want to (or can’t) use one of the all in one installations, you’ll need to install a few things, depending on your platform and your needs.
@@ -62,30 +76,32 @@sqlite3-ruby gem, as described in step 2, and the SQLite3 libraries and binary (see sqlite.org for downloads and installation instructions). If you want to use MySQL, download and install a package for your platform from MySQL.com. The basic steps for Postgresql should be similar to those for MySQL, but they will not be discussed further here.This description is intended for people installing Tracks from scratch. If you would like to upgrade an existing installation, please see Upgrading to Tracks 1.5.
Unzip the package and move Tracks into the directory you want to run it from. For example, for Mac OS X users, ~/Sites is a good choice.
Before you go any further, you need to decide which database you will use. See the What you need to install section for details on installing the required components for you choice of database.
/db in the next step, Configure variables./db in the next step, Configure variables.database.yml.tmpl and environment.yml.tmpl and remove the *.tmpl extension from the duplicates. Similarly, duplicate /log.tmpl and remove the *.tmpl extension, then edit the files as described in steps 2 and 3./config/database.yml and edit the production: section with the details of your database. If you are using MySQL the adapter: line should read adapter: mysql, host: localhost (in the majority of cases), and your username and password should match those you assigned when you created the database. If you are using SQLite3, you should have only two lines under the production section: adapter: sqlite3 and database: db/tracks-15.db./config/environment.rb, and read through the settings to make sure that they suit your setup. In most cases, all you need to change is the SALT = "change-me" line (change the string “change-me” to some other string of your choice), and the time zone setting.database.yml.tmpl and environment.yml.tmpl and remove the *.tmpl extension from the duplicates. Similarly, duplicate /log.tmpl and remove the *.tmpl extension, then edit the files as described in steps 1 and 2 above.#!/usr/bin/env ruby) 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 to point to the Ruby binary on your system.Open a terminal and change into the root of your Tracks 1.5 directory. Enter the following command:
@@ -115,7 +131,7 @@This will update your database with the required schema for Tracks 1.5. If you are using SQLite3, it is not strictly necessary, because the SQLite3 database included with Tracks already has the schema included in it, but it should not do any harm to run the command (nothing will happen if it is up to date).
-While still in the Terminal inside the Tracks 1.5 root directory, issue the following command:
@@ -123,12 +139,95 @@If all goes well, you should see some text informing you that the Mongrel server is running: ** Mongrel available at 0.0.0.0:3000. If you are already running other services on port 3000, you need to select a different port when running the server, using the -p option. You can stop the server again by the key combination Ctrl-C.
Visit http://0.0.0.0:3000/signup in a browser (or whatever URL and port was reported when you started the server in the step above) and chose a user name and password for admin user. Once logged in as admin, you can add other (ordinary level) users.
Once logged in, add some Contexts and Projects, and then go ahead and add your actions. You might also want to visit the Preferences page to edit various settings to your liking. Have fun!
+ +TODO: Instructions for upgrading from a version earlier than 1.043
+ +This should be a relatively straightforward, and involves the following main steps:
+ +rake db:migrate RAILS_ENV=production to update your old database to the new schema – you did back up your database didn’t you?script/server inside your Tracks 1.5 directory to start up Tracks 1.5.It’s very important that you back up your database before you start the upgrade process. It’s always possible for things to go wrong with the database update, and you don’t want to lose any data. If you are using SQLite3 and you are leaving your old Tracks directory in place, then you don’t need to do anything. However, there is no harm in taking extra precautions and copying your database from /db to a safe location as an extra backup, or making a dump of the schema and contents. You will never regret making too many backups! If you are using MySQL, make a SQL dump of your database, replacing the terms in square brackets with the correct information for your setup:
mysqldump –-user [user name] –-password=[password] [database name] > [dump file]
Rename your old Tracks installation (e.g. to ‘tracks-old’) so that you can install Tracks 1.5 along side it.
+ +There are two methods of downloading Tracks 1.5:
+ +~/Sites for Mac OS X users).
+
+ svn co --username=guest \
+ http://www.rousette.org.uk/svn/tracks-repos/tags/current tracks
+
+
+
+There are a few files you need to copy over from your old installation. If you copy them over rather than moving them, you can still run your old version of Tracks if anything goes awry with the installation process.
+ +/config/database.yml from your old Tracks directory to the same location in the new one. Double check that the information there is still correct./config/environment.rb.tmpl in the Tracks 1.5 directory, and rename the file to environment.rb. Open the file and alter the line SALT = "change-me" so that it matches what you had in this file in your old installation. You may also want to change the time zone setting as appropriate for your location (ENV['TZ'] = 'US/Eastern'). If you have made any other customisations to environment.rb in the past, copy those over, but the contents of the file have changed quite a lot since 1.043, so check it carefully./log directory over from your old installation to the root of the new one, or just rename /log.tmpl to log to start afresh./db in your old Tracks directory to the same location in the new one.#!/usr/bin/env ruby)1 of the /public/dispatch.* files and all the files in the /script directory. They are set to #!/usr/bin/env ruby by default. Check the format of those lines in your old installation, and change the new ones as necessary.In a terminal, change directories so that you are inside the Tracks 1.5 directory. Then issue the command:
+ +rake db:migrate RAILS_ENV=production
Watch the output carefully for errors, but it should report at the end of the process that everything worked OK. If you do get errors, you’ll have to fix them before you proceed any further. Running rake with the --trace option can help to track down the problem.
If you’re still in the Tracks 1.5 root directory in a terminal, enter the following command to start up Tracks in production mode:
+ +script/server -e production
Visit the URL indicated by the output (e.g. ** Mongrel available at 0.0.0.0:3000
+) in a browser, and with any luck, you should be able to log in and find all your actions as you left them!
Once you’re certain that your new Tracks 1.5 installation is working perfectly, you can delete your old Tracks directory.
+ +The env binary helps to locate other binaries, regardless of their location. If you don’t have env installed, you’ll need to change this line to point to the location of your Ruby binary. ↩