CONSUL Installer

CONSUL installer for production environments

Using Ansible, it will install and configure the following:

• Ruby
• Rails
• Postgres
• Nginx
• Puma
• SMTP
• Memcached
• DelayedJobs
• HTTPS
• Capistrano

It will also create a deploy user to install these libraries

Screencast

How to setup CONSUL for a production environment

Prerequisities

A remote server with the supported distribution

Ubuntu 16.04 x64

Access to a remote server via public ssh key without password. The default user is deploy but you can use any user with sudo privileges.

ssh root@remote-server-ip-address

Updated system package versions

sudo apt-get update

Python 2 installed in the remote server

sudo apt-get -y install python-simplejson

Running the installer

The following commands must be executed in your local machine

Install Ansible >= 2.4

Get the Ansible Playbook

git clone https://github.com/consul/installer
cd installer

Create your local hosts file

cp hosts.example hosts

Update your local hosts file with the remote server's ip address

remote-server-ip-address (maintain other default options)

Run the ansible playbook

sudo ansible-playbook -v consul.yml -i hosts

Visit remote-server-ip-address in your browser and you should see CONSUL running!

Admin user

You can sign in to the application with the default admin user:

[email protected]
12345678

Deploys with Capistrano

To restart the server and deploy new code to the server we have to configure Capistrano.

Screencast

How to setup Capistrano

Create your fork

Setup locally for your development environment)

Run the capistrano playbook:

sudo ansible-playbook -v capistrano.yml -i hosts

Download changes from the capistrano branch to your fork

git remote add upstream [email protected]:consul/consul.git
git fetch upstream
git merge upstream/capistrano
git push origin master

Create your deploy-secrets.yml

cp config/deploy-secrets.yml.example config/deploy-secrets.yml

Update deploy-secrets.yml with your server's info

deploy_to: "/home/deploy/consul"
server1: "your_remote_ip_address"
db_server: "localhost"
server_name: "your_remote_ip_address"

Update your repo_url in deploy.rb

set :repo_url, 'https://github.com/your_github_username/consul.git'

Make a change in a view and push it your fork in Github

git add .
git commit -a -m "Add sample text to homepage"
git push origin master

Deploy to production

cap production deploy

You should now see that change at your remote server's ip address

Email configuration

Screencast

How to setup email deliveries

Update the following file in your production server: /home/deploy/consul/shared/config/environments/production.rb

You want to change this block of code and use your own SMTP credentials:

  config.action_mailer.delivery_method = :smtp
  config.action_mailer.smtp_settings = {
    address:              "smtp.example.com",
    port:                 "25",
    domain:               "your_domain.com or ip address",
    user_name:            "username",
    password:             "password",
    authentication:       "plain",
    enable_starttls_auto: true }

And restart the server running this command from your local CONSUL installation (see Deploys with Capistrano for details).

cap production deploy:restart

Once you setup your domain, depending on your SMTP provider, you will have to do two things:

• Update the server_name with your domain in /home/deploy/consul/shared/config/secrets.yml.
• Update the sender_email_address from the admin section (remote-server-ip-address/admin/settings)

If your SMTP provider uses an authentication other than plain, check out the Rails docs on email configuration for the different authentation options.

SSL with LetsEncrypt

Using https instead of http is an important security configuration. Before you begin, you will need to either buy a domain or get access to the configuration of an existing domain. Next, you need to make sure you have an A Record in the DNS configuration of your domain, pointing to the correponding IP address of your server. You can check if your domain is correctly configured at this url https://dnschecker.org/, where you should see your IP address when searching for your domain name.

Once you have that setup we need to configure the Installer to use your domain in the application.

First, uncomment the domain variable in the configuration file and update it with your domain name:

#domain: "your_domain.com"

Next, uncomment the letsencrypt_email variable in the configuration file and update it with a valid email address:

#letsencrypt_email: "[email protected]"

Re-run the installer:

sudo ansible-playbook -v consul.yml -i hosts

You should now be able to see the application running at https://your_domain.com in your browser.

Configuration Variables

These are the main configuration variables:

# Server Timzone + Locale
timezone: Europe/Madrid
locale: en_US.UTF-8

# Authorized Hosts
ssh_public_key_path: "change_me/.ssh/id_rsa.pub"

# Ruby
ruby_version: 2.4.9

#Postgresql
postgresql_version: 9.6
database_name: "consul_production"
database_user: "deploy"
database_password: "change_me"
database_hostname: "localhost"
database_port: 5432

#SMTP
smtp_address:        "smtp.example.com"
smtp_port:           25
smtp_domain:         "your_domain.com"
smtp_user_name:      "username"
smtp_password:       "password"
smtp_authentication: "plain"

There are many more variables available check them out here

Other deployment options

Split database from application code

The consul playbook creates the database on the same server as the application code. If you are using a cloud host that offers managed databases (such as AWS RDS, Azure Databases, or Google Cloud SQL), we recommend using that instead.

To set up the application by itself:

1. Fork this repository.

2. Specify your database credentials (see the database_* group variables) in a vault.

3. Run the app playbook instead of the consul one against a clean server.

   sudo ansible-playbook -v app.yml -i hosts

Platform-as-a-Service (PaaS)

Aside from just using managed databases, you might also look into platform-as-a-service options (like Azure App Service or Google App Engine) to not have to manage a server at all.

No root access

By default the installer assumes you can log in as root. The root user will only be used once to login and create a deploy user. The deploy user is the one that will actually install all libraries and is the user that must be used to login to the server to do maintenance tasks.

If you do not have root access, you will need your system administrator to grant you: sudo privileges for a deploy user in the wheel group without password.

Also you will need to change the variable root access to false.

Using a different user than deploy

Change the variable deploy_user to the username you would like to use.

Ansible Documentation

http://docs.ansible.com/

Roadmap

Cross platform compatibility (Ubuntu, CentOS)

Greater diversity of interchangeable roles (nginx/apache, unicorn/puma/passenger, rvm/rbenv)

How to contribute

• Open an issue
• Send us a Pull Request

Support

License

Code published under AFFERO GPL v3 (see LICENSE-AGPLv3.txt)