Skip to content

Latest commit

 

History

History
190 lines (122 loc) · 6.98 KB

SETUP_DEVELOPMENT.md

File metadata and controls

190 lines (122 loc) · 6.98 KB
Raw

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.

This document describes how to setup Foodsoft for development within your local system. Another option is to use docker for development. If instead you just want to run Foodsoft without changing its code, please refer to hosting or deployment.

System requirements: RVM, Ruby 2+, Bundler, MySQL/PostgreSQL/SQLite.

Optional: Redis.

Getting started

  1. Clone the repository from GitHub:

     git clone https://github.com/foodcoops/foodsoft.git

    This brings up the bleeding-edge development version, which might contain some unfinished parts. If you want to be safe, choose the last release: git checkout $(git tag -l | grep ^v | sort -rn | head -n1)

    Note: When developing on Windows you might run into issues with shell scripts because of Git auto-crlf. Have a look how to avoid that in the Docker Development Setup instructions.

  2. Install RVM and Ruby 2.4+ (if you have not done so before):

     \curl -L https://get.rvm.io | bash
 source ~/.rvm/scripts/rvm
 rvm install 2.4

    We try to keep Foodsoft compatible with Ruby 2.4 as well as any later versions, so if you use this and don't want to use RVM, that might actually work.

  3. Install system dependencies.

    For Debian/Ubuntu, that's libv8-dev libmysqlclient-dev libxml2-dev libxslt1-dev libffi-dev libreadline-dev libmagic-dev:

     # Debian/Ubuntu
 sudo apt-get install libv8-dev libmysqlclient-dev libxml2-dev libxslt1-dev libffi-dev libreadline-dev libmagic-dev

    For CentOS/Redhat you need v8 community-mysql-devel libxml2-devel libxslt-devel libffi-devel readline-devel file-devel:

     # CentOS/Redhat
 sudo yum install v8 community-mysql-devel libxml2-devel libxslt-devel libffi-devel readline-devel file-devel

  4. Install Ruby dependencies:

     bundle install

  5. Setup your development environment:

     rake foodsoft:setup_development

    This will interactively prompt with several questions relating to your required environment.

    Important: After selecting your database type, rake will create the file config/database.yml, which then then be edited with working username and password credentials for the database. These fields must be added for development AND (temporary) test databases. Then continue with confirmation in rake dialogue.

  6. Start rails by running:

     bundle exec rails s

  7. Open your favorite browser and open the web application at:

     http://localhost:3000/

    You might want to watch a kitten video while it's loading.

  8. Login using the default credentials: admin/secret

  9. Change the admin password, just in case.

  10. Have phun!

For running integration tests, you also need the Chromium/Chrome web browser. On Debian that would be sudo apt-get install chromium, on Ubuntu sudo apt-get install chromium-browser.

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 database

    Create the database configuration from the default:

     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. 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'.

  5. (optional) Get background jobs done

    Time intensive tasks may block the web request. To run these in a separate task, you can install Redis and enable Resque:

    • Comment Resque.inline = true in config/environments/development.rb
    • Install Redis (Ubuntu package redis-server)
    • Run the worker: rake resque:work QUEUE=foodsoft_notifier

    To have look on the current queue, failed jobs etc start the resque server with resque-web.

  6. (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

Docker

To avoid having to go through setting up all dependencies, you can also run Foodsoft within a docker image. While the default Dockerfile is setup for production, Dockerfile-dev is meant for development. Even better, you can use docker-compose (using docker-compose-dev.yml) to setup the whole stack at once.

See Setup Development Docker for a detailed description.