diff --git a/doc/SETUP_DEVELOPMENT.md b/doc/SETUP_DEVELOPMENT.md index 51a4e3c2..319c2787 100644 --- a/doc/SETUP_DEVELOPMENT.md +++ b/doc/SETUP_DEVELOPMENT.md @@ -11,132 +11,121 @@ If instead you just want to run Foodsoft without changing its code, please refer [deployment](https://github.com/foodcoops/foodsoft/wiki/Deployment-notes). **System requirements**: -[RVM](https://rvm.io/rvm/install), -[Ruby 2+](https://www.ruby-lang.org/en/downloads/), +[rbenv](https://github.com/rbenv/rbenv), +[Ruby 2.6+](https://www.ruby-lang.org/en/downloads/), [Bundler](http://bundler.io/), -[MySQL](http://mysql.com/)/[PostgreSQL](http://www.postgresql.org/)/[SQLite](http://sqlite.org/). - -**Optional**: -[Redis](http://redis.io/). +[MySQL](http://mysql.com/) / [SQLite](http://sqlite.org/), +[Redis](http://redis.io/) (optional). ### Getting started -0. Clone the repository from GitHub: +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)` + This brings up the bleeding-edge development version, which might contain some unfinished parts. + If you want to be safe, choose the last release: - *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](./SETUP_DEVELOPMENT_DOCKER.md#prerequisites-windows-only) - instructions. + git checkout $(git tag -l | grep ^v | sort -rn | head -n1) -1. Install RVM and Ruby 2.6+ (if you have not done so before): + *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](./SETUP_DEVELOPMENT_DOCKER.md#prerequisites-windows-only) + instructions. - \curl -L https://get.rvm.io | bash - source ~/.rvm/scripts/rvm - rvm install 2.6 +1. Install and setup rbenv and Bundler. For Debian/Ubuntu: - We try to keep Foodsoft compatible with Ruby 2.6 as well as any later versions, - so if you use this and don't want to use RVM, that might actually work. + sudo apt install rbenv + + For other distributions have a look at the rbenv [documentation](https://github.com/rbenv/rbenv). -2. Install system dependencies. + Add the following line to your `.bashrc`: - For Debian/Ubuntu, that's - [libv8-dev](https://packages.debian.org/stable/libv8-dev) - [libmysqlclient-dev](https://packages.debian.org/stable/libmysqlclient-dev) - [libxml2-dev](https://packages.debian.org/stable/libxml2-dev) - [libxslt1-dev](https://packages.debian.org/stable/libxslt1-dev) - [libffi-dev](https://packages.debian.org/stable/libffi-dev) - [libreadline-dev](https://packages.debian.org/stable/libreadline-dev) - [libmagic-dev](https://packages.debian.org/stable/libmagic-dev): + eval "$(rbenv init -)" - # Debian/Ubuntu - sudo apt-get install libv8-dev libmysqlclient-dev libxml2-dev libxslt1-dev libffi-dev libreadline-dev libmagic-dev + Install [ruby-build](https://github.com/rbenv/ruby-build): - For CentOS/Redhat you need - [v8](https://apps.fedoraproject.org/packages/v8) - [community-mysql-devel](https://apps.fedoraproject.org/packages/community-mysql-devel) - [libxml2-devel](https://apps.fedoraproject.org/packages/libxml2-devel) - [libxslt-devel](https://apps.fedoraproject.org/packages/libxslt-devel) - [libffi-devel](https://apps.fedoraproject.org/packages/libffi-devel) - [readline-devel](https://apps.fedoraproject.org/packages/readline-devel) - [file-devel](https://apps.fedoraproject.org/packages/file-devel): + mkdir -p "$(rbenv root)"/plugins + git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build + + Change to the Foodsoft directory and install the [recommended](https://github.com/foodcoops/foodsoft/blob/master/.ruby-version) + Ruby version: + + rbenv install "$(cat .ruby-version)" + + Now you can install [Bundler](https://bundler.io/): + + rbenv exec gem install bundler + +1. Install system dependencies. + + For Debian/Ubuntu, that's: + + sudo apt install libv8-dev default-libmysqlclient-dev libxml2-dev libxslt1-dev libffi-dev libreadline-dev libmagic-dev + + For CentOS/Redhat you need: - # CentOS/Redhat sudo yum install v8 community-mysql-devel libxml2-devel libxslt-devel libffi-devel readline-devel file-devel -3. Install Ruby dependencies: +1. Install Ruby dependencies: - bundle install + rbenv exec bundle install -4. Setup your development environment: +1. Setup your development environment: - rake foodsoft:setup_development + rbenv exec rails 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`, + **Important**: After selecting your database type, `rails` 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. + must be added for *development* AND (temporary) *test* databases. Then continue with confirmation in rails dialogue. -5. Start rails by running: +1. Start rails by running: - bundle exec rails s + rbenv exec rails s -6. Open your favorite browser and open the web application at: +1. Open your favorite browser and open the web browser at: http://localhost:3000/ - You might want to watch a - [kitten video](https://www.youtube.com/watch?v=9Iq5yCoHp4o) - while it's loading. + 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` +1. Login using the default credentials: `admin/secret` -8. Change the admin password, just in case. +1. Change the admin password, just in case. -9. Have phun! +1. 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 +On Debian that would be `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. - +The rails 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: + 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. + 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. +1. **Configure development environment** -2. **Configure development environment** - - Again, you need to create your own copy of the default configuration: + 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. + 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** +1. **Foodsoft settings** You need to create your own copy of the foodsoft configuration settings: @@ -144,37 +133,36 @@ explained here. Edit `app_config.yml` to suit your needs or just keep the defaults for now. +1. **Create database (schema) and load defaults** -4. **Create database (schema) and load defaults** + rbenv exec rails db:setup - rake db:setup + With this, you also get a ready to go user with username 'admin' and password 'secret'. - With this, you also get a ready to go user with username 'admin' and - password 'secret'. +1. (optional) Get **background jobs** done - -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: + 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](http://redis.io/) (Ubuntu package `redis-server`) - * Run the worker: `rake resque:work QUEUE=foodsoft_notifier` + * Install [Redis](http://redis.io/) (Debian/Ubuntu package `redis-server`) + * Run the worker: + + ``` + rbenv exec rails resque:work QUEUE=* + ``` 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 +1. (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 + browser interface. Just install mailcatcher with `rbenv exec 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 + From now on you have a smtp server listening on 1025. To see the emails go to: http://localhost:1080 @@ -187,4 +175,4 @@ within a docker image. While the default [`Dockerfile`](../Dockerfile) is setup use docker-compose (using [`docker-compose-dev.yml`](../docker-compose-dev.yml)) to setup the whole stack at once. -See [Setup Development Docker](./SETUP_DEVELOPMENT_DOCKER.md) for a detailed description. +See [Setup Development Docker](./SETUP_DEVELOPMENT_DOCKER.md) for a detailed description. \ No newline at end of file