@@ -24,7 +24,7 @@ cd tracks <h4>Easy installation options</h4> -There are a few easy options if you are not confident about installing Tracks from source using these instructions. If you'd like to install Tracks on a local machine, try "BitNami":http://bitnami.org/stack/tracks -- it runs on Windows, Mac OS X and Linux. Alternatively, you could try "JumpBox":http://www.jumpbox.com/, who provide a "JumpBox for Tracks 1.7":http://www.jumpbox.com/app/tracks. JumpBoxes are pre-built, pre-configured virtual applications which run in a range of "Virtualization software applications":http://www.jumpbox.com/supported-virtualization-software. You just download the JumpBox (free), then open the file with your Virtualization software. Once the JumpBox has booted, it will give you a URL which you can visit in a browser. The software will then guide you through setting up an account. If you'd like to try out the JumpBox without installing it, you can use the 'Trial This JumpBox' button on the web site, which will let you play around with it to test it out. Furthermore, there is a free public AMI available for Amazon EC2. Just use any EC2 client and search for Tracks. This works in exactly the same way as the downloaded JumpBox you can easily migrate from a downloaded installation to an EC2 instance or back using the backup system of the JumpBox. +There are a few easy options if you are not confident about installing Tracks from source using these instructions. If you'd like to install Tracks on a local machine, try "BitNami":http://bitnami.org/stack/tracks -- it runs on Windows, Mac OS X and Linux. Alternatively, you could try "JumpBox (Affliate link)":http://www.shareasale.com/r.cfm?u=188858&b=179734&m=22742&afftrack=&urllink=www%2Ejumpbox%2Ecom, who provide a "JumpBox for Tracks 1.7 (Affiliate link)":http://www.shareasale.com/r.cfm?u=188858&b=179734&m=22742&afftrack=&urllink=www%2Ejumpbox%2Ecom%2Fapp%2Ftracks. JumpBoxes are pre-built, pre-configured virtual applications which run in a range of "Virtualization software applications":http://www.jumpbox.com/supported-virtualization-software. You just download the JumpBox (free), then open the file with your Virtualization software. Once the JumpBox has booted, it will give you a URL which you can visit in a browser. The software will then guide you through setting up an account. If you'd like to try out the JumpBox without installing it, you can use the 'Trial This JumpBox' button on the web site, which will let you play around with it to test it out. Furthermore, there is a free public AMI available for Amazon EC2. Just use any EC2 client and search for Tracks. This works in exactly the same way as the downloaded JumpBox you can easily migrate from a downloaded installation to an EC2 instance or back using the backup system of the JumpBox. If you'd like an easy way to access Tracks from any internet-connected computer, sign up for a free account at "Morph eXchange":http://www.morphexchange.com/. Sign up for a free account, then click on "See all available subscriptions" and you'll see Tracks listed as an application. Just subscribe to Tracks and you can get started. This option is recommended for those with little technical know-how. content/chapter/2-installation.txt @@ -21,7 +21,7 @@ filter: erb <div class="container"> <div class="column span-24 first last" id="header"> - <h1><img src="/assets/tracks-logo.png" /></h1> + <h1><img src="http://getontracks.org/doc/assets/tracks-logo.png" /></h1> </div> <div class="column span-15 append-1 first"> layouts/printed.txt @@ -58,29 +58,17 @@ </ul> </div> - <h2> Introduction</h2> - - - <p>Tracks is a web application that is specifically designed to implement the Getting Things Done &trade; (GTD) methods. That doesn&#8217;t mean that you can&#8217;t use it for other kinds of todo tracking. Data is stored in a database (either MySQL, Postgresql or SQLite), and viewed in a web browser via a web server (Apache, Lighttpd or Mongrel among others). This makes it cross-platform as well as being accessible from anywhere that you have web access.</p> - - - <p>Using the GTD method as a model, there are three main components to Tracks: Next actions, Contexts and Projects.</p> - - - <ul> + <h2>Introduction</h2> +<p>Tracks is a web application that is specifically designed to implement the Getting Things Done &trade; (GTD) methods. That doesn&#8217;t mean that you can&#8217;t use it for other kinds of todo tracking. Data is stored in a database (either MySQL, Postgresql or SQLite), and viewed in a web browser via a web server (Apache, Lighttpd or Mongrel among others). This makes it cross-platform as well as being accessible from anywhere that you have web access.</p> +<p>Using the GTD method as a model, there are three main components to Tracks: Next actions, Contexts and Projects.</p> +<ul> <li><strong>Next Actions</strong>: These are the heart of GTD. They are the very next physical action that can be taken on something. It&#8217;s best to phrase these in an active way e.g. &#8220;Call Bob about the committee meeting&#8221; or &#8220;Search for a reputable garage&#8221;.</li> - <li><strong>Contexts</strong>: Contexts are very flexible, and can be places, states of mind or modes of working in which actions can be taken. Next actions can be assigned to and sorted by context so that you know when you are able to make progress with items. e.g. &#8220;Library&#8221;, &#8220;Shops&#8221; or &#8220;Tired&#8221;.</li> - <li><strong>Projects</strong>: any goal which requires more than one next action to take it to completion is a Project. In Tracks, you can view your next actions by Project.</li> - </ul> - - - <p>Tracks 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&#8217;s only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in <code>doc/CHANGELOG</code>. Full API documentation can be found at <code>doc/app/index.html</code>, once you have run <code>rake appdoc</code>.</p> - - - <h3>About this manual</h3> - - - <p>The source for this manual is kept in a <a href="http://github.com/bsag/tracks_manual/tree">GitHub repository</a>, and this is pulled as a submodule into the doc/manual subdirectory of the main <a href="http://github.com/bsag/tracks/tree">Tracks repository</a>. The source is maintained using <a href="http://webby.rubyforge.org/">Webby</a> to create the HTML (deployed to the Tracks site), and <a href="http://www.princexml.com/">Prince XML</a> is used to convert the HTML to PDF.</p> + <li><strong>Contexts</strong>: Contexts are very flexible, and can be places, states of mind or modes of working in which actions can be taken. Next actions can be assigned to and sorted by context so that you know when you are able to make progress with items. e.g. &#8220;Library&#8221;, &#8220;Shops&#8221; or &#8220;Tired&#8221;.</li> + <li><strong>Projects</strong>: any goal which requires more than one next action to take it to completion is a Project. In Tracks, you can view your next actions by Project.</li> +</ul> +<p>Tracks 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&#8217;s only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in <code>doc/CHANGELOG</code>. Full API documentation can be found at <code>doc/app/index.html</code>, once you have run <code>rake appdoc</code>.</p> +<h3>About this manual</h3> +<p>The source for this manual is kept in a <a href="http://github.com/bsag/tracks_manual/tree">GitHub repository</a>, and this is pulled as a submodule into the doc/manual subdirectory of the main <a href="http://github.com/bsag/tracks/tree">Tracks repository</a>. The source is maintained using <a href="http://webby.rubyforge.org/">Webby</a> to create the HTML (deployed to the Tracks site), and <a href="http://www.princexml.com/">Prince XML</a> is used to convert the HTML to PDF.</p> </div> <div class="column span-8 last" id="sidebar"> output/chapter/1-introduction.html @@ -59,163 +59,87 @@ </ul> </div> <h2>Installing Tracks</h2> - - - <h3>Getting Tracks</h3> - - - <p>There are two methods of downloading Tracks:</p> - - - <ol> +<h3>Getting Tracks</h3> +<p>There are two methods of downloading Tracks:</p> +<ol> <li>(Recommended for most people) Download the <a href="http://bsag.bingodisk.com/public/files/tracks-current.zip">zipped package</a>, and unzip in your preferred location (e.g. <code>~/Sites</code> for Mac OS X users).</li> - <li>If you want to live on the edge, you can get the latest development version from GitHub using git (bear in mind that this may be less stable than the released versions):</li> - </ol> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> cd <span class="Keyword">~</span>/Sites -<span class="line-numbers"> 2 </span> git clone git://github.com/bsag/tracks.git -<span class="line-numbers"> 3 </span> cd tracks -</pre></div> - -<h4>Easy installation options</h4> - - <p>There are a few easy options if you are not confident about installing Tracks from source using these instructions. If you&#8217;d like to install Tracks on a local machine, try <a href="http://bitnami.org/stack/tracks">BitNami</a>&#8212;it runs on Windows, Mac OS X and Linux. Alternatively, you could try <a href="http://www.jumpbox.com/">JumpBox</a>, who provide a <a href="http://www.jumpbox.com/app/tracks">JumpBox for Tracks 1.7</a>. JumpBoxes are pre-built, pre-configured virtual applications which run in a range of <a href="http://www.jumpbox.com/supported-virtualization-software">Virtualization software applications</a>. You just download the JumpBox (free), then open the file with your Virtualization software. Once the JumpBox has booted, it will give you a URL which you can visit in a browser. The software will then guide you through setting up an account. If you&#8217;d like to try out the JumpBox without installing it, you can use the &#8216;Trial This JumpBox&#8217; button on the web site, which will let you play around with it to test it out. Furthermore, there is a free public AMI available for Amazon EC2. Just use any EC2 client and search for Tracks. This works in exactly the same way as the downloaded JumpBox you can easily migrate from a downloaded installation to an EC2 instance or back using the backup system of the JumpBox.</p> - - - <p>If you&#8217;d like an easy way to access Tracks from any internet-connected computer, sign up for a free account at <a href="http://www.morphexchange.com/">Morph eXchange</a>. Sign up for a free account, then click on &#8220;See all available subscriptions&#8221; and you&#8217;ll see Tracks listed as an application. Just subscribe to Tracks and you can get started. This option is recommended for those with little technical know-how.</p> - - - <h4> Requirements</h4> - - - <p>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&#8217;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 <a href="http://www.apache.org/">Apache</a> or <a href="http://www.lighttpd.net/">Lighttpd</a> to serve the pages, particularly if it will be used by many people.</p> - - - <p>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.</p> - - - <h4> What is included with the Tracks package?</h4> - - - <ol> + <li>If you want to live on the edge, you can get the latest development version from GitHub using git (bear in mind that this may be less stable than the released versions):</li> +</ol> +<h4><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> cd <span class="Keyword">~</span>/Sites<br /> +<span class="line-numbers"> 2 </span> git clone git://github.com/bsag/tracks.git<br /> +<span class="line-numbers"> 3 </span> cd tracks<br /> +</pre></div><br /> +Easy installation options</h4> +<p>There are a few easy options if you are not confident about installing Tracks from source using these instructions. If you&#8217;d like to install Tracks on a local machine, try <a href="http://bitnami.org/stack/tracks">BitNami</a> &#8212; it runs on Windows, Mac OS X and Linux. Alternatively, you could try <a href="http://www.shareasale.com/r.cfm?u=188858&amp;b=179734&amp;m=22742&amp;afftrack=&amp;urllink=www%2Ejumpbox%2Ecom" title="Affliate link">JumpBox</a>, who provide a <a href="http://www.shareasale.com/r.cfm?u=188858&amp;b=179734&amp;m=22742&amp;afftrack=&amp;urllink=www%2Ejumpbox%2Ecom%2Fapp%2Ftracks" title="Affiliate link">JumpBox for Tracks 1.7</a>. JumpBoxes are pre-built, pre-configured virtual applications which run in a range of <a href="http://www.jumpbox.com/supported-virtualization-software">Virtualization software applications</a>. You just download the JumpBox (free), then open the file with your Virtualization software. Once the JumpBox has booted, it will give you a URL which you can visit in a browser. The software will then guide you through setting up an account. If you&#8217;d like to try out the JumpBox without installing it, you can use the &#8216;Trial This JumpBox&#8217; button on the web site, which will let you play around with it to test it out. Furthermore, there is a free public AMI available for Amazon EC2. Just use any EC2 client and search for Tracks. This works in exactly the same way as the downloaded JumpBox you can easily migrate from a downloaded installation to an EC2 instance or back using the backup system of the JumpBox.</p> +<p>If you&#8217;d like an easy way to access Tracks from any internet-connected computer, sign up for a free account at <a href="http://www.morphexchange.com/">Morph eXchange</a>. Sign up for a free account, then click on &#8220;See all available subscriptions&#8221; and you&#8217;ll see Tracks listed as an application. Just subscribe to Tracks and you can get started. This option is recommended for those with little technical know-how.</p> +<h4>Requirements</h4> +<p>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&#8217;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 <a href="http://www.apache.org/">Apache</a> or <a href="http://www.lighttpd.net/">Lighttpd</a> to serve the pages, particularly if it will be used by many people.</p> +<p>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.</p> +<h4>What is included with the Tracks package?</h4> +<ol> <li>Tracks itself</li> - <li>Rails 2.2.2 (installed in the <code>/vendor/rails</code> directory, so you do not need to install Rails yourself)</li> - <li>An empty SQLite3 database, set up with the correct database schema</li> - </ol> - - - <h4> What you need to install</h4> - - - <p>If you don&#8217;t want to (or can&#8217;t) use one of the all in one installations, you&#8217;ll need to install a few things, depending on your platform and your needs.</p> - - - <ol> + <li>Rails 2.2.2 (installed in the <code>/vendor/rails</code> directory, so you do not need to install Rails yourself)</li> + <li>An empty SQLite3 database, set up with the correct database schema</li> +</ol> +<h4>What you need to install</h4> +<p>If you don&#8217;t want to (or can&#8217;t) use one of the all in one installations, you&#8217;ll need to install a few things, depending on your platform and your needs.</p> +<ol> <li><strong>Ruby</strong>. Version 1.8.6 or 1.8.7 is recommended, but it is also possible to use 1.8.5, 1.8.4 and 1.8.2. Note that 1.8.3 is not compatible. If you are running Mac OS X Leopard, you already have Ruby 1.8.6 installed by default, so you have nothing to do here. You can get the source to compile yourself <a href="http://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.6.tar.gz">here</a> for all platforms, or Windows users can use an easy <a href="http://rubyforge.org/frs/?group_id=167">installer</a>. If you&#8217;re using a version of Mac OS X earlier than 10.5.0, it is recommended that you use the <a href="http://hivelogic.com/narrative/articles/ruby-rails-mongrel-mysql-osx">instructions here</a> to install all the Rails dependencies, though you can skip the step to install Rails if you like.</li> - <li><strong>RubyGems</strong>. The gems needed by Rails to interact with the database have to be compiled on the platform on which they will be run, so we cannot include them with the Tracks package, unlike some other gems. So you will need to <a href="http://rubyforge.org/frs/?group_id=126">download</a> and install RubyGems (run <code>ruby setup.rb</code> after extracting the package). Note that once again, Mac OS X Leopard users get an easy life, because RubyGems and the SQLite3 gem is already installed. Once installed you can use RubyGems to install the gems you need for your database. If you are using SQLite3, run <code>sudo gem install sqlite3-ruby</code>, then select the appropriate package for your platform (version 1.2.1 recommended). You can use MySQL without installing a gem, but installing the gem can speed things up a bit: <code>sudo gem install mysql</code>. If you&#8217;re using Leopard, there are a few work-arounds necessary, which are explained on <a href="http://trac.macosforge.org/projects/ruby/wiki/Troubleshooting#IcannotbuildrubymysqlonLeopardwithmysql.combinaries">Mac OS Forge</a>. The ruby-mysql bindings can sometimes be a bit troublesome to install, so to be honest, it&#8217;s probably not worth the bother unless you are trying to wring maximum speed out of your system. If you are using PostgreSQL, then you can install a postgres gem: <code>gem install postgres</code>.</li> - <li><strong>Database</strong>. The easiest option is to use SQLite3, as the database is included in the package. All you need then is the <code>sqlite3-ruby</code> gem, as described in step 2, and the SQLite3 libraries and binary (see <a href="http://sqlite.org/download.html">sqlite.org</a> for downloads and installation instructions). If you want to use MySQL, download and install a package for your platform from <a href="http://dev.mysql.com/downloads/mysql/5.0.html">MySQL.com</a>. The basic steps for Postgresql should be similar to those for MySQL, but they will not be discussed further here.</li> - <li><strong>Rake</strong> You will need rake to install and upgrade Tracks. If it is not installed on your system, use <code>sudo gem install rake</code> to install it.</li> - </ol> - - - <p>You can find several installation howtos for specific setups <a href="http://www.getontracks.org/wiki/Installation-Index/">here</a>. They were contributed by various Tracks users.</p> - - - <h3> Installation</h3> - - - <p>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.7.</p> - - - <ol> + <li><strong>RubyGems</strong>. The gems needed by Rails to interact with the database have to be compiled on the platform on which they will be run, so we cannot include them with the Tracks package, unlike some other gems. So you will need to <a href="http://rubyforge.org/frs/?group_id=126">download</a> and install RubyGems (run <code>ruby setup.rb</code> after extracting the package). Note that once again, Mac OS X Leopard users get an easy life, because RubyGems and the SQLite3 gem is already installed. Once installed you can use RubyGems to install the gems you need for your database. If you are using SQLite3, run <code>sudo gem install sqlite3-ruby</code>, then select the appropriate package for your platform (version 1.2.1 recommended). You can use MySQL without installing a gem, but installing the gem can speed things up a bit: <code>sudo gem install mysql</code>. If you&#8217;re using Leopard, there are a few work-arounds necessary, which are explained on <a href="http://trac.macosforge.org/projects/ruby/wiki/Troubleshooting#IcannotbuildrubymysqlonLeopardwithmysql.combinaries">Mac OS Forge</a>. The ruby-mysql bindings can sometimes be a bit troublesome to install, so to be honest, it&#8217;s probably not worth the bother unless you are trying to wring maximum speed out of your system. If you are using PostgreSQL, then you can install a postgres gem: <code>gem install postgres</code>.</li> + <li><strong>Database</strong>. The easiest option is to use SQLite3, as the database is included in the package. All you need then is the <code>sqlite3-ruby</code> gem, as described in step 2, and the SQLite3 libraries and binary (see <a href="http://sqlite.org/download.html">sqlite.org</a> for downloads and installation instructions). If you want to use MySQL, download and install a package for your platform from <a href="http://dev.mysql.com/downloads/mysql/5.0.html">MySQL.com</a>. The basic steps for Postgresql should be similar to those for MySQL, but they will not be discussed further here.</li> + <li><strong>Rake</strong> You will need rake to install and upgrade Tracks. If it is not installed on your system, use <code>sudo gem install rake</code> to install it.</li> +</ol> +<p>You can find several installation howtos for specific setups <a href="http://www.getontracks.org/wiki/Installation-Index/">here</a>. They were contributed by various Tracks users.</p> +<h3>Installation</h3> +<p>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.7.</p> +<ol> <li>Unzip tracks and install in a directory</li> - <li>Decide on a database to use - <ol> - <li> SQLite3 &#8211; change database.yml to point to SQLite3 database. Make sure you add the complete path to the database</li> - <li> MySQL &#8211; create new MySQL db and grant all privileges </li> - </ol> - </li> - <li>Configure some variables</li> - <li>Populate the database with the Tracks 1.7 schema</li> - <li>Start the server</li> - <li>Visit Tracks in a browser</li> - <li>Customise Tracks</li> - </ol> - - - <h4> Unzip Tracks and install</h4> - - - <p>Unzip the package and move Tracks into the directory you want to run it from. For example, for Mac OS X users, <code>~/Sites</code> is a good choice.</p> - - - <h4> Decide on a database</h4> - - - <p>Before you go any further, you need to decide which database you will use. See the &#8216;What you need to install&#8217; section for details on installing the required components for you choice of database.</p> - - + <li>Decide on a database to use <ol> + <li>SQLite3 &#8211; change database.yml to point to SQLite3 database. Make sure you add the complete path to the database</li> + <li>MySQL &#8211; create new MySQL db and grant all privileges</li> + </ol></li> + <li>Configure some variables</li> + <li>Populate the database with the Tracks 1.7 schema</li> + <li>Start the server</li> + <li>Visit Tracks in a browser</li> + <li>Customise Tracks</li> +</ol> +<h4>Unzip Tracks and install</h4> +<p>Unzip the package and move Tracks into the directory you want to run it from. For example, for Mac OS X users, <code>~/Sites</code> is a good choice.</p> +<h4>Decide on a database</h4> +<p>Before you go any further, you need to decide which database you will use. See the &#8216;What you need to install&#8217; section for details on installing the required components for you choice of database.</p> +<ol> <li><strong>SQLite3</strong>. All you need to do is make sure that you point Tracks to the included SQLite3 database in <code>/db</code> in the next step, &#8216;Configure variables&#8217;.</li> - <li><strong>MySQL</strong>. Once you have MySQL installed, you need to create a database and database-user to use with Tracks 1.7. For this, you can use MySQL Administrator or go into a terminal and issue the following commands:</li> - </ol> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> mysql -uroot -p -<span class="line-numbers"> 2 </span> mysql&gt; CREATE DATABASE tracks; -<span class="line-numbers"> 3 </span> mysql&gt; <span class="Keyword">GRANT</span> ALL PRIVILEGES <span class="Keyword">ON </span>tracks.* TO yourmysqluser@localhost \ -<span class="line-numbers"> 4 </span> IDENTIFIED BY <span class="String"><span class="String">'</span>password-goes-here'</span> WITH <span class="Keyword">GRANT</span> OPTION; -</pre></div> - - - <h4> Configure variables</h4> - - - <ol> + <li><strong>MySQL</strong>. Once you have MySQL installed, you need to create a database and database-user to use with Tracks 1.7. For this, you can use MySQL Administrator or go into a terminal and issue the following commands:</li> +</ol> +<h4><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> mysql -uroot -p<br /> +<span class="line-numbers"> 2 </span> mysql&gt; CREATE DATABASE tracks;<br /> +<span class="line-numbers"> 3 </span> mysql&gt; <span class="Keyword">GRANT</span> ALL PRIVILEGES <span class="Keyword">ON </span>tracks.* TO yourmysqluser@localhost \<br /> +<span class="line-numbers"> 4 </span> IDENTIFIED BY <span class="String"><span class="String">&#8216;</span>password-goes-here&#8217;</span> WITH <span class="Keyword">GRANT</span> OPTION;<br /> +</pre></div><br /> +<br /> +Configure variables</h4> +<ol> <li>If you downloaded Tracks 1.7 via GitHub, you need to duplicate the files <code>database.yml.tmpl</code> and <code>site.yml.tmpl</code> and remove the <code>*.tmpl</code> extension from the duplicates. Similarly, duplicate <code>/log.tmpl</code> and remove the <code>*.tmpl</code> extension, then edit the files as described in steps 2 and 3.</li> - <li>Open the file <code>/config/database.yml</code> and edit the <code>production:</code> section with the details of your database. If you are using MySQL the <code>adapter:</code> line should read <code>adapter: mysql</code>, <code>host: localhost</code> (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: <code>adapter: sqlite3</code> and <code>database: db/tracks-17-blank.db</code>. If you downloaded the zipped file, the database.yml file is already configured to use the provided SQLite3 file.</li> - <li>Open the file <code>/config/site.yml</code>, and read through the settings to make sure that they suit your setup. In most cases, all you need to change is the <code>salt: "change-me"</code> line (change the string &#8220;change-me&#8221; to some other string of your choice), and the time zone setting. For the time zone setting you can use the command <code>rake time:zones:local</code> to see all available timezones on your machine</li> - <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. This should work for all Unix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like <code>#c:/ruby/bin/ruby</code> to point to the Ruby binary on your system.</li> - </ol> - - - <h4> Populate your database with the Tracks 1.7 schema</h4> - - - <p>Open a terminal and change into the root of your Tracks 1.7 directory. Enter the following command:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> rake db<span class="Constant"><span class="Constant">:</span>migrate</span> <span class="Variable">RAILS_ENV</span><span class="Keyword">=</span>production -</pre></div> - -This will update your database with the required schema for Tracks 1.7. 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). - - <h4> Start the server</h4> - - - <p>While still in the Terminal inside the Tracks 1.7 root directory, issue the following command:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> script<span class="Keyword">/</span>server <span class="Keyword">-</span>e production -</pre></div> - -If all goes well, you should see some text informing you that the Mongrel server is running: <code>** Mongrel available at 0.0.0.0:3000</code>. If you are already running other services on port 3000, you need to select a different port when running the server, using the <code>-p</code> option. You can stop the server again by the key combination Ctrl-C. - - <h4> Visit Tracks in a browser</h4> - - - <p>Visit <code>http://0.0.0.0:3000/signup</code> 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. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</p> - - - <h4> Customise Tracks</h4> - - - <p>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!</p> + <li>Open the file <code>/config/database.yml</code> and edit the <code>production:</code> section with the details of your database. If you are using MySQL the <code>adapter:</code> line should read <code>adapter: mysql</code>, <code>host: localhost</code> (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: <code>adapter: sqlite3</code> and <code>database: db/tracks-17-blank.db</code>. If you downloaded the zipped file, the database.yml file is already configured to use the provided SQLite3 file.</li> + <li>Open the file <code>/config/site.yml</code>, and read through the settings to make sure that they suit your setup. In most cases, all you need to change is the <code>salt: "change-me"</code> line (change the string &#8220;change-me&#8221; to some other string of your choice), and the time zone setting. For the time zone setting you can use the command <code>rake time:zones:local</code> to see all available timezones on your machine</li> + <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. This should work for all Unix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like <code>#c:/ruby/bin/ruby</code> to point to the Ruby binary on your system.</li> +</ol> +<h4>Populate your database with the Tracks 1.7 schema</h4> +<p>Open a terminal and change into the root of your Tracks 1.7 directory. Enter the following command:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> rake db<span class="Constant"><span class="Constant">:</span>migrate</span> <span class="Variable">RAILS_ENV</span><span class="Keyword">=</span>production<br /> +</pre></div><br /> +This will update your database with the required schema for Tracks 1.7. 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).</p> +<h4>Start the server</h4> +<p>While still in the Terminal inside the Tracks 1.7 root directory, issue the following command:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> script<span class="Keyword">/</span>server <span class="Keyword">-</span>e production<br /> +</pre></div><br /> +If all goes well, you should see some text informing you that the Mongrel server is running: <code>** Mongrel available at 0.0.0.0:3000</code>. If you are already running other services on port 3000, you need to select a different port when running the server, using the <code>-p</code> option. You can stop the server again by the key combination Ctrl-C.</p> +<h4>Visit Tracks in a browser</h4> +<p>Visit <code>http://0.0.0.0:3000/signup</code> 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. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</p> +<h4>Customise Tracks</h4> +<p>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!</p> </div> <div class="column span-8 last" id="sidebar"> @@ -236,7 +160,7 @@ If all goes well, you should see some text informing you that the Mongrel server </div> <div class="column span-24 first last" id="footer"> - <p>Last updated on Mon 04 May 2009 at 19:35 &nbsp; :: &nbsp; Created with <a href="http://webby.rubyforge.org">Webby</a></p> + <p>Last updated on Sun 30 Aug 2009 at 12:13 &nbsp; :: &nbsp; Created with <a href="http://webby.rubyforge.org">Webby</a></p> </div> output/chapter/2-installation.html @@ -58,164 +58,91 @@ </ul> </div> - <h2> Upgrading Tracks</h2> - - - <h3> Upgrading from Tracks 1.7RC2 to Tracks 1.7</h3> - - - <p>There were only a few fixes in the code, so you can consider unzipping the new release over your install of Tracks 1.7RC2. Do make a backup of your Tracks 1.7RC2 install and your database!</p> - - - <p>It is also possible to follow the instructions below and copy your existing Site.yml from your Tracks 1.7RC2 install.</p> - - - <h3> Upgrading from Tracks 1.5, 1.6 or from Tracks 1.7RC1 to Tracks 1.7</h3> - - - <p>In Tracks 1.7 (since RC2) the site specific configuration is moved from <code>environment.rb</code> into the new <code>site.yml</code>. This makes updating <code>environment.rb</code> much easier without you needing to set your site specific settings after each update.</p> - - - <p>After you install Tracks 1.7 there will be no <code>environment.rb.tmpl</code> anymore. You will find an <code>environment.rb</code> which you can leave untouched. Just fill in your settings from your old <code>environment.rb</code> in the new <code>site.yml</code>. If you have made any other customisations to <code>environment.rb</code> in the past, you can put them in your own configuration file (for example, in my-config.rb) in <code>config/initializers</code>. Please let us know it you think they should be in <code>site.yml.tmpl</code></p> - - - <p>Also, there were some database changes made in Tracks 1.7, so you need to migrate to them.</p> - - - <ol> + <h2>Upgrading Tracks</h2> +<h3>Upgrading from Tracks 1.7RC2 to Tracks 1.7</h3> +<p>There were only a few fixes in the code, so you can consider unzipping the new release over your install of Tracks 1.7RC2. Do make a backup of your Tracks 1.7RC2 install and your database!</p> +<p>It is also possible to follow the instructions below and copy your existing Site.yml from your Tracks 1.7RC2 install.</p> +<h3>Upgrading from Tracks 1.5, 1.6 or from Tracks 1.7RC1 to Tracks 1.7</h3> +<p>In Tracks 1.7 (since RC2) the site specific configuration is moved from <code>environment.rb</code> into the new <code>site.yml</code>. This makes updating <code>environment.rb</code> much easier without you needing to set your site specific settings after each update.</p> +<p>After you install Tracks 1.7 there will be no <code>environment.rb.tmpl</code> anymore. You will find an <code>environment.rb</code> which you can leave untouched. Just fill in your settings from your old <code>environment.rb</code> in the new <code>site.yml</code>. If you have made any other customisations to <code>environment.rb</code> in the past, you can put them in your own configuration file (for example, in my-config.rb) in <code>config/initializers</code>. Please let us know it you think they should be in <code>site.yml.tmpl</code></p> +<p>Also, there were some database changes made in Tracks 1.7, so you need to migrate to them.</p> +<ol> <li>Back up your existing database and installation of Tracks</li> - <li>Install Tracks 1.7 in a new directory</li> - <li>Copy over the configuration from your previous Tracks installation (except for environment.rb, see above). If using SQLite3, copy the old database into the new Tracks 1.7 directory.</li> - <li>Run <code>rake db:migrate RAILS_ENV=production</code> to update your old database to the new schema&#8212;you did back up your database didn&#8217;t you?</li> - <li>Run <code>script/server</code> inside your Tracks 1.7 directory to start up Tracks 1.7.</li> - <li>Once you are happy that everything is working well, delete your old Tracks directory.</li> - </ol> - - - <h3> Upgrading from Tracks 1.043 to 1.7</h3> - - - <p>This should be a relatively straightforward, and involves the following main steps:</p> - - - <ol> + <li>Install Tracks 1.7 in a new directory</li> + <li>Copy over the configuration from your previous Tracks installation (except for environment.rb, see above). If using SQLite3, copy the old database into the new Tracks 1.7 directory.</li> + <li>Run <code>rake db:migrate RAILS_ENV=production</code> to update your old database to the new schema &#8212; you did back up your database didn&#8217;t you?</li> + <li>Run <code>script/server</code> inside your Tracks 1.7 directory to start up Tracks 1.7.</li> + <li>Once you are happy that everything is working well, delete your old Tracks directory.</li> +</ol> +<h3>Upgrading from Tracks 1.043 to 1.7</h3> +<p>This should be a relatively straightforward, and involves the following main steps:</p> +<ol> <li>Back up your existing database and installation of Tracks</li> - <li>Install Tracks 1.6 in a new directory</li> - <li>Copy over the configuration from your previous Tracks 1.043 installation. If using SQLite3, copy the old database into the new Tracks 1.7 directory.</li> - <li>Run <code>rake db:migrate RAILS_ENV=production</code> to update your old database to the new schema&#8212;you did back up your database didn&#8217;t you? + <li>Install Tracks 1.6 in a new directory</li> + <li>Copy over the configuration from your previous Tracks 1.043 installation. If using SQLite3, copy the old database into the new Tracks 1.7 directory.</li> + <li>Run <code>rake db:migrate RAILS_ENV=production</code> to update your old database to the new schema &#8212; you did back up your database didn&#8217;t you?<br /> +# Run <code>script/server</code> inside your Tracks 1.7 directory to start up Tracks 1.7.</li> - <li>Once you are happy that everything is working well, delete your old Tracks directory.</li> - </ol> - - - <h3>Detailed steps</h3> - - - <h4> Backing up</h4> - - - <p>It&#8217;s very important that you <strong>back up your database</strong> before you start the upgrade process. It&#8217;s always possible for things to go wrong with the database update, and you don&#8217;t want to lose any data. If you are using SQLite3 and you are leaving your old Tracks directory in place, then you don&#8217;t need to do anything. However, there is no harm in taking extra precautions and copying your database from <code>/db</code> 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:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> mysqldump –-user [user name] –-password=[password] \ -<span class="line-numbers"> 2 </span> [database name] <span class="Keyword">&gt;</span> [dump file] -</pre></div> - -Rename your old Tracks installation (e.g. to &#8216;tracks-old&#8217;) so that you can install Tracks 1.7 along side it. - - <h4> Install the latest version of Tracks</h4> - - - <p>There are two methods of downloading Tracks:</p> - - - <ol> + <li>Once you are happy that everything is working well, delete your old Tracks directory.</li> +</ol> +<h3>Detailed steps</h3> +<h4>Backing up</h4> +<p>It&#8217;s very important that you <strong>back up your database</strong> before you start the upgrade process. It&#8217;s always possible for things to go wrong with the database update, and you don&#8217;t want to lose any data. If you are using SQLite3 and you are leaving your old Tracks directory in place, then you don&#8217;t need to do anything. However, there is no harm in taking extra precautions and copying your database from <code>/db</code> 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:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> mysqldump –-user [user name] –-password=[password] \<br /> +<span class="line-numbers"> 2 </span> [database name] <span class="Keyword">&gt;</span> [dump file]<br /> +</pre></div><br /> +Rename your old Tracks installation (e.g. to &#8216;tracks-old&#8217;) so that you can install Tracks 1.7 along side it.</p> +<h4>Install the latest version of Tracks</h4> +<p>There are two methods of downloading Tracks:</p> +<ol> <li>(Recommended for most people) Download the <a href="http://bsag.bingodisk.com/public/files/tracks_1.7.zip">zipped package</a>, and unzip in your preferred location (e.g. <code>~/Sites</code> for Mac OS X users).</li> - <li>If you want to live on the edge, you can get the latest development version from GitHub using git (bear in mind that this may be less stable than the released versions):</li> - </ol> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> cd <span class="Keyword">~</span>/Sites -<span class="line-numbers"> 2 </span> git clone git://github.com/bsag/tracks.git -<span class="line-numbers"> 3 </span> cd tracks -</pre></div> - - - <h4> Copy over old configuration</h4> - - - <p>There are a few settings and configuration 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.</p> - - - <ol> + <li>If you want to live on the edge, you can get the latest development version from GitHub using git (bear in mind that this may be less stable than the released versions):</li> +</ol> +<h4><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> cd <span class="Keyword">~</span>/Sites<br /> +<span class="line-numbers"> 2 </span> git clone git://github.com/bsag/tracks.git<br /> +<span class="line-numbers"> 3 </span> cd tracks<br /> +</pre></div><br /> +<br /> +Copy over old configuration</h4> +<p>There are a few settings and configuration 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.</p> +<ol> <li>Copy <code>/config/database.yml</code> from your old Tracks directory to the same location in the new one. Double check that the information there is still correct.</li> - <li>Duplicate <code>/config/site.yml.tmpl</code> in the Tracks 1.7 directory, and rename the file to <code>site.yml</code>. Open the file and alter the line <code>salt: "change-me"</code> so that it matches what you had in the <code>environment.rb</code> file in your old installation. You may also want to change the time zone setting as appropriate for your location. If you have made any other customisations to <code>environment.rb</code> in the past, you can put them in your own configuration file (e.g. my-config.rb) in <code>config/initializers</code>. Please let us know it you think they should be in <code>site.yml.tmpl</code>.</li> - <li>Copy your <code>/log</code> directory over from your old installation to the root of the new one, or just rename <code>/log.tmpl</code> to <code>log</code> to start afresh.</li> - <li>If you are using SQLite3, copy your database from <code>/db</code> in your old Tracks directory to the same location in the new one.</li> - <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) [1] of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li> - </ol> - - - <h4> Update your old database to the new format</h4> - - - <p>In a terminal, change directories so that you are inside the Tracks 1.7 directory. Then issue the command to update your Tracks 1.6 database to the format required for Tracks 1.7:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> rake db<span class="Constant"><span class="Constant">:</span>migrate</span> <span class="Variable">RAILS_ENV</span><span class="Keyword">=</span>production -</pre></div> - - - <p>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&#8217;ll have to fix them before you proceed any further. Running rake with the <code>--trace</code> option can help to track down the problem.</p> - - - <h4> Start the server</h4> - - - <p>If you&#8217;re still in the Tracks 1.7 root directory in a terminal, enter the following command to start up Tracks in production mode:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> script<span class="Keyword">/</span>server <span class="Keyword">-</span>e production -</pre></div> - - - <p>Visit the URL indicated by the output (e.g. <code>** Mongrel available at 0.0.0.0:3000</code> + <li>Duplicate <code>/config/site.yml.tmpl</code> in the Tracks 1.7 directory, and rename the file to <code>site.yml</code>. Open the file and alter the line <code>salt: "change-me"</code> so that it matches what you had in the <code>environment.rb</code> file in your old installation. You may also want to change the time zone setting as appropriate for your location. If you have made any other customisations to <code>environment.rb</code> in the past, you can put them in your own configuration file (e.g. my-config.rb) in <code>config/initializers</code>. Please let us know it you think they should be in <code>site.yml.tmpl</code>.</li> + <li>Copy your <code>/log</code> directory over from your old installation to the root of the new one, or just rename <code>/log.tmpl</code> to <code>log</code> to start afresh.</li> + <li>If you are using SQLite3, copy your database from <code>/db</code> in your old Tracks directory to the same location in the new one.</li> + <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) <sup class="footnote"><a href="#fn1">1</a></sup> of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li> +</ol> +<h4>Update your old database to the new format</h4> +<p>In a terminal, change directories so that you are inside the Tracks 1.7 directory. Then issue the command to update your Tracks 1.6 database to the format required for Tracks 1.7:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> rake db<span class="Constant"><span class="Constant">:</span>migrate</span> <span class="Variable">RAILS_ENV</span><span class="Keyword">=</span>production<br /> +</pre></div><br /> +<br /> +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&#8217;ll have to fix them before you proceed any further. Running rake with the <code>--trace</code> option can help to track down the problem.</p> +<h4>Start the server</h4> +<p>If you&#8217;re still in the Tracks 1.7 root directory in a terminal, enter the following command to start up Tracks in production mode:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> script<span class="Keyword">/</span>server <span class="Keyword">-</span>e production<br /> +</pre></div><br /> +<br /> +Visit the URL indicated by the output (e.g. <code>** Mongrel available at 0.0.0.0:3000</code><br /> ) in a browser, and with any luck, you should be able to log in and find all your actions as you left them! If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</p> - - - <h4> Clean up your old installation</h4> - - - <p>Once you&#8217;re certain that your new Tracks 1.7 installation is working perfectly, you can delete your old Tracks directory.</p> - - - <h3> Upgrading from versions prior to 1.043</h3> - - - <p>The best option for versions prior to 1.043 is to follow the instructions below to upgrade to version 1.043, then use the instructions above to upgrade from version 1.043.</p> - - - <ol> +<h4>Clean up your old installation</h4> +<p>Once you&#8217;re certain that your new Tracks 1.7 installation is working perfectly, you can delete your old Tracks directory.</p> +<h3>Upgrading from versions prior to 1.043</h3> +<p>The best option for versions prior to 1.043 is to follow the instructions below to upgrade to version 1.043, then use the instructions above to upgrade from version 1.043.</p> +<ol> <li>For safety, rename your current Tracks directory to &#8216;tracks-old&#8217; or something similar.</li> - <li>Before you do anything else, <strong>BACK UP YOUR DATABASE</strong> (tables and content) and keep the SQL dumps somewhere safe so that you can recreate the old database if necesary.</li> - <li>Download a copy of Tracks 1.043 and unzip alongside your &#8216;tracks-old&#8217; directory.</li> - <li>Open the file <code>config/environment.rb</code> and look at the last line which should read: <code>SALT = "change-me"</code>. Change the word change-me to something else of your choosing. This string will be used as a &#8216;salt&#8217; 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.</li> - <li>In <code>database.yml</code> insert your old database name, user and password under the &#8216;development&#8217; section. If you are using SQLite3 rather than MySQL or PostgreSQL, you need only the database name, and to change the &#8216;adapter&#8217; line to &#8216;sqlite3&#8217;. You also need to copy (NOT MOVE!), your SQLite3 database from your tracks-old <code>db</code> directory to your new tracks <code>db</code> directory</li> - <li>Run the command <code>rake extract_fixtures</code> inside the Tracks directory. This will populate the <code>db/exported_fixtures</code> directory with <code>*.yml</code> files corresponding to the contexts, projects and todos table from the contents of your old database.</li> - <li>Open <code>db/exported_fixtures/todos.yml</code> and search for the lines starting <code>created:</code> and replace with <code>created_at:</code>. If you are using SQLite3, you also need to change the following: <code>done: "0"</code> with <code>done: "f"</code> and <code>done: "1"</code> with <code>done: "t"</code>. You need to replace the similar &#8216;done&#8217; lines in <code>projects.yml</code>, and in <code>contexts.yml</code> replace <code>hide: "0"</code> with <code>hide: "f"</code> and <code>hide: "1"</code> with <code>hide: "t"</code>.</li> - <li>Create a new MySQL database (named tracks1043, for example). In <code>database.yml</code> insert this new database name, user and password under the &#8216;development&#8217; and &#8216;production&#8217; sections. If you are using SQLite3, insert a new name for a database to hold your Tracks 1.043 data.</li> - <li>Run the command <code>rake db_schema_import</code> inside the Tracks directory. This should import the upgraded schema for 1.043 into your new database.</li> - <li> Run the command <code>rake load_exported_fixtures</code> which will import the contents of your old database from the fixtures files in <code>db/exported_fixtures</code>.</li> - <li> If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) [1] of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li> - <li> Try starting up the server with <code>script/server</code> to make sure that all your data has migrated successfully. If all is well, follow the instructions above to <a href="upgrading_1043">upgrade from version 1.043</a> to Tracks 1.6. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</li> - </ol> - - - <p id="fn1">¹ The <code>env</code> binary helps to locate other binaries, regardless of their location. If you don&#8217;t have <code>env</code> installed, you&#8217;ll need to change this line to point to the location of your Ruby binary.</p> + <li>Before you do anything else, <strong>BACK UP YOUR DATABASE</strong> (tables and content) and keep the SQL dumps somewhere safe so that you can recreate the old database if necesary.</li> + <li>Download a copy of Tracks 1.043 and unzip alongside your &#8216;tracks-old&#8217; directory.</li> + <li>Open the file <code>config/environment.rb</code> and look at the last line which should read: <code>SALT = "change-me"</code>. Change the word change-me to something else of your choosing. This string will be used as a &#8216;salt&#8217; 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.</li> + <li>In <code>database.yml</code> insert your old database name, user and password under the &#8216;development&#8217; section. If you are using SQLite3 rather than MySQL or PostgreSQL, you need only the database name, and to change the &#8216;adapter&#8217; line to &#8216;sqlite3&#8217;. You also need to copy (NOT MOVE!), your SQLite3 database from your tracks-old <code>db</code> directory to your new tracks <code>db</code> directory</li> + <li>Run the command <code>rake extract_fixtures</code> inside the Tracks directory. This will populate the <code>db/exported_fixtures</code> directory with <code>*.yml</code> files corresponding to the contexts, projects and todos table from the contents of your old database.</li> + <li>Open <code>db/exported_fixtures/todos.yml</code> and search for the lines starting <code>created:</code> and replace with <code>created_at:</code>. If you are using SQLite3, you also need to change the following: <code>done: "0"</code> with <code>done: "f"</code> and <code>done: "1"</code> with <code>done: "t"</code>. You need to replace the similar &#8216;done&#8217; lines in <code>projects.yml</code>, and in <code>contexts.yml</code> replace <code>hide: "0"</code> with <code>hide: "f"</code> and <code>hide: "1"</code> with <code>hide: "t"</code>.</li> + <li>Create a new MySQL database (named tracks1043, for example). In <code>database.yml</code> insert this new database name, user and password under the &#8216;development&#8217; and &#8216;production&#8217; sections. If you are using SQLite3, insert a new name for a database to hold your Tracks 1.043 data.</li> + <li>Run the command <code>rake db_schema_import</code> inside the Tracks directory. This should import the upgraded schema for 1.043 into your new database.</li> + <li>Run the command <code>rake load_exported_fixtures</code> which will import the contents of your old database from the fixtures files in <code>db/exported_fixtures</code>.</li> + <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) <sup class="footnote"><a href="#fn1">1</a></sup> of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li> + <li>Try starting up the server with <code>script/server</code> to make sure that all your data has migrated successfully. If all is well, follow the instructions above to [upgrade from version 1.043][upgrading_1043] to Tracks 1.6. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</li> +</ol> +<p class="footnote" id="fn1">¹ The <code>env</code> binary helps to locate other binaries, regardless of their location. If you don&#8217;t have <code>env</code> installed, you&#8217;ll need to change this line to point to the location of your Ruby binary.</p> </div> <div class="column span-8 last" id="sidebar"> output/chapter/3-upgrading.html @@ -39,33 +39,26 @@ <div class="column span-15 append-1 first"> <div class="box" id="toc"> - <ul> +<ul> <li><a href="http://www.getontracks.org/doc/chapter/1-introduction.html" class="current">Introduction</a></li> <li><a href="http://www.getontracks.org/doc/chapter/2-installation.html">Installation</a></li> <li><a href="http://www.getontracks.org/doc/chapter/3-upgrading.html">Upgrading</a></li> - </ul> +</ul> </div> - -<h2> Introduction</h2> - - <p>Tracks is a web application that is specifically designed to implement the Getting Things Done &trade; (GTD) methods. That doesn&#8217;t mean that you can&#8217;t use it for other kinds of todo tracking. Data is stored in a database (either MySQL, Postgresql or SQLite), and viewed in a web browser via a web server (Apache, Lighttpd or Mongrel among others). This makes it cross-platform as well as being accessible from anywhere that you have web access.</p> - - <p>Using the GTD method as a model, there are three main components to Tracks: Next actions, Contexts and Projects.</p> - - <ul> - <li><strong>Next Actions</strong>: These are the heart of GTD. They are the very next physical action that can be taken on something. It&#8217;s best to phrase these in an active way e.g. &#8220;Call Bob about the committee meeting&#8221; or &#8220;Search for a reputable garage&#8221;.</li> - <li><strong>Contexts</strong>: Contexts are very flexible, and can be places, states of mind or modes of working in which actions can be taken. Next actions can be assigned to and sorted by context so that you know when you are able to make progress with items. e.g. &#8220;Library&#8221;, &#8220;Shops&#8221; or &#8220;Tired&#8221;.</li> - <li><strong>Projects</strong>: any goal which requires more than one next action to take it to completion is a Project. In Tracks, you can view your next actions by Project.</li> - </ul> - - <p>Tracks 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&#8217;s only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in <code>doc/CHANGELOG</code>. Full API documentation can be found at <code>doc/app/index.html</code>, once you have run <code>rake appdoc</code>.</p> - - <h3>About this manual</h3> - - <p>The source for this manual is kept in a <a href="http://github.com/bsag/tracks_manual/tree">GitHub repository</a>, and this is pulled as a submodule into the doc/manual subdirectory of the main <a href="http://github.com/bsag/tracks/tree">Tracks repository</a>. The source is maintained using <a href="http://webby.rubyforge.org/">Webby</a> to create the HTML (deployed to the Tracks site), and <a href="http://www.princexml.com/">Prince XML</a> is used to convert the HTML to PDF.</p> +<h2>Introduction</h2> +<p>Tracks is a web application that is specifically designed to implement the Getting Things Done &trade; (GTD) methods. That doesn&#8217;t mean that you can&#8217;t use it for other kinds of todo tracking. Data is stored in a database (either MySQL, Postgresql or SQLite), and viewed in a web browser via a web server (Apache, Lighttpd or Mongrel among others). This makes it cross-platform as well as being accessible from anywhere that you have web access.</p> +<p>Using the GTD method as a model, there are three main components to Tracks: Next actions, Contexts and Projects.</p> +<ul> + <li><strong>Next Actions</strong>: These are the heart of GTD. They are the very next physical action that can be taken on something. It&#8217;s best to phrase these in an active way e.g. &#8220;Call Bob about the committee meeting&#8221; or &#8220;Search for a reputable garage&#8221;.</li> + <li><strong>Contexts</strong>: Contexts are very flexible, and can be places, states of mind or modes of working in which actions can be taken. Next actions can be assigned to and sorted by context so that you know when you are able to make progress with items. e.g. &#8220;Library&#8221;, &#8220;Shops&#8221; or &#8220;Tired&#8221;.</li> + <li><strong>Projects</strong>: any goal which requires more than one next action to take it to completion is a Project. In Tracks, you can view your next actions by Project.</li> +</ul> +<p>Tracks 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&#8217;s only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in <code>doc/CHANGELOG</code>. Full API documentation can be found at <code>doc/app/index.html</code>, once you have run <code>rake appdoc</code>.</p> +<h3>About this manual</h3> +<p>The source for this manual is kept in a <a href="http://github.com/bsag/tracks_manual/tree">GitHub repository</a>, and this is pulled as a submodule into the doc/manual subdirectory of the main <a href="http://github.com/bsag/tracks/tree">Tracks repository</a>. The source is maintained using <a href="http://webby.rubyforge.org/">Webby</a> to create the HTML (deployed to the Tracks site), and <a href="http://www.princexml.com/">Prince XML</a> is used to convert the HTML to PDF.</p> </div> <div class="column span-8 last" id="sidebar"> output/index.html @@ -26,7 +26,7 @@ <div class="container"> <div class="column span-24 first last" id="header"> - <h1><img src="/assets/tracks-logo.png" /></h1> + <h1><img src="http://getontracks.org/doc/assets/tracks-logo.png" /></h1> </div> <div class="column span-15 append-1 first"> @@ -49,347 +49,186 @@ </div> - <h2> Introduction</h2> - - - <p>Tracks is a web application that is specifically designed to implement the Getting Things Done &trade; (GTD) methods. That doesn&#8217;t mean that you can&#8217;t use it for other kinds of todo tracking. Data is stored in a database (either MySQL, Postgresql or SQLite), and viewed in a web browser via a web server (Apache, Lighttpd or Mongrel among others). This makes it cross-platform as well as being accessible from anywhere that you have web access.</p> - - - <p>Using the GTD method as a model, there are three main components to Tracks: Next actions, Contexts and Projects.</p> - - - <ul> + <h2>Introduction</h2> +<p>Tracks is a web application that is specifically designed to implement the Getting Things Done &trade; (GTD) methods. That doesn&#8217;t mean that you can&#8217;t use it for other kinds of todo tracking. Data is stored in a database (either MySQL, Postgresql or SQLite), and viewed in a web browser via a web server (Apache, Lighttpd or Mongrel among others). This makes it cross-platform as well as being accessible from anywhere that you have web access.</p> +<p>Using the GTD method as a model, there are three main components to Tracks: Next actions, Contexts and Projects.</p> +<ul> <li><strong>Next Actions</strong>: These are the heart of GTD. They are the very next physical action that can be taken on something. It&#8217;s best to phrase these in an active way e.g. &#8220;Call Bob about the committee meeting&#8221; or &#8220;Search for a reputable garage&#8221;.</li> - <li><strong>Contexts</strong>: Contexts are very flexible, and can be places, states of mind or modes of working in which actions can be taken. Next actions can be assigned to and sorted by context so that you know when you are able to make progress with items. e.g. &#8220;Library&#8221;, &#8220;Shops&#8221; or &#8220;Tired&#8221;.</li> - <li><strong>Projects</strong>: any goal which requires more than one next action to take it to completion is a Project. In Tracks, you can view your next actions by Project.</li> - </ul> - - - <p>Tracks 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&#8217;s only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in <code>doc/CHANGELOG</code>. Full API documentation can be found at <code>doc/app/index.html</code>, once you have run <code>rake appdoc</code>.</p> - - - <h3>About this manual</h3> - - - <p>The source for this manual is kept in a <a href="http://github.com/bsag/tracks_manual/tree">GitHub repository</a>, and this is pulled as a submodule into the doc/manual subdirectory of the main <a href="http://github.com/bsag/tracks/tree">Tracks repository</a>. The source is maintained using <a href="http://webby.rubyforge.org/">Webby</a> to create the HTML (deployed to the Tracks site), and <a href="http://www.princexml.com/">Prince XML</a> is used to convert the HTML to PDF.</p> + <li><strong>Contexts</strong>: Contexts are very flexible, and can be places, states of mind or modes of working in which actions can be taken. Next actions can be assigned to and sorted by context so that you know when you are able to make progress with items. e.g. &#8220;Library&#8221;, &#8220;Shops&#8221; or &#8220;Tired&#8221;.</li> + <li><strong>Projects</strong>: any goal which requires more than one next action to take it to completion is a Project. In Tracks, you can view your next actions by Project.</li> +</ul> +<p>Tracks 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&#8217;s only sensible to make sure that you have frequent, reliable backups of your data. Full changenotes on the release can be found in <code>doc/CHANGELOG</code>. Full API documentation can be found at <code>doc/app/index.html</code>, once you have run <code>rake appdoc</code>.</p> +<h3>About this manual</h3> +<p>The source for this manual is kept in a <a href="http://github.com/bsag/tracks_manual/tree">GitHub repository</a>, and this is pulled as a submodule into the doc/manual subdirectory of the main <a href="http://github.com/bsag/tracks/tree">Tracks repository</a>. The source is maintained using <a href="http://webby.rubyforge.org/">Webby</a> to create the HTML (deployed to the Tracks site), and <a href="http://www.princexml.com/">Prince XML</a> is used to convert the HTML to PDF.</p> <h2>Installing Tracks</h2> - - - <h3>Getting Tracks</h3> - - - <p>There are two methods of downloading Tracks:</p> - - - <ol> +<h3>Getting Tracks</h3> +<p>There are two methods of downloading Tracks:</p> +<ol> <li>(Recommended for most people) Download the <a href="http://bsag.bingodisk.com/public/files/tracks-current.zip">zipped package</a>, and unzip in your preferred location (e.g. <code>~/Sites</code> for Mac OS X users).</li> - <li>If you want to live on the edge, you can get the latest development version from GitHub using git (bear in mind that this may be less stable than the released versions):</li> - </ol> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> cd <span class="Keyword">~</span>/Sites -<span class="line-numbers"> 2 </span> git clone git://github.com/bsag/tracks.git -<span class="line-numbers"> 3 </span> cd tracks -</pre></div> - -<h4>Easy installation options</h4> - - <p>There are a few easy options if you are not confident about installing Tracks from source using these instructions. If you&#8217;d like to install Tracks on a local machine, try <a href="http://bitnami.org/stack/tracks">BitNami</a>&#8212;it runs on Windows, Mac OS X and Linux. Alternatively, you could try <a href="http://www.jumpbox.com/">JumpBox</a>, who provide a <a href="http://www.jumpbox.com/app/tracks">JumpBox for Tracks 1.7</a>. JumpBoxes are pre-built, pre-configured virtual applications which run in a range of <a href="http://www.jumpbox.com/supported-virtualization-software">Virtualization software applications</a>. You just download the JumpBox (free), then open the file with your Virtualization software. Once the JumpBox has booted, it will give you a URL which you can visit in a browser. The software will then guide you through setting up an account. If you&#8217;d like to try out the JumpBox without installing it, you can use the &#8216;Trial This JumpBox&#8217; button on the web site, which will let you play around with it to test it out. Furthermore, there is a free public AMI available for Amazon EC2. Just use any EC2 client and search for Tracks. This works in exactly the same way as the downloaded JumpBox you can easily migrate from a downloaded installation to an EC2 instance or back using the backup system of the JumpBox.</p> - - - <p>If you&#8217;d like an easy way to access Tracks from any internet-connected computer, sign up for a free account at <a href="http://www.morphexchange.com/">Morph eXchange</a>. Sign up for a free account, then click on &#8220;See all available subscriptions&#8221; and you&#8217;ll see Tracks listed as an application. Just subscribe to Tracks and you can get started. This option is recommended for those with little technical know-how.</p> - - - <h4> Requirements</h4> - - - <p>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&#8217;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 <a href="http://www.apache.org/">Apache</a> or <a href="http://www.lighttpd.net/">Lighttpd</a> to serve the pages, particularly if it will be used by many people.</p> - - - <p>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.</p> - - - <h4> What is included with the Tracks package?</h4> - - - <ol> + <li>If you want to live on the edge, you can get the latest development version from GitHub using git (bear in mind that this may be less stable than the released versions):</li> +</ol> +<h4><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> cd <span class="Keyword">~</span>/Sites<br /> +<span class="line-numbers"> 2 </span> git clone git://github.com/bsag/tracks.git<br /> +<span class="line-numbers"> 3 </span> cd tracks<br /> +</pre></div><br /> +Easy installation options</h4> +<p>There are a few easy options if you are not confident about installing Tracks from source using these instructions. If you&#8217;d like to install Tracks on a local machine, try <a href="http://bitnami.org/stack/tracks">BitNami</a> &#8212; it runs on Windows, Mac OS X and Linux. Alternatively, you could try <a href="http://www.shareasale.com/r.cfm?u=188858&amp;b=179734&amp;m=22742&amp;afftrack=&amp;urllink=www%2Ejumpbox%2Ecom" title="Affliate link">JumpBox</a>, who provide a <a href="http://www.shareasale.com/r.cfm?u=188858&amp;b=179734&amp;m=22742&amp;afftrack=&amp;urllink=www%2Ejumpbox%2Ecom%2Fapp%2Ftracks" title="Affiliate link">JumpBox for Tracks 1.7</a>. JumpBoxes are pre-built, pre-configured virtual applications which run in a range of <a href="http://www.jumpbox.com/supported-virtualization-software">Virtualization software applications</a>. You just download the JumpBox (free), then open the file with your Virtualization software. Once the JumpBox has booted, it will give you a URL which you can visit in a browser. The software will then guide you through setting up an account. If you&#8217;d like to try out the JumpBox without installing it, you can use the &#8216;Trial This JumpBox&#8217; button on the web site, which will let you play around with it to test it out. Furthermore, there is a free public AMI available for Amazon EC2. Just use any EC2 client and search for Tracks. This works in exactly the same way as the downloaded JumpBox you can easily migrate from a downloaded installation to an EC2 instance or back using the backup system of the JumpBox.</p> +<p>If you&#8217;d like an easy way to access Tracks from any internet-connected computer, sign up for a free account at <a href="http://www.morphexchange.com/">Morph eXchange</a>. Sign up for a free account, then click on &#8220;See all available subscriptions&#8221; and you&#8217;ll see Tracks listed as an application. Just subscribe to Tracks and you can get started. This option is recommended for those with little technical know-how.</p> +<h4>Requirements</h4> +<p>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&#8217;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 <a href="http://www.apache.org/">Apache</a> or <a href="http://www.lighttpd.net/">Lighttpd</a> to serve the pages, particularly if it will be used by many people.</p> +<p>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.</p> +<h4>What is included with the Tracks package?</h4> +<ol> <li>Tracks itself</li> - <li>Rails 2.2.2 (installed in the <code>/vendor/rails</code> directory, so you do not need to install Rails yourself)</li> - <li>An empty SQLite3 database, set up with the correct database schema</li> - </ol> - - - <h4> What you need to install</h4> - - - <p>If you don&#8217;t want to (or can&#8217;t) use one of the all in one installations, you&#8217;ll need to install a few things, depending on your platform and your needs.</p> - - - <ol> + <li>Rails 2.2.2 (installed in the <code>/vendor/rails</code> directory, so you do not need to install Rails yourself)</li> + <li>An empty SQLite3 database, set up with the correct database schema</li> +</ol> +<h4>What you need to install</h4> +<p>If you don&#8217;t want to (or can&#8217;t) use one of the all in one installations, you&#8217;ll need to install a few things, depending on your platform and your needs.</p> +<ol> <li><strong>Ruby</strong>. Version 1.8.6 or 1.8.7 is recommended, but it is also possible to use 1.8.5, 1.8.4 and 1.8.2. Note that 1.8.3 is not compatible. If you are running Mac OS X Leopard, you already have Ruby 1.8.6 installed by default, so you have nothing to do here. You can get the source to compile yourself <a href="http://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.6.tar.gz">here</a> for all platforms, or Windows users can use an easy <a href="http://rubyforge.org/frs/?group_id=167">installer</a>. If you&#8217;re using a version of Mac OS X earlier than 10.5.0, it is recommended that you use the <a href="http://hivelogic.com/narrative/articles/ruby-rails-mongrel-mysql-osx">instructions here</a> to install all the Rails dependencies, though you can skip the step to install Rails if you like.</li> - <li><strong>RubyGems</strong>. The gems needed by Rails to interact with the database have to be compiled on the platform on which they will be run, so we cannot include them with the Tracks package, unlike some other gems. So you will need to <a href="http://rubyforge.org/frs/?group_id=126">download</a> and install RubyGems (run <code>ruby setup.rb</code> after extracting the package). Note that once again, Mac OS X Leopard users get an easy life, because RubyGems and the SQLite3 gem is already installed. Once installed you can use RubyGems to install the gems you need for your database. If you are using SQLite3, run <code>sudo gem install sqlite3-ruby</code>, then select the appropriate package for your platform (version 1.2.1 recommended). You can use MySQL without installing a gem, but installing the gem can speed things up a bit: <code>sudo gem install mysql</code>. If you&#8217;re using Leopard, there are a few work-arounds necessary, which are explained on <a href="http://trac.macosforge.org/projects/ruby/wiki/Troubleshooting#IcannotbuildrubymysqlonLeopardwithmysql.combinaries">Mac OS Forge</a>. The ruby-mysql bindings can sometimes be a bit troublesome to install, so to be honest, it&#8217;s probably not worth the bother unless you are trying to wring maximum speed out of your system. If you are using PostgreSQL, then you can install a postgres gem: <code>gem install postgres</code>.</li> - <li><strong>Database</strong>. The easiest option is to use SQLite3, as the database is included in the package. All you need then is the <code>sqlite3-ruby</code> gem, as described in step 2, and the SQLite3 libraries and binary (see <a href="http://sqlite.org/download.html">sqlite.org</a> for downloads and installation instructions). If you want to use MySQL, download and install a package for your platform from <a href="http://dev.mysql.com/downloads/mysql/5.0.html">MySQL.com</a>. The basic steps for Postgresql should be similar to those for MySQL, but they will not be discussed further here.</li> - <li><strong>Rake</strong> You will need rake to install and upgrade Tracks. If it is not installed on your system, use <code>sudo gem install rake</code> to install it.</li> - </ol> - - - <p>You can find several installation howtos for specific setups <a href="http://www.getontracks.org/wiki/Installation-Index/">here</a>. They were contributed by various Tracks users.</p> - - - <h3> Installation</h3> - - - <p>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.7.</p> - - - <ol> + <li><strong>RubyGems</strong>. The gems needed by Rails to interact with the database have to be compiled on the platform on which they will be run, so we cannot include them with the Tracks package, unlike some other gems. So you will need to <a href="http://rubyforge.org/frs/?group_id=126">download</a> and install RubyGems (run <code>ruby setup.rb</code> after extracting the package). Note that once again, Mac OS X Leopard users get an easy life, because RubyGems and the SQLite3 gem is already installed. Once installed you can use RubyGems to install the gems you need for your database. If you are using SQLite3, run <code>sudo gem install sqlite3-ruby</code>, then select the appropriate package for your platform (version 1.2.1 recommended). You can use MySQL without installing a gem, but installing the gem can speed things up a bit: <code>sudo gem install mysql</code>. If you&#8217;re using Leopard, there are a few work-arounds necessary, which are explained on <a href="http://trac.macosforge.org/projects/ruby/wiki/Troubleshooting#IcannotbuildrubymysqlonLeopardwithmysql.combinaries">Mac OS Forge</a>. The ruby-mysql bindings can sometimes be a bit troublesome to install, so to be honest, it&#8217;s probably not worth the bother unless you are trying to wring maximum speed out of your system. If you are using PostgreSQL, then you can install a postgres gem: <code>gem install postgres</code>.</li> + <li><strong>Database</strong>. The easiest option is to use SQLite3, as the database is included in the package. All you need then is the <code>sqlite3-ruby</code> gem, as described in step 2, and the SQLite3 libraries and binary (see <a href="http://sqlite.org/download.html">sqlite.org</a> for downloads and installation instructions). If you want to use MySQL, download and install a package for your platform from <a href="http://dev.mysql.com/downloads/mysql/5.0.html">MySQL.com</a>. The basic steps for Postgresql should be similar to those for MySQL, but they will not be discussed further here.</li> + <li><strong>Rake</strong> You will need rake to install and upgrade Tracks. If it is not installed on your system, use <code>sudo gem install rake</code> to install it.</li> +</ol> +<p>You can find several installation howtos for specific setups <a href="http://www.getontracks.org/wiki/Installation-Index/">here</a>. They were contributed by various Tracks users.</p> +<h3>Installation</h3> +<p>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.7.</p> +<ol> <li>Unzip tracks and install in a directory</li> - <li>Decide on a database to use - <ol> - <li> SQLite3 &#8211; change database.yml to point to SQLite3 database. Make sure you add the complete path to the database</li> - <li> MySQL &#8211; create new MySQL db and grant all privileges </li> - </ol> - </li> - <li>Configure some variables</li> - <li>Populate the database with the Tracks 1.7 schema</li> - <li>Start the server</li> - <li>Visit Tracks in a browser</li> - <li>Customise Tracks</li> - </ol> - - - <h4> Unzip Tracks and install</h4> - - - <p>Unzip the package and move Tracks into the directory you want to run it from. For example, for Mac OS X users, <code>~/Sites</code> is a good choice.</p> - - - <h4> Decide on a database</h4> - - - <p>Before you go any further, you need to decide which database you will use. See the &#8216;What you need to install&#8217; section for details on installing the required components for you choice of database.</p> - - + <li>Decide on a database to use <ol> + <li>SQLite3 &#8211; change database.yml to point to SQLite3 database. Make sure you add the complete path to the database</li> + <li>MySQL &#8211; create new MySQL db and grant all privileges</li> + </ol></li> + <li>Configure some variables</li> + <li>Populate the database with the Tracks 1.7 schema</li> + <li>Start the server</li> + <li>Visit Tracks in a browser</li> + <li>Customise Tracks</li> +</ol> +<h4>Unzip Tracks and install</h4> +<p>Unzip the package and move Tracks into the directory you want to run it from. For example, for Mac OS X users, <code>~/Sites</code> is a good choice.</p> +<h4>Decide on a database</h4> +<p>Before you go any further, you need to decide which database you will use. See the &#8216;What you need to install&#8217; section for details on installing the required components for you choice of database.</p> +<ol> <li><strong>SQLite3</strong>. All you need to do is make sure that you point Tracks to the included SQLite3 database in <code>/db</code> in the next step, &#8216;Configure variables&#8217;.</li> - <li><strong>MySQL</strong>. Once you have MySQL installed, you need to create a database and database-user to use with Tracks 1.7. For this, you can use MySQL Administrator or go into a terminal and issue the following commands:</li> - </ol> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> mysql -uroot -p -<span class="line-numbers"> 2 </span> mysql&gt; CREATE DATABASE tracks; -<span class="line-numbers"> 3 </span> mysql&gt; <span class="Keyword">GRANT</span> ALL PRIVILEGES <span class="Keyword">ON </span>tracks.* TO yourmysqluser@localhost \ -<span class="line-numbers"> 4 </span> IDENTIFIED BY <span class="String"><span class="String">'</span>password-goes-here'</span> WITH <span class="Keyword">GRANT</span> OPTION; -</pre></div> - - - <h4> Configure variables</h4> - - - <ol> + <li><strong>MySQL</strong>. Once you have MySQL installed, you need to create a database and database-user to use with Tracks 1.7. For this, you can use MySQL Administrator or go into a terminal and issue the following commands:</li> +</ol> +<h4><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> mysql -uroot -p<br /> +<span class="line-numbers"> 2 </span> mysql&gt; CREATE DATABASE tracks;<br /> +<span class="line-numbers"> 3 </span> mysql&gt; <span class="Keyword">GRANT</span> ALL PRIVILEGES <span class="Keyword">ON </span>tracks.* TO yourmysqluser@localhost \<br /> +<span class="line-numbers"> 4 </span> IDENTIFIED BY <span class="String"><span class="String">&#8216;</span>password-goes-here&#8217;</span> WITH <span class="Keyword">GRANT</span> OPTION;<br /> +</pre></div><br /> +<br /> +Configure variables</h4> +<ol> <li>If you downloaded Tracks 1.7 via GitHub, you need to duplicate the files <code>database.yml.tmpl</code> and <code>site.yml.tmpl</code> and remove the <code>*.tmpl</code> extension from the duplicates. Similarly, duplicate <code>/log.tmpl</code> and remove the <code>*.tmpl</code> extension, then edit the files as described in steps 2 and 3.</li> - <li>Open the file <code>/config/database.yml</code> and edit the <code>production:</code> section with the details of your database. If you are using MySQL the <code>adapter:</code> line should read <code>adapter: mysql</code>, <code>host: localhost</code> (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: <code>adapter: sqlite3</code> and <code>database: db/tracks-17-blank.db</code>. If you downloaded the zipped file, the database.yml file is already configured to use the provided SQLite3 file.</li> - <li>Open the file <code>/config/site.yml</code>, and read through the settings to make sure that they suit your setup. In most cases, all you need to change is the <code>salt: "change-me"</code> line (change the string &#8220;change-me&#8221; to some other string of your choice), and the time zone setting. For the time zone setting you can use the command <code>rake time:zones:local</code> to see all available timezones on your machine</li> - <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. This should work for all Unix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like <code>#c:/ruby/bin/ruby</code> to point to the Ruby binary on your system.</li> - </ol> - - - <h4> Populate your database with the Tracks 1.7 schema</h4> - - - <p>Open a terminal and change into the root of your Tracks 1.7 directory. Enter the following command:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> rake db<span class="Constant"><span class="Constant">:</span>migrate</span> <span class="Variable">RAILS_ENV</span><span class="Keyword">=</span>production -</pre></div> - -This will update your database with the required schema for Tracks 1.7. 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). - - <h4> Start the server</h4> - - - <p>While still in the Terminal inside the Tracks 1.7 root directory, issue the following command:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> script<span class="Keyword">/</span>server <span class="Keyword">-</span>e production -</pre></div> - -If all goes well, you should see some text informing you that the Mongrel server is running: <code>** Mongrel available at 0.0.0.0:3000</code>. If you are already running other services on port 3000, you need to select a different port when running the server, using the <code>-p</code> option. You can stop the server again by the key combination Ctrl-C. - - <h4> Visit Tracks in a browser</h4> - - - <p>Visit <code>http://0.0.0.0:3000/signup</code> 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. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</p> - - - <h4> Customise Tracks</h4> - - - <p>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!</p> - - <h2> Upgrading Tracks</h2> - - - <h3> Upgrading from Tracks 1.7RC2 to Tracks 1.7</h3> - - - <p>There were only a few fixes in the code, so you can consider unzipping the new release over your install of Tracks 1.7RC2. Do make a backup of your Tracks 1.7RC2 install and your database!</p> - - - <p>It is also possible to follow the instructions below and copy your existing Site.yml from your Tracks 1.7RC2 install.</p> - - - <h3> Upgrading from Tracks 1.5, 1.6 or from Tracks 1.7RC1 to Tracks 1.7</h3> - - - <p>In Tracks 1.7 (since RC2) the site specific configuration is moved from <code>environment.rb</code> into the new <code>site.yml</code>. This makes updating <code>environment.rb</code> much easier without you needing to set your site specific settings after each update.</p> - - - <p>After you install Tracks 1.7 there will be no <code>environment.rb.tmpl</code> anymore. You will find an <code>environment.rb</code> which you can leave untouched. Just fill in your settings from your old <code>environment.rb</code> in the new <code>site.yml</code>. If you have made any other customisations to <code>environment.rb</code> in the past, you can put them in your own configuration file (for example, in my-config.rb) in <code>config/initializers</code>. Please let us know it you think they should be in <code>site.yml.tmpl</code></p> - - - <p>Also, there were some database changes made in Tracks 1.7, so you need to migrate to them.</p> - - - <ol> + <li>Open the file <code>/config/database.yml</code> and edit the <code>production:</code> section with the details of your database. If you are using MySQL the <code>adapter:</code> line should read <code>adapter: mysql</code>, <code>host: localhost</code> (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: <code>adapter: sqlite3</code> and <code>database: db/tracks-17-blank.db</code>. If you downloaded the zipped file, the database.yml file is already configured to use the provided SQLite3 file.</li> + <li>Open the file <code>/config/site.yml</code>, and read through the settings to make sure that they suit your setup. In most cases, all you need to change is the <code>salt: "change-me"</code> line (change the string &#8220;change-me&#8221; to some other string of your choice), and the time zone setting. For the time zone setting you can use the command <code>rake time:zones:local</code> to see all available timezones on your machine</li> + <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. This should work for all Unix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like <code>#c:/ruby/bin/ruby</code> to point to the Ruby binary on your system.</li> +</ol> +<h4>Populate your database with the Tracks 1.7 schema</h4> +<p>Open a terminal and change into the root of your Tracks 1.7 directory. Enter the following command:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> rake db<span class="Constant"><span class="Constant">:</span>migrate</span> <span class="Variable">RAILS_ENV</span><span class="Keyword">=</span>production<br /> +</pre></div><br /> +This will update your database with the required schema for Tracks 1.7. 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).</p> +<h4>Start the server</h4> +<p>While still in the Terminal inside the Tracks 1.7 root directory, issue the following command:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> script<span class="Keyword">/</span>server <span class="Keyword">-</span>e production<br /> +</pre></div><br /> +If all goes well, you should see some text informing you that the Mongrel server is running: <code>** Mongrel available at 0.0.0.0:3000</code>. If you are already running other services on port 3000, you need to select a different port when running the server, using the <code>-p</code> option. You can stop the server again by the key combination Ctrl-C.</p> +<h4>Visit Tracks in a browser</h4> +<p>Visit <code>http://0.0.0.0:3000/signup</code> 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. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</p> +<h4>Customise Tracks</h4> +<p>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!</p> + + <h2>Upgrading Tracks</h2> +<h3>Upgrading from Tracks 1.7RC2 to Tracks 1.7</h3> +<p>There were only a few fixes in the code, so you can consider unzipping the new release over your install of Tracks 1.7RC2. Do make a backup of your Tracks 1.7RC2 install and your database!</p> +<p>It is also possible to follow the instructions below and copy your existing Site.yml from your Tracks 1.7RC2 install.</p> +<h3>Upgrading from Tracks 1.5, 1.6 or from Tracks 1.7RC1 to Tracks 1.7</h3> +<p>In Tracks 1.7 (since RC2) the site specific configuration is moved from <code>environment.rb</code> into the new <code>site.yml</code>. This makes updating <code>environment.rb</code> much easier without you needing to set your site specific settings after each update.</p> +<p>After you install Tracks 1.7 there will be no <code>environment.rb.tmpl</code> anymore. You will find an <code>environment.rb</code> which you can leave untouched. Just fill in your settings from your old <code>environment.rb</code> in the new <code>site.yml</code>. If you have made any other customisations to <code>environment.rb</code> in the past, you can put them in your own configuration file (for example, in my-config.rb) in <code>config/initializers</code>. Please let us know it you think they should be in <code>site.yml.tmpl</code></p> +<p>Also, there were some database changes made in Tracks 1.7, so you need to migrate to them.</p> +<ol> <li>Back up your existing database and installation of Tracks</li> - <li>Install Tracks 1.7 in a new directory</li> - <li>Copy over the configuration from your previous Tracks installation (except for environment.rb, see above). If using SQLite3, copy the old database into the new Tracks 1.7 directory.</li> - <li>Run <code>rake db:migrate RAILS_ENV=production</code> to update your old database to the new schema&#8212;you did back up your database didn&#8217;t you?</li> - <li>Run <code>script/server</code> inside your Tracks 1.7 directory to start up Tracks 1.7.</li> - <li>Once you are happy that everything is working well, delete your old Tracks directory.</li> - </ol> - - - <h3> Upgrading from Tracks 1.043 to 1.7</h3> - - - <p>This should be a relatively straightforward, and involves the following main steps:</p> - - - <ol> + <li>Install Tracks 1.7 in a new directory</li> + <li>Copy over the configuration from your previous Tracks installation (except for environment.rb, see above). If using SQLite3, copy the old database into the new Tracks 1.7 directory.</li> + <li>Run <code>rake db:migrate RAILS_ENV=production</code> to update your old database to the new schema &#8212; you did back up your database didn&#8217;t you?</li> + <li>Run <code>script/server</code> inside your Tracks 1.7 directory to start up Tracks 1.7.</li> + <li>Once you are happy that everything is working well, delete your old Tracks directory.</li> +</ol> +<h3>Upgrading from Tracks 1.043 to 1.7</h3> +<p>This should be a relatively straightforward, and involves the following main steps:</p> +<ol> <li>Back up your existing database and installation of Tracks</li> - <li>Install Tracks 1.6 in a new directory</li> - <li>Copy over the configuration from your previous Tracks 1.043 installation. If using SQLite3, copy the old database into the new Tracks 1.7 directory.</li> - <li>Run <code>rake db:migrate RAILS_ENV=production</code> to update your old database to the new schema&#8212;you did back up your database didn&#8217;t you? + <li>Install Tracks 1.6 in a new directory</li> + <li>Copy over the configuration from your previous Tracks 1.043 installation. If using SQLite3, copy the old database into the new Tracks 1.7 directory.</li> + <li>Run <code>rake db:migrate RAILS_ENV=production</code> to update your old database to the new schema &#8212; you did back up your database didn&#8217;t you?<br /> +# Run <code>script/server</code> inside your Tracks 1.7 directory to start up Tracks 1.7.</li> - <li>Once you are happy that everything is working well, delete your old Tracks directory.</li> - </ol> - - - <h3>Detailed steps</h3> - - - <h4> Backing up</h4> - - - <p>It&#8217;s very important that you <strong>back up your database</strong> before you start the upgrade process. It&#8217;s always possible for things to go wrong with the database update, and you don&#8217;t want to lose any data. If you are using SQLite3 and you are leaving your old Tracks directory in place, then you don&#8217;t need to do anything. However, there is no harm in taking extra precautions and copying your database from <code>/db</code> 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:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> mysqldump –-user [user name] –-password=[password] \ -<span class="line-numbers"> 2 </span> [database name] <span class="Keyword">&gt;</span> [dump file] -</pre></div> - -Rename your old Tracks installation (e.g. to &#8216;tracks-old&#8217;) so that you can install Tracks 1.7 along side it. - - <h4> Install the latest version of Tracks</h4> - - - <p>There are two methods of downloading Tracks:</p> - - - <ol> + <li>Once you are happy that everything is working well, delete your old Tracks directory.</li> +</ol> +<h3>Detailed steps</h3> +<h4>Backing up</h4> +<p>It&#8217;s very important that you <strong>back up your database</strong> before you start the upgrade process. It&#8217;s always possible for things to go wrong with the database update, and you don&#8217;t want to lose any data. If you are using SQLite3 and you are leaving your old Tracks directory in place, then you don&#8217;t need to do anything. However, there is no harm in taking extra precautions and copying your database from <code>/db</code> 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:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> mysqldump –-user [user name] –-password=[password] \<br /> +<span class="line-numbers"> 2 </span> [database name] <span class="Keyword">&gt;</span> [dump file]<br /> +</pre></div><br /> +Rename your old Tracks installation (e.g. to &#8216;tracks-old&#8217;) so that you can install Tracks 1.7 along side it.</p> +<h4>Install the latest version of Tracks</h4> +<p>There are two methods of downloading Tracks:</p> +<ol> <li>(Recommended for most people) Download the <a href="http://bsag.bingodisk.com/public/files/tracks_1.7.zip">zipped package</a>, and unzip in your preferred location (e.g. <code>~/Sites</code> for Mac OS X users).</li> - <li>If you want to live on the edge, you can get the latest development version from GitHub using git (bear in mind that this may be less stable than the released versions):</li> - </ol> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> cd <span class="Keyword">~</span>/Sites -<span class="line-numbers"> 2 </span> git clone git://github.com/bsag/tracks.git -<span class="line-numbers"> 3 </span> cd tracks -</pre></div> - - - <h4> Copy over old configuration</h4> - - - <p>There are a few settings and configuration 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.</p> - - - <ol> + <li>If you want to live on the edge, you can get the latest development version from GitHub using git (bear in mind that this may be less stable than the released versions):</li> +</ol> +<h4><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> cd <span class="Keyword">~</span>/Sites<br /> +<span class="line-numbers"> 2 </span> git clone git://github.com/bsag/tracks.git<br /> +<span class="line-numbers"> 3 </span> cd tracks<br /> +</pre></div><br /> +<br /> +Copy over old configuration</h4> +<p>There are a few settings and configuration 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.</p> +<ol> <li>Copy <code>/config/database.yml</code> from your old Tracks directory to the same location in the new one. Double check that the information there is still correct.</li> - <li>Duplicate <code>/config/site.yml.tmpl</code> in the Tracks 1.7 directory, and rename the file to <code>site.yml</code>. Open the file and alter the line <code>salt: "change-me"</code> so that it matches what you had in the <code>environment.rb</code> file in your old installation. You may also want to change the time zone setting as appropriate for your location. If you have made any other customisations to <code>environment.rb</code> in the past, you can put them in your own configuration file (e.g. my-config.rb) in <code>config/initializers</code>. Please let us know it you think they should be in <code>site.yml.tmpl</code>.</li> - <li>Copy your <code>/log</code> directory over from your old installation to the root of the new one, or just rename <code>/log.tmpl</code> to <code>log</code> to start afresh.</li> - <li>If you are using SQLite3, copy your database from <code>/db</code> in your old Tracks directory to the same location in the new one.</li> - <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) [1] of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li> - </ol> - - - <h4> Update your old database to the new format</h4> - - - <p>In a terminal, change directories so that you are inside the Tracks 1.7 directory. Then issue the command to update your Tracks 1.6 database to the format required for Tracks 1.7:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> rake db<span class="Constant"><span class="Constant">:</span>migrate</span> <span class="Variable">RAILS_ENV</span><span class="Keyword">=</span>production -</pre></div> - - - <p>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&#8217;ll have to fix them before you proceed any further. Running rake with the <code>--trace</code> option can help to track down the problem.</p> - - - <h4> Start the server</h4> - - - <p>If you&#8217;re still in the Tracks 1.7 root directory in a terminal, enter the following command to start up Tracks in production mode:</p> - - - -<div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> script<span class="Keyword">/</span>server <span class="Keyword">-</span>e production -</pre></div> - - - <p>Visit the URL indicated by the output (e.g. <code>** Mongrel available at 0.0.0.0:3000</code> + <li>Duplicate <code>/config/site.yml.tmpl</code> in the Tracks 1.7 directory, and rename the file to <code>site.yml</code>. Open the file and alter the line <code>salt: "change-me"</code> so that it matches what you had in the <code>environment.rb</code> file in your old installation. You may also want to change the time zone setting as appropriate for your location. If you have made any other customisations to <code>environment.rb</code> in the past, you can put them in your own configuration file (e.g. my-config.rb) in <code>config/initializers</code>. Please let us know it you think they should be in <code>site.yml.tmpl</code>.</li> + <li>Copy your <code>/log</code> directory over from your old installation to the root of the new one, or just rename <code>/log.tmpl</code> to <code>log</code> to start afresh.</li> + <li>If you are using SQLite3, copy your database from <code>/db</code> in your old Tracks directory to the same location in the new one.</li> + <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) <sup class="footnote"><a href="#fn1">1</a></sup> of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li> +</ol> +<h4>Update your old database to the new format</h4> +<p>In a terminal, change directories so that you are inside the Tracks 1.7 directory. Then issue the command to update your Tracks 1.6 database to the format required for Tracks 1.7:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> rake db<span class="Constant"><span class="Constant">:</span>migrate</span> <span class="Variable">RAILS_ENV</span><span class="Keyword">=</span>production<br /> +</pre></div><br /> +<br /> +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&#8217;ll have to fix them before you proceed any further. Running rake with the <code>--trace</code> option can help to track down the problem.</p> +<h4>Start the server</h4> +<p>If you&#8217;re still in the Tracks 1.7 root directory in a terminal, enter the following command to start up Tracks in production mode:</p> +<p><div class="UltraViolet"><pre class="blackboard"><span class="line-numbers"> 1 </span> script<span class="Keyword">/</span>server <span class="Keyword">-</span>e production<br /> +</pre></div><br /> +<br /> +Visit the URL indicated by the output (e.g. <code>** Mongrel available at 0.0.0.0:3000</code><br /> ) in a browser, and with any luck, you should be able to log in and find all your actions as you left them! If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</p> - - - <h4> Clean up your old installation</h4> - - - <p>Once you&#8217;re certain that your new Tracks 1.7 installation is working perfectly, you can delete your old Tracks directory.</p> - - - <h3> Upgrading from versions prior to 1.043</h3> - - - <p>The best option for versions prior to 1.043 is to follow the instructions below to upgrade to version 1.043, then use the instructions above to upgrade from version 1.043.</p> - - - <ol> +<h4>Clean up your old installation</h4> +<p>Once you&#8217;re certain that your new Tracks 1.7 installation is working perfectly, you can delete your old Tracks directory.</p> +<h3>Upgrading from versions prior to 1.043</h3> +<p>The best option for versions prior to 1.043 is to follow the instructions below to upgrade to version 1.043, then use the instructions above to upgrade from version 1.043.</p> +<ol> <li>For safety, rename your current Tracks directory to &#8216;tracks-old&#8217; or something similar.</li> - <li>Before you do anything else, <strong>BACK UP YOUR DATABASE</strong> (tables and content) and keep the SQL dumps somewhere safe so that you can recreate the old database if necesary.</li> - <li>Download a copy of Tracks 1.043 and unzip alongside your &#8216;tracks-old&#8217; directory.</li> - <li>Open the file <code>config/environment.rb</code> and look at the last line which should read: <code>SALT = "change-me"</code>. Change the word change-me to something else of your choosing. This string will be used as a &#8216;salt&#8217; 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.</li> - <li>In <code>database.yml</code> insert your old database name, user and password under the &#8216;development&#8217; section. If you are using SQLite3 rather than MySQL or PostgreSQL, you need only the database name, and to change the &#8216;adapter&#8217; line to &#8216;sqlite3&#8217;. You also need to copy (NOT MOVE!), your SQLite3 database from your tracks-old <code>db</code> directory to your new tracks <code>db</code> directory</li> - <li>Run the command <code>rake extract_fixtures</code> inside the Tracks directory. This will populate the <code>db/exported_fixtures</code> directory with <code>*.yml</code> files corresponding to the contexts, projects and todos table from the contents of your old database.</li> - <li>Open <code>db/exported_fixtures/todos.yml</code> and search for the lines starting <code>created:</code> and replace with <code>created_at:</code>. If you are using SQLite3, you also need to change the following: <code>done: "0"</code> with <code>done: "f"</code> and <code>done: "1"</code> with <code>done: "t"</code>. You need to replace the similar &#8216;done&#8217; lines in <code>projects.yml</code>, and in <code>contexts.yml</code> replace <code>hide: "0"</code> with <code>hide: "f"</code> and <code>hide: "1"</code> with <code>hide: "t"</code>.</li> - <li>Create a new MySQL database (named tracks1043, for example). In <code>database.yml</code> insert this new database name, user and password under the &#8216;development&#8217; and &#8216;production&#8217; sections. If you are using SQLite3, insert a new name for a database to hold your Tracks 1.043 data.</li> - <li>Run the command <code>rake db_schema_import</code> inside the Tracks directory. This should import the upgraded schema for 1.043 into your new database.</li> - <li> Run the command <code>rake load_exported_fixtures</code> which will import the contents of your old database from the fixtures files in <code>db/exported_fixtures</code>.</li> - <li> If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) [1] of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li> - <li> Try starting up the server with <code>script/server</code> to make sure that all your data has migrated successfully. If all is well, follow the instructions above to <a href="upgrading_1043">upgrade from version 1.043</a> to Tracks 1.6. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</li> - </ol> - - - <p id="fn1">¹ The <code>env</code> binary helps to locate other binaries, regardless of their location. If you don&#8217;t have <code>env</code> installed, you&#8217;ll need to change this line to point to the location of your Ruby binary.</p> + <li>Before you do anything else, <strong>BACK UP YOUR DATABASE</strong> (tables and content) and keep the SQL dumps somewhere safe so that you can recreate the old database if necesary.</li> + <li>Download a copy of Tracks 1.043 and unzip alongside your &#8216;tracks-old&#8217; directory.</li> + <li>Open the file <code>config/environment.rb</code> and look at the last line which should read: <code>SALT = "change-me"</code>. Change the word change-me to something else of your choosing. This string will be used as a &#8216;salt&#8217; 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.</li> + <li>In <code>database.yml</code> insert your old database name, user and password under the &#8216;development&#8217; section. If you are using SQLite3 rather than MySQL or PostgreSQL, you need only the database name, and to change the &#8216;adapter&#8217; line to &#8216;sqlite3&#8217;. You also need to copy (NOT MOVE!), your SQLite3 database from your tracks-old <code>db</code> directory to your new tracks <code>db</code> directory</li> + <li>Run the command <code>rake extract_fixtures</code> inside the Tracks directory. This will populate the <code>db/exported_fixtures</code> directory with <code>*.yml</code> files corresponding to the contexts, projects and todos table from the contents of your old database.</li> + <li>Open <code>db/exported_fixtures/todos.yml</code> and search for the lines starting <code>created:</code> and replace with <code>created_at:</code>. If you are using SQLite3, you also need to change the following: <code>done: "0"</code> with <code>done: "f"</code> and <code>done: "1"</code> with <code>done: "t"</code>. You need to replace the similar &#8216;done&#8217; lines in <code>projects.yml</code>, and in <code>contexts.yml</code> replace <code>hide: "0"</code> with <code>hide: "f"</code> and <code>hide: "1"</code> with <code>hide: "t"</code>.</li> + <li>Create a new MySQL database (named tracks1043, for example). In <code>database.yml</code> insert this new database name, user and password under the &#8216;development&#8217; and &#8216;production&#8217; sections. If you are using SQLite3, insert a new name for a database to hold your Tracks 1.043 data.</li> + <li>Run the command <code>rake db_schema_import</code> inside the Tracks directory. This should import the upgraded schema for 1.043 into your new database.</li> + <li>Run the command <code>rake load_exported_fixtures</code> which will import the contents of your old database from the fixtures files in <code>db/exported_fixtures</code>.</li> + <li>If you are using Windows, you may need to check the &#8216;shebang&#8217; lines (<code>#!/usr/bin/env ruby</code>) <sup class="footnote"><a href="#fn1">1</a></sup> of the <code>/public/dispatch.*</code> files and all the files in the <code>/script</code> directory. They are set to <code>#!/usr/bin/env ruby</code> by default. Check the format of those lines in your old installation, and change the new ones as necessary.</li> + <li>Try starting up the server with <code>script/server</code> to make sure that all your data has migrated successfully. If all is well, follow the instructions above to [upgrade from version 1.043][upgrading_1043] to Tracks 1.6. If you need to access Tracks from a mobile/cellular phone browser, visit <code>http://yourdomain.com/mobile/</code>. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.</li> +</ol> +<p class="footnote" id="fn1">¹ The <code>env</code> binary helps to locate other binaries, regardless of their location. If you don&#8217;t have <code>env</code> installed, you&#8217;ll need to change this line to point to the location of your Ruby binary.</p> </div> output/printed/manual.html 29aecda6159b742843e607e0a1bdb45b0ab158dc bsag butshesagirl@rousette.org.uk http://github.com/bsag/tracks_manual/commit/46e9efd2efdf1c26e7408f77c8cf12c1436512b1 46e9efd2efdf1c26e7408f77c8cf12c1436512b1 2009-08-30T04:35:15-07:00 2009-08-30T04:35:15-07:00 Updated JumpBox links to affiliate links. 74dca037cebc888370a2f596f54c8af9badeac86 bsag butshesagirl@rousette.org.uk