From 1baa2a179eb41130e232c8c43c04858e6be607f7 Mon Sep 17 00:00:00 2001 From: Sylvain Date: Mon, 23 Mar 2020 15:03:09 +0100 Subject: [PATCH] Updated instructions to setup a development environment --- CHANGELOG.md | 1 + config/application.yml.default | 6 +- config/database.yml.default | 4 +- doc/archlinux_readme.md | 17 ---- doc/development_readme.md | 119 ++++++++------------------ docker/development/docker-compose.yml | 62 ++++++++++++++ docker/development/hosts | 10 +++ 7 files changed, 113 insertions(+), 106 deletions(-) delete mode 100644 doc/archlinux_readme.md create mode 100644 docker/development/docker-compose.yml create mode 100644 docker/development/hosts diff --git a/CHANGELOG.md b/CHANGELOG.md index 73f6335e8..0c22f4b86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ # Changelog Fab-manager +- Updated instructions to setup a development environment - Updated translations ## v4.3.2 2020 March 11 diff --git a/config/application.yml.default b/config/application.yml.default index 9213e4032..83d64de33 100644 --- a/config/application.yml.default +++ b/config/application.yml.default @@ -1,10 +1,10 @@ # Add application configuration variables here, as shown below. # Databases -POSTGRES_HOST: localhost +POSTGRES_HOST: fabmanager-postgres POSTGRES_PASSWORD: -REDIS_HOST: localhost -ELASTICSEARCH_HOST: localhost +REDIS_HOST: fabmanager-redis +ELASTICSEARCH_HOST: fabmanager-elastic # Stripe SECRET_KEY_BASE: 83daf5e7b80d990f037407bab78dff9904aaf3c195a50f84fa8695a22287e707dfbd9524b403b1dcf116ae1d8c06844c3d7ed942564e5b46be6ae3ead93a9d30 diff --git a/config/database.yml.default b/config/database.yml.default index 55839e171..00edc7d10 100644 --- a/config/database.yml.default +++ b/config/database.yml.default @@ -3,7 +3,7 @@ development: adapter: postgresql - host: localhost + host: fabmanager-postgres encoding: unicode database: fabmanager_development pool: 25 @@ -15,7 +15,7 @@ development: # Do not set this db to the same as development or production. test: adapter: postgresql - host: localhost + host: fabmanager-postgres encoding: unicode database: fabmanager_test pool: 25 diff --git a/doc/archlinux_readme.md b/doc/archlinux_readme.md deleted file mode 100644 index e17c964ac..000000000 --- a/doc/archlinux_readme.md +++ /dev/null @@ -1,17 +0,0 @@ -# Specific instructions concerning installation on ArchLinux - -## Ruby 2.3.0 -Ruby 2.3.0 has a known issue with openSSL version > 1.0 (which is ArchLinux default). -To overpass this problem, you must install ruby with special indication of the openSSL installation to use. - -```bash -# first, install GCC 5 from AUR (https://aur.archlinux.org/packages/gcc5/) -# you can use pacaur, yaourt or whatever you want ... -pacaur -S gcc5 -# then, install openssl-1.0 (in addition of 1.1) -sudo pacman -S openssl-1.0 -# finally, install ruby 2.3 using the bindings -CC=/usr/bin/gcc-5 PKG_CONFIG_PATH=/usr/lib/openssl-1.0/pkgconfig:/usr/lib/pkgconfig CFLAGS+=" -I/usr/include/openssl-1.0" LDFLAGS+=" -L/usr/lib/openssl-1.0 -lssl" rvm install 2.3.0 -``` - -There's also an issue with openSSL and `puma` but this is fixed by using puma version > 3. diff --git a/doc/development_readme.md b/doc/development_readme.md index 3c26c9de0..16bd6b7f4 100644 --- a/doc/development_readme.md +++ b/doc/development_readme.md @@ -5,12 +5,10 @@ This document will guide you through all the steps needed to set up a developmen ##### Table of contents 1. [General Guidelines](#general-guidelines)
-2. [PostgreSQL](#postgresql)
-2.1. [Install PostgreSQL 9.6](#setup-postgresql) +2. [PostgreSQL](#postgresql) 3. [ElasticSearch](#elasticsearch)
-3.1. [Install ElasticSearch](#setup-elasticsearch)
-3.2. [Rebuild statistics](#rebuild-stats)
-3.3. [Backup and Restore](#backup-and-restore-elasticsearch) +3.1. [Rebuild statistics](#rebuild-stats)
+3.2. [Backup and Restore](#backup-and-restore-elasticsearch) This procedure is not easy to follow so if you don't need to write some code for Fab-manager, please prefer the [docker-compose installation method](docker-compose_readme.md). @@ -19,8 +17,7 @@ This procedure is not easy to follow so if you don't need to write some code for ## General Guidelines 1. Install RVM, with the ruby version specified in the [.ruby-version file](../.ruby-version). - For more details about the process, please read the [official RVM documentation](http://rvm.io/rvm/install). - If you're using ArchLinux, you may have to [read this](archlinux_readme.md) before. + For more details about the process, please read the [official RVM documentation](http://rvm.io/rvm/install) 2. Install NVM, with the node.js version specified in the [.nvmrc file](../.nvmrc). For instructions about installing NVM, please refer to [the NVM readme](https://github.com/nvm-sh/nvm#installation-and-update). @@ -42,46 +39,55 @@ This procedure is not easy to follow so if you don't need to write some code for sudo reboot ``` -6. Create a docker network for Fab-manager. - You may have to change the network address if it is already in use. - > 🍏 If you're using MacOS, this is not required. - ```bash - docker network create --subnet=172.18.0.0/16 fabmanager - ``` - -7. Retrieve the project from Git +6. Retrieve the project from Git ```bash git clone https://github.com/sleede/fab-manager.git ``` -8. Install the software dependencies. - First install [PostgreSQL](#postgresql) and [ElasticSearch](#elasticsearch) as specified in their respective documentations (see below). - Then install the other dependencies: +7. Move into the project directory and install the docker-based dependencies. + > ⚠ If you are using MacOS X, you must *first* edit the files located in docker/development to use port binding instead of ip-based binding. + > This can be achieved by uncommenting the "port" directives and commenting the "networks" directives in the docker-compose.yml file. + > The hosts file must be modified too, accordingly. + ```bash + cd fab-manager + cat docker/development/hosts | sudo tee -a /etc/hosts + mkdir -p .docker/elasticsearch/config + cp docker/development/docker-compose.yml .docker + cp docker/elasticsearch.yml .docker/elasticsearch/config + cp docker/log4j2.properties .docker/elasticsearch/config + cd .docker + docker-compose up -d + cd - + ``` + +8. Install the other dependencies. - For Ubuntu/Debian: ```bash # on Ubuntu 18.04 server, you may have to enable the "universe" repository sudo add-apt-repository universe # then, install the dependencies - sudo apt-get install libpq-dev redis-server imagemagick + sudo apt-get install libpq-dev imagemagick ``` - For MacOS X: ```bash - brew install redis imagemagick + brew install imagemagick ``` 9. Init the RVM and NVM instances and check they were correctly configured ```bash - cd fab-manager rvm current | grep -q `cat .ruby-version`@fab-manager && echo "ok" # Must print ok nvm use node --version | grep -q `cat .nvmrc` && echo "ok" # Must print ok ``` + + If one of these commands does not print "ok", then try to input `rvm use` or `nvm use` +``` 10. Install bundler in the current RVM gemset @@ -106,8 +112,9 @@ This procedure is not easy to follow so if you don't need to write some code for ``` 13. Build the databases. - - **Warning**: **DO NOT** run `rake db:setup` instead of these commands, as this will not run some required raw SQL instructions. - - **Please note**: Your password length must be between 8 and 128 characters, otherwise db:seed will be rejected. This is configured in [config/initializers/devise.rb](config/initializers/devise.rb) + > **⚠ Warning**: **DO NOT** run `rake db:setup` instead of these commands, as this will not run some required raw SQL instructions. + + > **🛈 Please note**: Your password length must be between 8 and 128 characters, otherwise db:seed will be rejected. This is configured in [config/initializers/devise.rb](config/initializers/devise.rb) ```bash # for dev @@ -129,7 +136,7 @@ This procedure is not easy to follow so if you don't need to write some code for 15. Start the development web server ```bash - foreman s -p 3000 + foreman s -p 5000 ``` 16. You should now be able to access your local development Fab-manager instance by accessing `http://localhost:3000` in your web browser. @@ -143,77 +150,21 @@ This procedure is not easy to follow so if you don't need to write some code for ## PostgreSQL - -### Install PostgreSQL 9.6 - -We will use docker to easily install the required version of PostgreSQL. - -1. Create the docker binding folder - ```bash - mkdir -p .docker/postgresql - ``` - -2. Start the PostgreSQL container. - > 🍏 If you're using MacOS, remove the --network and --ip parameters, and add -p 5432:5432. - ```bash - docker run --restart=always -d --name fabmanager-postgres \ - -v $(pwd)/.docker/postgresql:/var/lib/postgresql/data \ - --network fabmanager --ip 172.18.0.2 \ - postgres:9.6 - ``` - -3. Configure Fab-manager to use it. - On linux systems, PostgreSQL will be available at 172.18.0.2. - On MacOS, you'll have to set the host to 127.0.0.1 (or localhost). - See [environment.md](environment.md) for more details. - -4 . Finally, you may want to have a look at detailed informations about PostgreSQL usage in Fab-manager. - Some information about that is available in the [PostgreSQL Readme](postgresql_readme.md). +Some information about PostgreSQL usage in fab-manager is available in the [PostgreSQL Readme](postgresql_readme.md). ## ElasticSearch ElasticSearch is a powerful search engine based on Apache Lucene combined with a NoSQL database used as a cache to index data and quickly process complex requests on it. -In Fab-manager, it is used for the admin's statistics module and to perform searches in projects. +In FabManager, it is used for the admin's statistics module and to perform searches in projects. - -### Install ElasticSearch - -1. Create the docker binding folders - ```bash - mkdir -p .docker/elasticsearch/config - mkdir -p .docker/elasticsearch/plugins - mkdir -p .docker/elasticsearch/backups - ``` - -2. Copy the default configuration files - ```bash - cp docker/elasticsearch.yml .docker/elasticsearch/config - cp docker/log4j2.properties .docker/elasticsearch/config - ``` - -3. Start the ElasticSearch container. - > 🍏 If you're using MacOS, remove the --network and --ip parameters, and add -p 9200:9200. - ```bash - docker run --restart=always -d --name fabmanager-elastic \ - -v $(pwd)/.docker/elasticsearch/config:/usr/share/elasticsearch/config \ - -v $(pwd)/.docker/elasticsearch:/usr/share/elasticsearch/data \ - -v $(pwd)/.docker/elasticsearch/plugins:/usr/share/elasticsearch/plugins \ - -v $(pwd)/.docker/elasticsearch/backups:/usr/share/elasticsearch/backups \ - --network fabmanager --ip 172.18.0.3 \ - elasticsearch:5.6 - ``` - -4. Configure Fab-manager to use it. - On linux systems, ElasticSearch will be available at 172.18.0.3. - On MacOS, you'll have to set the host to 127.0.0.1 (or localhost). - See [environment.md](environment.md) for more details. +The organisation if the data in the ElasticSearch database is documented in [elasticsearch.md](elasticsearch.md) ### Rebuild statistics -Every nights, the statistics for the day that just ended are built automatically at 01:00 (AM) and stored in ElastricSearch. +Every nights, the statistics for the day that just ended are built automatically at 01:00 (AM) and stored in ElasticSearch. See [schedule.yml](config/schedule.yml) to modify this behavior. If the scheduled task wasn't executed for any reason (eg. you are in a dev environment and your computer was turned off at 1 AM), you can force the statistics data generation in ElasticSearch, running the following command. diff --git a/docker/development/docker-compose.yml b/docker/development/docker-compose.yml new file mode 100644 index 000000000..e8eca948a --- /dev/null +++ b/docker/development/docker-compose.yml @@ -0,0 +1,62 @@ +version: '2' +services: + postgres: + image: postgres:9.6 + volumes: + - ${PWD}/postgresql:/var/lib/postgresql/data + restart: always + ## linux + networks: + fabmanager: + ipv4_address: 172.18.0.2 + ## osx + #ports: + # - "5432:5432" + environment: + POSTGRES_HOST_AUTH_METHOD: trust + + elasticsearch: + image: elasticsearch:5.6 + environment: + - "ES_JAVA_OPTS=-Xms512m -Xmx512m" + ulimits: + memlock: + soft: -1 + hard: -1 + volumes: + - ${PWD}/elasticsearch/config:/usr/share/elasticsearch/config + - ${PWD}/elasticsearch:/usr/share/elasticsearch/data + - ${PWD}/elasticsearch/plugins:/usr/share/elasticsearch/plugins + - ${PWD}/elasticsearch/backups:/usr/share/elasticsearch/backups + restart: always + ## linux + networks: + fabmanager: + ipv4_address: 172.18.0.3 + ## osx + #ports: + # - "9200:9200" + # - "9300:9300" + + redis: + image: redis:5 + volumes: + - ${PWD}/redis:/data + restart: always + ## linux + networks: + fabmanager: + ipv4_address: 172.18.0.4 + ## osx + #ports: + # - "6379:6379" + +## linux +networks: + fabmanager: + driver: bridge + ipam: + config: + - subnet: 172.18.0.0/16 + gateway: 172.18.0.1 + diff --git a/docker/development/hosts b/docker/development/hosts new file mode 100644 index 000000000..f69380840 --- /dev/null +++ b/docker/development/hosts @@ -0,0 +1,10 @@ +## == fab-manager == +## linux +172.18.0.4 fabmanager-redis +172.18.0.3 fabmanager-elastic +172.18.0.2 fabmanager-postgres + +## osx +# 127.0.0.1 fabmanager-redis +# 127.0.0.1 fabmanager-elastic +# 127.0.0.1 fabmanager-postgres