split and cleanup documentation [ci skip]
This commit is contained in:
wvengen
parent
50d2991cc0
commit
75059d5bcf
4 changed files with 168 additions and 155 deletions
69
README.md
69
README.md
|
|
@ -3,78 +3,29 @@ FoodSoft
|
||||||
[](https://travis-ci.org/foodcoops/foodsoft)
|
[](https://travis-ci.org/foodcoops/foodsoft)
|
||||||
[](https://codeclimate.com/github/foodcoops/foodsoft)
|
[](https://codeclimate.com/github/foodcoops/foodsoft)
|
||||||
[](https://gemnasium.com/foodcoops/foodsoft)
|
[](https://gemnasium.com/foodcoops/foodsoft)
|
||||||
[](https://bitdeli.com/free "Bitdeli Badge")
|
[](https://bitdeli.com/foodcoops "Bitdeli Badge")
|
||||||
|
|
||||||
Web-based software to manage a non-profit food coop (product catalog, ordering, accounting, job scheduling).
|
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).
|
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
|
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
|
Deploying
|
||||||
---------
|
---------
|
||||||
|
|
||||||
As you might have noticed, documentation is scarce and insufficient. If you
|
Please see [doc/SETUP_PRODUCTION](https://github.com/foodcoops/foodsoft/blob/master/doc/SETUP_PRODUCTION.md),
|
||||||
intend to deploy foodsoft in production, we would love to guide you through
|
as well as[doc/DEPLOYMENT](https://github.com/foodcoops/foodsoft/blob/master/doc/DEPLOYMENT.md).
|
||||||
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.
|
|
||||||
|
|
||||||
License
|
License
|
||||||
-------
|
-------
|
||||||
|
|
|
||||||
|
|
@ -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
|
|
||||||
147
doc/SETUP_DEVELOPMENT.md
Normal file
147
doc/SETUP_DEVELOPMENT.md
Normal file
|
|
@ -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
|
||||||
|
```
|
||||||
|
|
||||||
11
doc/SETUP_PRODUCTION.md
Normal file
11
doc/SETUP_PRODUCTION.md
Normal file
|
|
@ -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.
|
||||||
|
|
||||||
Loading…
Reference in a new issue