consul/nairobi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

GitBook: [master] 86 pages and 110 assets modified

Browse Source
This commit is contained in:
consuldocs
2020-07-14 22:51:03 +00:00
committed by gitbook-bot
parent 06fe16d6b4
commit 5ed5960428
196 changed files with 5304 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/english-documentation/introduction/local_installation/README.md Normal file
View File

@@ -0,0 +1,74 @@
# Local installation
Before installing Consul and having it up and running make sure you all [prerequisites](prerequisites.md) installed.
1. First, clone the [Consul Github repository](https://github.com/consul/consul/) and enter the project folder:
```bash
git clone https://github.com/consul/consul.git
cd consul
```
1. Install the Ruby version we need with your Ruby version manager. Here are some examples:
```bash
rvm install `cat .ruby-version` # If you're using RVM
rbenv install `cat .ruby-version` # If you're using rbenv
asdf install ruby `cat .ruby-version` # If you're using asdf
```
1. Check we're using the Ruby version we've just installed:
```bash
ruby -v
=> # (it should be the same as the version in the .ruby-version file)
```
1. Install [Bundler](http://bundler.io/):
```bash
gem install bundler --version 1.17.1
```
1. Install the required gems using Bundler:
```bash
bundle
```
1. Copy the environment example configuration files inside new readable ones:
```bash
cp config/database.yml.example config/database.yml
cp config/secrets.yml.example config/secrets.yml
```
And setup database credentials with your `consul` user in your new `database.yml` file.
1. Run the following [Rake tasks](https://github.com/ruby/rake) to create and fill your local database with the minimum data needed to run the application:
```bash
rake db:create
rake db:setup
rake db:dev_seed
rake db:test:prepare
```
1. Check everything is fine by running the test suite \(beware it might take more than an hour\):
```bash
bin/rspec
```
1. Now you have all set, run the application:
```bash
bin/rails s
```
Congratulations! Your local Consul application will be running now at `http://localhost:3000`.
In case you want to access the local application as admin, a default user verified and with admin permissions was created by the seed files with **username** `admin@consul.dev` and **password** `12345678`.
If you need an specific user to perform actions such as voting without admin permissions, a default verified user is also available with **username** `verified@consul.dev` and **password** `12345678`.

167
docs/english-documentation/introduction/local_installation/debian.md Normal file
View File

@@ -0,0 +1,167 @@
# Debian Linux
## Configuration for development and test environments \(Debian GNU/Linux 9.8\)
## Superuser
Note that 'sudo' is not installed by default in Debian. It's possible to install and configure it, you can find information [here](https://wiki.debian.org/sudo). But we don't recommend it cause you may have other problems. We recommend running the following commands as a superuser, so make sure the very first command you run is:
```text
su
```
> For [Vagrant](vagrant.md) run:
>
> ```text
> sudo su -
> ```
## System update
Run a general system update:
```bash
apt-get update
```
## Git
Git is officially maintained in Debian:
```text
apt-get install git
```
## Curl
Curl is officially maintained in Debian:
```text
apt-get install curl
```
## Ruby version manager
Ruby versions packaged in official repositories are not suitable to work with consul, so we'll have to install it manually.
One possible tool is rvm:
### As a local user
```text
command curl -sSL https://rvm.io/mpapis.asc | gpg --import -
command curl -sSL https://rvm.io/pkuczynski.asc | gpg --import -
curl -L https://get.rvm.io | bash -s stable
```
then add rvm script source to user's bash \(~/.bashrc\) \(this step is only necessary if you can't execute the rvm command\)
```text
[[ -s /usr/local/rvm/scripts/rvm ]] && source /usr/local/rvm/scripts/rvm
```
and finally, reload .bashrc to be able to run RVM
```text
source ~/.bashrc
```
## Node.js
To compile the assets, you'll need a JavaScript runtime. Node.js is the preferred option. As with Ruby, we don't recommend installing Node from your distro's repositories.
To install it, you can use [n](https://github.com/tj/n)
Run the following command on your terminal:
```text
curl -L https://git.io/n-install | bash -s -- -y lts
```
And it will install the latest LTS \(Long Term Support\) Node version on your `$HOME` folder automatically \(This makes use of [n-install](https://github.com/mklement0/n-install)\)
Reload .bashrc to be able to run node
```text
source /root/.bashrc
```
Check it's correctly installed by running:
```text
node -v
```
## PostgreSQL \(>=9.4\)
PostgreSQL version 9.4 is not official in debian 9.
So you have to add a repository, the official postgresql works fine.
Add the repository to apt, for example creating file _/etc/apt/sources.list.d/pgdg.list_ with:
```text
deb http://security.debian.org/debian-security jessie/updates main
```
afterwards you'll have to download the key, and install it, by:
```text
wget https://www.postgresql.org/media/keys/ACCC4CF8.asc
apt-key add ACCC4CF8.asc
```
and install postgresql
```text
apt-get update
apt-get install postgresql-9.4 postgresql-server-dev-9.4 postgresql-contrib-9.4
```
You also need to configure a user for your database. As an example, we'll choose the username "consul":
```text
su - postgres
createuser consul --createdb --superuser --pwprompt
exit
```
## Imagemagick
Install Imagemagick:
```bash
apt-get install imagemagick
```
## ChromeDriver
To run E2E integration tests, we use Selenium along with Headless Chrome.
To get it working, install the chromedriver package:
```bash
apt-get install chromedriver
ln -s /usr/lib/chromedriver /usr/local/bin/
```
Make sure it's working as expected by running the following command:
```bash
chromedriver --version
```
You should receive an output with the latest version of ChromeDriver. If that's the case, you're good to go!
If you are using an Arch-based distro, installing `chromium` from the `extra` repository should be sufficient.
You also have the option of just installing ChromeDriver from AUR. If you use `pacaur`, run the following command:
```bash
pacaur -S chromedriver
```
Now you're ready to go get Consul [installed](./)!!

104
docs/english-documentation/introduction/local_installation/macos.md Normal file
View File

@@ -0,0 +1,104 @@
# MacOS
## Homebrew
Homebrew is a very popular package manager for OS X. It's advised to use it since it makes the installation of some of the dependencies much easier.
You can find the installation instructions at: [brew.sh](http://brew.sh)
## XCode and XCode Command Line Tools
To install _git_ you'll first need to install _Xcode_ \(download it from the Mac App Store\) and its _Xcode Command Line Tools_ \(you can install them from the Xcode's app menu\)
## Git and Github
You can download git from: [git-scm.com/download/mac](https://git-scm.com/download/mac)
## Ruby version manager
OS X already comes with a preinstalled Ruby version, but it's quite old and we need a newer one. One of the multiple ways of installing Ruby in OS X is through _rbenv_. The installation instructions are in its GitHub repository and are pretty straight-forward:
[github.com/rbenv/rbenv](https://github.com/rbenv/rbenv)
## Node.js
To compile the assets, you'll need a JavaScript runtime. OS X comes with an integrated runtime called `Apple JavaScriptCore` but Node.js is the preferred option.
To install it, you can use [n](https://github.com/tj/n)
Run the following command on your terminal:
```text
curl -L https://git.io/n-install | bash -s -- -y lts
```
And it will install the latest LTS \(Long Term Support\) Node version on your `$HOME` folder automatically \(This makes use of [n-install](https://github.com/mklement0/n-install)\)
## PostgreSQL \(>=9.4\)
```text
brew install postgres
```
Once installed, we need to _initialize_ it:
```text
initdb /usr/local/var/postgres
```
Now we're going to configure some things related to the _default user_. First we start postgres server with:
```text
postgres -D /usr/local/var/postgres
```
At this point we're supposed to have postgres correctly installed and a default user will automatically be created \(whose name will match our username\). This user hasn't got a password yet.
If we run `psql` we'll login into the postgres console with the default user. Probably it will fail since its required that a default database exists for that user. We can create it by typing:
```text
createdb 'your_username'
```
If we run `psql` again we should now get access to postgres console. With `\du` you can see the current users list.
In case you want to set a password for your user you can make it throught postgres console by:
```text
ALTER USER your_username WITH PASSWORD 'your_password';
```
Now we'll create the _consul_ user, the one the application is using. Run in postgres console:
```text
CREATE ROLE consul WITH PASSWORD '000';
ALTER ROLE consul WITH SUPERUSER;
ALTER ROLE consul WITH login;
```
If at any point during PostgreSQL installation you feel you have messed things up, you can uninstall it and start again by running:
```text
brew uninstall postgres
```
You'll have to delete also this directory \(otherwise the new installation will generate conflicts, source: [gist.github.com/lxneng/741932](https://gist.github.com/lxneng/741932)\):
```text
rm -rf /usr/local/var/postgres
```
## ChromeDriver
```text
brew install chromedriver
```
## Imagemagick
```text
brew install imagemagick
```
Now that we have all the dependencies installed we can go ahead and [install Consul](./).

7
docs/english-documentation/introduction/local_installation/prerequisites.md Normal file
View File

@@ -0,0 +1,7 @@
# Prerequisites
* [Ubuntu Linux](ubuntu.md)
* [Debian Linux](debian.md)
* [MacOS](macos.md)
* [Windows](windows.md)

114
docs/english-documentation/introduction/local_installation/ubuntu.md Normal file
View File

@@ -0,0 +1,114 @@
# Ubuntu Linux
## Configuration for development and test environments \(Ubuntu 18.04\)
## System update
Run a general system update:
```bash
sudo apt update
```
## Git
Git is officially maintained in Ubuntu:
```bash
sudo apt install git
```
## Ruby version manager
Ruby versions packaged in official repositories are not suitable to work with CONSUL, so we'll have to install it manually.
First, we need to install Ruby's development dependencies:
```bash
sudo apt install libssl-dev autoconf bison build-essential libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev
```
The next step is installing a Ruby version manager, like rbenv:
```bash
wget -q https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-installer -O- | bash
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
```
## Node.js
To compile the assets, you'll need a JavaScript runtime. Node.js is the preferred option.
Run the following command on your terminal:
```bash
sudo apt install nodejs
```
## PostgreSQL
Install postgresql and its development dependencies with:
```bash
sudo apt install postgresql libpq-dev
```
You also need to configure a user for your database. As an example, we'll choose the username "consul":
```bash
sudo -u postgres createuser consul --createdb --superuser --pwprompt
```
To make sure the UTF-8 enconding is used, create a file:
```text
sudo nano /etc/profile.d/lang.sh
```
Add the following:
```text
export LANGUAGE="en_US.UTF-8"
export LANG="en_US.UTF-8"
export LC_ALL="en_US.UTF-8"
```
Reconfigure Postgres to use the UTF-8 encoding:
```text
sudo su - postgres
psql
update pg_database set datistemplate=false where datname='template1';
drop database Template1;
create database template1 with owner=postgres encoding='UTF-8'
lc_collate='en_US.utf8' lc_ctype='en_US.utf8' template template0;
update pg_database set datistemplate=true where datname='template1';
\q
exit
```
## Imagemagick
Install Imagemagick:
```bash
sudo apt install imagemagick
```
## ChromeDriver
To run E2E integration tests, we use Selenium along with Headless Chrome.
To get it working, install the chromium-chromedriver package and make sure it's available on your shell's PATH:
```bash
sudo apt install chromium-chromedriver
sudo ln -s /usr/lib/chromium-browser/chromedriver /usr/local/bin/
```
Now you're ready to go [get CONSUL installed](./)!

48
docs/english-documentation/introduction/local_installation/vagrant.md Normal file
View File

@@ -0,0 +1,48 @@
# Vagrant
## Vagrant
Install [Vagrant](https://www.vagrantup.com/) and setup a virtual machine with [Linux](prerequisites.md)
Vagrant is compatible for [Debian](debian.md) and [Ubuntu](ubuntu.md).
### Browser configuration
To access the application through the brower at `localhost:3000` we must forward a port and run the rails server with a binding option:
### Port forwarding
Open the Vagrant configuration file:
```text
nano Vagranfile
```
Find this line:
```text
# config.vm.network "forwarded_port", guest: 80, host: 8080
```
And change it for this configuration:
```text
config.vm.network "forwarded_port", guest: 3000, host: 3000
```
Reload your virtual machine:
```text
vagrant reload
```
## Running the rails server
In your virtual machine, run the application server, binding to your local ip address:
```text
bin/rails s -b 0.0.0.0
```
Now you should be able to see the application running in your browser at url `localhost:3000`! :tada:

4
docs/english-documentation/introduction/local_installation/windows.md Normal file
View File

@@ -0,0 +1,4 @@
# Windows
Windows is not yet officially supported. Please install [Virtual Box](https://www.virtualbox.org/) to setup a virtual machine in [Linux](prerequisites.md).