From 75059d5bcf77a3f230da738c534f324302d2bb61 Mon Sep 17 00:00:00 2001 From: wvengen Date: Tue, 29 Oct 2013 15:27:26 +0100 Subject: [PATCH] split and cleanup documentation [ci skip] --- README.md | 69 +++--------------- doc/DEVELOPMENT.md | 96 ------------------------- doc/SETUP_DEVELOPMENT.md | 147 +++++++++++++++++++++++++++++++++++++++ doc/SETUP_PRODUCTION.md | 11 +++ 4 files changed, 168 insertions(+), 155 deletions(-) delete mode 100644 doc/DEVELOPMENT.md create mode 100644 doc/SETUP_DEVELOPMENT.md create mode 100644 doc/SETUP_PRODUCTION.md diff --git a/README.md b/README.md index edd45078..a1067c12 100644 --- a/README.md +++ b/README.md @@ -3,78 +3,29 @@ FoodSoft [![Build Status](https://travis-ci.org/foodcoops/foodsoft.png)](https://travis-ci.org/foodcoops/foodsoft) [![Code Climate](https://codeclimate.com/github/foodcoops/foodsoft.png)](https://codeclimate.com/github/foodcoops/foodsoft) [![Dependency Status](https://gemnasium.com/foodcoops/foodsoft.png)](https://gemnasium.com/foodcoops/foodsoft) -[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/foodcoops/foodsoft/trend.png)](https://bitdeli.com/free "Bitdeli Badge") +[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/foodcoops/foodsoft/trend.png)](https://bitdeli.com/foodcoops "Bitdeli Badge") Web-based software to manage a non-profit food coop (product catalog, ordering, accounting, job scheduling). +If you're a food coop considering to use foodsoft, please have a look at the [wiki page for foodcoops](https://github.com/foodcoops/foodsoft/wiki/For-foodcoops). When you'd like to experiment with or develop foodsoft, see [doc/SETUP_DEVELOPMENT](https://github.com/foodcoops/foodsoft/blob/master/doc/SETUP_DEVELOPMENT.md) on how to set it up on your own computer. + More information about using this software and contributing can be found on the [wiki](https://github.com/foodcoops/foodsoft/wiki). -System requirements -------------------- - -* [RVM](https://rvm.io/rvm/install) -* [Ruby 1.9.3](https://www.ruby-lang.org/en/downloads/) -* [Bundler](http://bundler.io/) - -Getting started ---------------- - -1. Install RVM (if you have not done so before): - ``` - \curl -L https://get.rvm.io | bash - ``` - -2. Clone the repository from GitHub: - ``` - git clone https://github.com/foodcoops/foodsoft.git - ``` - -3. Install Ruby dependencies: - ``` - bundle install - ``` - -4. Setup your development environment: - ``` - rake foodsoft:setup_development - ``` - This will interactively prompt with several questions relating to your - required environment. - -5. Start rails by running: - ``` - bundle exec rails s - ``` - -6. Open your favorite browser and open the web application at: - ``` - http://localhost:3000/ - ``` - You might want to watch a - [kitten video](https://www.youtube.com/watch?v=9Iq5yCoHp4o) - while it's loading. - -7. Login using the default credentials: `admin/secret` - -8. Change the admin password, just in case. - -9. Have phun! Developing ---------- -Have a look at [DEVELOPMENT.md](https://github.com/foodcoops/foodsoft/blob/master/doc/DEVELOPMENT.md) (outdated) and the (more recent) [Developing Guidelines](https://github.com/foodcoops/foodsoft/wiki/Developing-Guidelines) page on the wiki. +Get foodsoft [running locally](https://github.com/foodcoops/foodsoft/blob/master/doc/SETUP_DEVELOPMENT.md), +then visit our [Developing Guidelines](https://github.com/foodcoops/foodsoft/wiki/Developing-Guidelines) +page on the wiki. + Deploying --------- -As you might have noticed, documentation is scarce and insufficient. If you -intend to deploy foodsoft in production, we would love to guide you through -the process. You can contact the mailing list -[foodsoft-discuss](http://foodsoft.51229.x6.nabble.com/foodsoft-discuss-f5.html), -or mail some of us directly at -[developers@foodcoop.nl](mailto:developers@foodcoop.nl) or -foodsoft (at) foodcoops.net. +Please see [doc/SETUP_PRODUCTION](https://github.com/foodcoops/foodsoft/blob/master/doc/SETUP_PRODUCTION.md), +as well as[doc/DEPLOYMENT](https://github.com/foodcoops/foodsoft/blob/master/doc/DEPLOYMENT.md). + License ------- diff --git a/doc/DEVELOPMENT.md b/doc/DEVELOPMENT.md deleted file mode 100644 index fb226daf..00000000 --- a/doc/DEVELOPMENT.md +++ /dev/null @@ -1,96 +0,0 @@ -README for DEVELopment Project Setup -==================================== - -Gratulations, you have successfully cloned the foodsoft project -from the git repository. Now you are only a few steps away from -trying it out and then jumping into development. (This manual presumes -you have ruby and rails setup.) - -(1) Configure datebase ----------------------- -Create the database configuration from the default: - - cp config/database.yml.SAMPLE config/database.yml - -If you are fine with using a file-based sqlite database you are all set. -The sqlite files (development/test/production) will reside in the "db" directory. -Otherwise you would want to edit database.yml to suit your needs (MySQL whatever). - - -(2) Configure development environment -------------------------------------- -Again, you need to create your own copy of the default configuration: - - cp config/environments/development.rb.SAMPLE config/environments/development.rb - -Edit development.rb to specify your settings (at least the ActionMailer SMTP settings). -If you just leave the file as is, emails will not work but everything else should be okay. - - -(3) Foodsoft settings ---------------------- -You need to create your own copy of the foodsoft configuration settings: - - cp config/app_config.yml.SAMPLE config/app_config.yml - -Edit app_config.yml to suit your needs or just keep the defaults for now. - - -(4) Secret Token -------------------- -The user session are stored in cookies. Do avoid misusing the cookies and its sensitive information, rails -will encrypt it with a token. So copy the config file - - cp config/initializers/secret_token.rb.SAMPLE config/initializers/secret_token.rb - -and modify the token!! - - -(5) Required ruby and gems -------------------- -We recommend to use rvm (https://rvm.beginrescueend.com/). Install rvm and get the latest ruby (>= 1.9.3). -If installed you only need to install the gem bundler: - - gem install bundler - -After that you get the other gems easily with (from project root): - - bundle install - - -(6) Create database (schema) and load defaults --------------------------- - rake db:setup - -With this, you also get a ready to go user with username 'admin' and password 'secret'. - - -(7) Try it out! ---------------- -Start the WEBrick server to try it out: - - bundle exec rails s - - -(8) (optional) Get background jobs done ---------------------------------------- -We use for time intensive tasks a background job queue, at the moment resque with redis as key/value store. -Install redis (in ubuntu the package redis-server works out of the box) and start the resque worker with: - - rake resque:work QUEUE=foodsoft_notifier - -To have look on the current queue, failed jobs etc start the resque server with - - resque-web - - -(9) (optional) View mails in browser instead in your logs ---------------------------------------------------------- -We use mailcatcher in development mode to view all delivered mails in a browser interface. -Just install mailcatcher with gem install mailcatcher and start the service with - - mailcatcher - -From now on you have a smpt server listening on 1025. To see the emails go to - - http://localhost:1080 diff --git a/doc/SETUP_DEVELOPMENT.md b/doc/SETUP_DEVELOPMENT.md new file mode 100644 index 00000000..18a2b16f --- /dev/null +++ b/doc/SETUP_DEVELOPMENT.md @@ -0,0 +1,147 @@ +Getting foodsoft running for development +======================================== + +Gratulations, if you read this file locally, you have successfully cloned the +foodsoft project from the git repository. Now you are only a few steps away +from trying it out and then jumping into development. + +**System requirements**: +[RVM](https://rvm.io/rvm/install), +[Ruby 1.9.3](https://www.ruby-lang.org/en/downloads/) and +[Bundler](http://bundler.io/). + +Getting started +--------------- + +0. Clone the repository from GitHub: + ``` + git clone https://github.com/foodcoops/foodsoft.git + ``` + +1. Install RVM and Ruby 1.9.3 (if you have not done so before): + ``` + \curl -L https://get.rvm.io | bash + source ~/.rvm/scripts/rvm + rvm install 1.9.3 + ``` + +2. Install Ruby dependencies: + ``` + bundle install + ``` + +3. Setup your development environment: + ``` + rake foodsoft:setup_development + ``` + This will interactively prompt with several questions relating to your + required environment. + +4. Start rails by running: + ``` + bundle exec rails s + ``` + +5. Open your favorite browser and open the web application at: + ``` + http://localhost:3000/ + ``` + You might want to watch a + [kitten video](https://www.youtube.com/watch?v=9Iq5yCoHp4o) + while it's loading. + +6. Login using the default credentials: `admin/secret` + +7. Change the admin password, just in case. + +8. Have phun! + + + +Manual configuration +-------------------- + +The rake task `foodsoft:setup_development` helps you to setup foodsoft. +If you want to have more control, you can do these steps manually as +explained here. + + +1. **Configure datebase** + + Create the database configuration from the default: + ```sh + cp config/database.yml.SQLite_SAMPLE config/database.yml + ``` + If you are fine with using a file-based sqlite database you are all set. + The sqlite files (development/test/production) will reside in the "db" + directory. Otherwise you would want to copy one of the other + "database.yml.*_SAMPLE" files and edit database.yml to suit your needs. + + +2. **Configure development environment** + + Again, you need to create your own copy of the default configuration: + ``` + cp config/environments/development.rb.SAMPLE config/environments/development.rb + ``` + + Edit development.rb to specify your settings (at least the ActionMailer SMTP + settings). If you just leave the file as is, emails will not work but + everything else should be okay. + + +3. **Foodsoft settings** + + You need to create your own copy of the foodsoft configuration settings: + ``` + cp config/app_config.yml.SAMPLE config/app_config.yml + ``` + Edit app_config.yml to suit your needs or just keep the defaults for now. + + +4. **Secret token** + + The user session are stored in cookies. Do avoid misusing the cookies and + its sensitive information, rails will encrypt it with a token. So copy the + config file + ``` + cp config/initializers/secret_token.rb.SAMPLE config/initializers/secret_token.rb + ``` + and modify the token!! You can run `bundle exec rake secret` + + +5. **Create database (schema) and load defaults** + ``` + rake db:setup + ``` + With this, you also get a ready to go user with username 'admin' and + password 'secret'. + + +6. (optional) Get **background jobs** done + + We use for time intensive tasks a background job queue, at the moment resque + with redis as key/value store. Install redis (in ubuntu the package + redis-server works out of the box) and start the resque worker with: + ``` + rake resque:work QUEUE=foodsoft_notifier + ``` + To have look on the current queue, failed jobs etc start the resque server with + ``` + resque-web + ``` + + +7. (optional) **View mails in browser** instead in your logs + + We use mailcatcher in development mode to view all delivered mails in a + browser interface. Just install mailcatcher with gem install mailcatcher + and start the service with + ``` + mailcatcher + ``` + From now on you have a smtp server listening on 1025. To see the emails go to + ``` + http://localhost:1080 + ``` + diff --git a/doc/SETUP_PRODUCTION.md b/doc/SETUP_PRODUCTION.md new file mode 100644 index 00000000..58527034 --- /dev/null +++ b/doc/SETUP_PRODUCTION.md @@ -0,0 +1,11 @@ +Running foodsoft in production +============================== + +As you might have noticed, documentation is scarce and insufficient. If you +intend to deploy foodsoft in production, we would love to guide you through the +process. You can contact the mailing list +[foodsoft-discuss](http://foodsoft.51229.x6.nabble.com/foodsoft-discuss-f5.html), +or mail some of us directly at +[developers@foodcoop.nl](mailto:developers@foodcoop.nl) or foodsoft (at) +foodcoops.net. +