Andreas/tracks
1
0
Fork 0
mirror of https://github.com/TracksApp/tracks.git synced 2025-12-27 04:18:49 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Convert documentation to Markdown using Pandoc

Browse source
This commit is contained in:
Daniel Rice 2014-08-20 16:05:31 -04:00
parent ee51639780
commit 41764d8bc2
4 changed files with 115 additions and 123 deletions
Download patch file Download diff file Expand all files Collapse all files

93
doc/installation.md Normal file
View file

@ -0,0 +1,93 @@
# Installing Tracks
The following instructions will guide you through the installation of Tracks from source.
This description is intended for people installing Tracks from scratch. If you would like to upgrade an existing installation, please see the [upgrade documentation](upgrading.md).
Various Tracks users have contributed installation howtos for specific environments. They are [on the wiki](https://github.com/TracksApp/tracks/wiki/Installation-index).
If you are not confident installing Tracks from source using these instructions, there are several alternative options provided by third parties:
* If you’d like to install Tracks on a local machine, try the packaged version offered by [Bitnami](http://bitnami.org/stack/tracks) — it runs on Windows, Mac OS X and Linux.
* If you’d like to run Tracks within a dedicated virtual machine, [JumpBox](http://jumpbox.com/app/tracks) provides preconfigured virtual machine images.
* Several providers offer individual Tracks user accounts. A list of these providers can be found [on the wiki](https://github.com/TracksApp/tracks/wiki/Tracks-hosting).
(Please note that these third-party options may use older versions of Tracks.)
## Prerequisites
Tracks has a few software requirements that must be satisfied before installation:
1. **Ruby**. Tracks requires Ruby 1.9.2 or greater.
2. **Bundler**. Tracks requires a recent version of [Bundler](http://bundler.io) to handle the installation of dependencies. Bundler is typically installed by running `gem install bundler`.
3. **Database**. Tracks is tested on [MySQL](http://www.mysql.com/), but [SQLite](http://www.sqlite.org/) and [PostgreSQL](http://www.postgresql.org/) can also be used. Of the three, SQLite requires the least configuration. Whatever your choice, the appropriate database software must be installed.
## Get Tracks
There are two methods of downloading Tracks:
1. (Recommended for most people) Download the [zipped package](https://github.com/TracksApp/tracks/archive/v2.2.2.zip) for the latest stable release (2.2.2) and unzip in your preferred location (e.g. `~/Sites` for Mac OS X users).
2. 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):
<!-- -->
cd ~/Sites
git clone https://github.com/TracksApp/tracks.git
cd tracks
## Set up the database
*This section only applies if you will be using Tracks with a MySQL database.*
You need to create a database and database-user to use with Tracks. For this, you can use MySQL Administrator or go into a terminal and issue the following commands:
mysql -uroot -p
mysql> CREATE DATABASE tracks;
mysql> GRANT ALL PRIVILEGES ON tracks.* TO yourmysqluser@localhost \
IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION;
## Install dependencies
Tracks is built upon a number of Ruby libraries (known as ‘gems’). The Bundler tool makes it easy to install all the gems that Tracks needs, and ensures that they are all the correct versions.
1. Edit the file `Gemfile` in the Tracks root directory. You may comment out any database drivers you will not be using. You may also comment out `therubyracer` if you are installing Tracks on Windows or Mac OS X, or if you have another JavaScript runtime such as Node.js installed.
2. Run the command `bundle install --without development test` in the directory that you unzipped your Tracks download to.
3. Wait for Bundler to finish installing the necessary gems that Tracks needs. This can take some time depending on the speed of your internet connection and the speed of the system you’re installing Tracks on.
## Configure variables
1. In the `config` folder, copy the files `database.yml.tmpl` and `site.yml.tmpl` to `database.yml` and `site.yml`, respectively.
2. Open the file `config/database.yml` and edit the `production:` section with the details of your database. If you are using MySQL the `adapter:` line should read `adapter: mysql2`, `host: localhost` (in the majority of cases), and your username and password should match those you assigned when you created the database. If you are using SQLite3, you should have only two lines under the production section: `adapter: sqlite3` and `database: db/tracks.db`.
3. Open the file `config/site.yml`, and read through the settings to make sure that they suit your setup. In most cases, all you need to change are the `salt: "change-me"` line (change the string “change-me” to some other string of your choice), the administrator email address (`admin_email`), and the time zone setting. For the time zone setting you can use the command `bundle exec rake time:zones:local` to see all available timezones on your machine
4. If you are using Windows, you may need to check the ‘shebang’ lines (`#!/usr/bin/env ruby`) of the `/public/dispatch.*` files and all the files in the `/script` directory. They are set to `#!/usr/bin/env ruby` by default. This should work for all Unix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like `#c:/ruby/bin/ruby` to point to the Ruby binary on your system.
5. If you intend to deploy Tracks with the built in webserver called WEBrick, you’ll need to change `config.serve_static_assets` to `true` in `config/environments/production.rb` in order for the images, stylesheets, and javascript files to be served correctly.
## Populate your database with the Tracks schema
Open a terminal and change into the root of your Tracks directory. Enter the following command:
bundle exec rake db:migrate RAILS_ENV=production
This will set up your database with the required structure to hold Tracks’ data.
## Precompile assets
Static assets (images, stylesheets, and javascript) need to be compiled in order for them to work correctly with the new asset pipeline feature in Rails. Precompiling your assets is as simple as running the following command while inside the Tracks root directory:
bundle exec rake assets:precompile RAILS_ENV=production
## Start the server
While still in the Terminal inside the Tracks root directory, issue the following command:
bundle exec rails server -e production
If all goes well, you should see some text informing you that the WEBrick server is running: `=> Rails application starting in production on http://0.0.0.0:3000`. If you are already running other services on port 3000, you need to select a different port when running the server, using the `-p` option.
## Visit Tracks in a browser
Visit `http://0.0.0.0:3000/signup` in a browser (or whatever URL and port was reported when you started the server in the step above) and chose a user name and password for admin user. Once logged in as admin, you can add other (ordinary level) users. If you need to access Tracks from a mobile/cellular phone browser, visit `http://yourdomain.com/mobile/`. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.
## Customise Tracks
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!

101
doc/installation.textile
View file

@ -1,101 +0,0 @@
h1. Installing Tracks
The following instructions will guide you through the installation of Tracks from source.
This description is intended for people installing Tracks from scratch. If you would like to upgrade an existing installation, please see the "upgrade documentation":upgrading.textile.
Various Tracks users have contributed installation howtos for specific environments. They are "on the wiki":https://github.com/TracksApp/tracks/wiki/Installation-index.
If you are not confident installing Tracks from source using these instructions, there are several alternative options provided by third parties:
* If you'd like to install Tracks on a local machine, try the packaged version offered by "Bitnami":http://bitnami.org/stack/tracks -- it runs on Windows, Mac OS X and Linux.
* If you'd like to run Tracks within a dedicated virtual machine, "JumpBox":http://jumpbox.com/app/tracks provides preconfigured virtual machine images.
* Several providers offer individual Tracks user accounts. A list of these providers can be found "on the wiki":https://github.com/TracksApp/tracks/wiki/Tracks-hosting.
(Please note that these third-party options may use older versions of Tracks.)
h2. Prerequisites
Tracks has a few software requirements that must be satisfied before installation:
# *Ruby*. Tracks requires Ruby 1.9.2 or greater.
# *Bundler*. Tracks requires a recent version of "Bundler":http://bundler.io to handle the installation of dependencies. Bundler is typically installed by running @gem install bundler@.
# *Database*. Tracks is tested on "MySQL":http://www.mysql.com/, but "SQLite":http://www.sqlite.org/ and "PostgreSQL":http://www.postgresql.org/ can also be used. Of the three, SQLite requires the least configuration. Whatever your choice, the appropriate database software must be installed.
h2. Get Tracks
There are two methods of downloading Tracks:
# (Recommended for most people) Download the "zipped package":https://github.com/TracksApp/tracks/archive/v2.2.2.zip for the latest stable release (2.2.2) and unzip in your preferred location (e.g. @~/Sites@ for Mac OS X users).
# 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):
bc. cd ~/Sites
git clone https://github.com/TracksApp/tracks.git
cd tracks
h2. Set up the database
_This section only applies if you will be using Tracks with a MySQL database._
You need to create a database and database-user to use with Tracks. For this, you can use MySQL Administrator or go into a terminal and issue the following commands:
bc. mysql -uroot -p
mysql> CREATE DATABASE tracks;
mysql> GRANT ALL PRIVILEGES ON tracks.* TO yourmysqluser@localhost \
IDENTIFIED BY 'password-goes-here' WITH GRANT OPTION;
h2. Install dependencies
Tracks is built upon a number of Ruby libraries (known as 'gems'). The Bundler tool makes it easy to install all the gems that Tracks needs, and ensures that they are all the correct versions.
# Edit the file @Gemfile@ in the Tracks root directory. You may comment out any database drivers you will not be using. You may also comment out @therubyracer@ if you are installing Tracks on Windows or Mac OS X, or if you have another JavaScript runtime such as Node.js installed.
# Run the command @bundle install --without development test@ in the directory that you unzipped your Tracks download to.
# Wait for Bundler to finish installing the necessary gems that Tracks needs. This can take some time depending on the speed of your internet connection and the speed of the system you're installing Tracks on.
h2. Configure variables
# In the @config@ folder, copy the files @database.yml.tmpl@ and @site.yml.tmpl@ to @database.yml@ and @site.yml@, respectively.
# Open the file @config/database.yml@ and edit the @production:@ section with the details of your database. If you are using MySQL the @adapter:@ line should read @adapter: mysql2@, @host: localhost@ (in the majority of cases), and your username and password should match those you assigned when you created the database. If you are using SQLite3, you should have only two lines under the production section: @adapter: sqlite3@ and @database: db/tracks.db@.
# Open the file @config/site.yml@, and read through the settings to make sure that they suit your setup. In most cases, all you need to change are the @salt: "change-me"@ line (change the string "change-me" to some other string of your choice), the administrator email address (@admin_email@), and the time zone setting. For the time zone setting you can use the command @bundle exec rake time:zones:local@ to see all available timezones on your machine
# If you are using Windows, you may need to check the 'shebang' lines (@#!/usr/bin/env ruby@) of the @/public/dispatch.*@ files and all the files in the @/script@ directory. They are set to @#!/usr/bin/env ruby@ by default. This should work for all Unix based setups (Linux or Mac OS X), but Windows users will probably have to change it to something like @#c:/ruby/bin/ruby@ to point to the Ruby binary on your system.
# If you intend to deploy Tracks with the built in webserver called WEBrick, you'll need to change @config.serve_static_assets@ to @true@ in @config/environments/production.rb@ in order for the images, stylesheets, and javascript files to be served correctly.
h2. Populate your database with the Tracks schema
Open a terminal and change into the root of your Tracks directory. Enter the following command:
bc. bundle exec rake db:migrate RAILS_ENV=production
This will set up your database with the required structure to hold Tracks' data.
h2. Precompile assets
Static assets (images, stylesheets, and javascript) need to be compiled in order for them to work correctly with the new asset pipeline feature in Rails. Precompiling your assets is as simple as running the following command while inside the Tracks root directory:
bc. bundle exec rake assets:precompile RAILS_ENV=production
h2. Start the server
While still in the Terminal inside the Tracks root directory, issue the following command:
bc. bundle exec rails server -e production
If all goes well, you should see some text informing you that the WEBrick server is running: @=> Rails application starting in production on http://0.0.0.0:3000@. If you are already running other services on port 3000, you need to select a different port when running the server, using the @-p@ option.
h2. Visit Tracks in a browser
Visit @http://0.0.0.0:3000/signup@ in a browser (or whatever URL and port was reported when you started the server in the step above) and chose a user name and password for admin user. Once logged in as admin, you can add other (ordinary level) users. If you need to access Tracks from a mobile/cellular phone browser, visit @http://yourdomain.com/mobile/@. This mobile version is a special, lightweight version of Tracks, designed to use on a mobile browser.
h2. Customise Tracks
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!

22
doc/upgrading.md Normal file
View file

@ -0,0 +1,22 @@
# Upgrading Tracks
## Upgrading from Tracks 2.2 to 2.3devel
WARNING: 2.3devel is a development tree of Tracks and may (will?) contain bugs that might destroy your data! It is not recommended to upgrade to 2.3devel unless you know what you are doing.
That said. To upgrade:
1. Back up your existing database and installation of Tracks
2. Install Tracks 2.3devel in a new directory. Or you can create a separate installation of 2.3 for testing purposes.
3. Copy over the configuration from your previous Tracks installation. If using SQLite3, copy the old database into the new Tracks 2.3devel directory.
4. Check that you have all dependencies installed: `bundle install --without development test` Or leave out the `--without development test` part if you intend to test or develop on this tree.
5. Run `bundle exec rake db:migrate RAILS_ENV=production` to update your old database to the new schema. This is the point of no return. Make sure you have backups!
6. Precompile your static assets (css, javascript, etc.) by running `bundle exec rake assets:precompile RAILS_ENV=production`.
7. Run `bundle exec rails server -e production` inside your Tracks 2.3devel directory to start up Tracks. Or use `-e development` if you intend to try your changes and get more log info.
Please note that if you intend to use Tracks with the built in webserver called WEBrick for production, you’ll need to change `config.serve_static_assets` to `true` in `config/environments/production.rb` in order for the images, stylesheets, and javascript files to be served correctly.
The Czech locale has been renamed from `cz` to `cs` in accordance with ISO standards. Users of the Czech locale will need to edit their preferences and reselect the locale under the new name.
## Upgrading from older versions of Tracks
Upgrade to Tracks 2.2.2 first. Follow the upgrade instructions included in Tracks 2.2.2.

22
doc/upgrading.textile
View file

@ -1,22 +0,0 @@
h1. Upgrading Tracks
h2. Upgrading from Tracks 2.2 to 2.3devel
WARNING: 2.3devel is a development tree of Tracks and may (will?) contain bugs that might destroy your data! It is not recommended to upgrade to 2.3devel unless you know what you are doing.
That said. To upgrade:
# Back up your existing database and installation of Tracks
# Install Tracks 2.3devel in a new directory. Or you can create a separate installation of 2.3 for testing purposes.
# Copy over the configuration from your previous Tracks installation. If using SQLite3, copy the old database into the new Tracks 2.3devel directory.
# Check that you have all dependencies installed: @bundle install --without development test@ Or leave out the @--without development test@ part if you intend to test or develop on this tree.
# Run @bundle exec rake db:migrate RAILS_ENV=production@ to update your old database to the new schema. This is the point of no return. Make sure you have backups!
# Precompile your static assets (css, javascript, etc.) by running @bundle exec rake assets:precompile RAILS_ENV=production@.
# Run @bundle exec rails server -e production@ inside your Tracks 2.3devel directory to start up Tracks. Or use @-e development@ if you intend to try your changes and get more log info.
Please note that if you intend to use Tracks with the built in webserver called WEBrick for production, you'll need to change @config.serve_static_assets@ to @true@ in @config/environments/production.rb@ in order for the images, stylesheets, and javascript files to be served correctly.
The Czech locale has been renamed from @cz@ to @cs@ in accordance with ISO standards. Users of the Czech locale will need to edit their preferences and reselect the locale under the new name.
h2. Upgrading from older versions of Tracks
Upgrade to Tracks 2.2.2 first. Follow the upgrade instructions included in Tracks 2.2.2.