Installing Grape

This tutorial will show you how to install Grape in a matter of minutes.

Checklist

Please read the requirements page first to see if your setup meets the minimum requirements.

System requirements:

  • A GNU/Linux server or VM. Supported distributions: RHEL 7, Centos 7, Debian 9, Ubuntu 16.04 LTS or 18.04 LTS
  • docker-engine CE versions 18.03.0+ are supported.
  • docker-compose versions 1.22.0+ are supported.

Only the community edition (ce) of docker is supported for now.

Prerequisites

Make sure that you have the following Information at hand before starting the install process:

  • An email account on one of your servers for Grape to send mails from, e.g. grape@example.com
  • An email account on one of your servers for Grape’s Sentry to send mails from, e.g. grape@example.com
  • A DNS entry for the server running Grape, e.g. grape.example.com
  • A DNS entry for the server running Grape’s Sentry instance, e.g. sentry.grape.example.com
  • DNS entries for organizational subdomains , e.g. my-team.example.com etc OR a wildcard DNS entry for *.grape@example.com
  • Proxy URL and authentification (if required)
  • Initial installation files (provided by the Grape team)
  • Login data for the Grape docker registry (provided by the Grape team)
  • Login data for the Grape distribution server (provided by the Grape team)

Initial installation

Copy the files from the Grape install package to the server.

Then run the script ./install.sh. This will copy the basic files for the Grape setup to the correct locations.

It will also install ansible and a couple of python dependencies needed by the grape script.

root@grape-debian:~/Grape-install# ./install.sh 
Starting very basic Grape initial install
Checking for required files...
File 'config.yml.example' found.
File 'grape-distrib-2016-pub.asc' found.
File 'grape-distrib-2016-pub.ownertrust' found.
File 'install.sh' found.
File 'requirements.txt' found.
File 'grape.py' found.
All required files present.

Checking for docker engine version >= 1.10.0
OK: docker-engine version 1.11.1 valid

Checking for docker-compose version >= 1.7.0
OK: docker-compose version 1.7.0 valid

Checking for ansible version >= 2.1
OK: ansible version 2.2.1.0 valid
Checking for GnuPG
GnuPG found.
Collecting python-gnupg==0.3.9 (from -r requirements.txt (line 2))
  Downloading python_gnupg-0.3.9-py2.py3-none-any.whl
...
Successfully installed backports.ssl-match-hostname-3.5.0.1 colorama-0.3.7 colorlog-2.7.0 docker-py-1.9.0 python-gnupg-0.3.9 requests-2.11.1 websocket-client-0.37.0
Importing Grape Distribution GnuPG public key
Setting ownertrust for Grape Distribution GnuPG public key
Creating config folder and default config (if required)
Creating initial setup dir
Copying and linking grape command
Done!

Configuring Grape setup

To get the latest setup files and docker images we need to create a basic setup configuration.

To do so run: grape init

Hint: If you don’t know what an option means you can just enter ? and a help text will be displayed.

root@grape-debian:~# grape init
                                   _            __        ____         
   ____ __________ _____  ___     (_)___  _____/ /_____ _/ / /__  _____
  / __ `/ ___/ __ `/ __ \/ _ \   / / __ \/ ___/ __/ __ `/ / / _ \/ ___/
 / /_/ / /  / /_/ / /_/ /  __/  / / / / (__  ) /_/ /_/ / / /  __/ /    
 \__, /_/   \__,_/ .___/\___/  /_/_/ /_/____/\__/\__,_/_/_/\___/_/     
/____/          /_/                                                    

Grape SETUP Version: 2.8.0


Options for selected command 'init':
 * force-reconfigure    True

General options:
 * verbose              False
 * debug                False

Initializing Grape installation
Do you want to use your own reverse-proxy server: n
Will you use a Grape Egde server [n]: n
Please enter docker registry url [https://docker-registry-builds.chatgrape.com]:
Please enter docker registry username: registry-user
Please enter docker registry password: qCeSAuhbp4iY+CDP
Please enter releases registry username: releases-user
Please enter releases registry password: nRm/94FAeui7C7QG
Write changes to '/data/grape/config.yml' [y]: 
Writing config to '/data/grape/config.yml'
Command 'init' returned no errors.
Will run 'check' now to see if the login data works.
Checking Grape distribution server HTTP auth
OK: Releases HTTP auth data exists.
  Attempting login to Grape distribution server
OK: HTTP auth succeeded

Checking Docker registry authentification
OK: Docker registry auth data exists.
  Attempting docker login
Logging into docker registry 'https://docker-registry-builds.chatgrape.com:4443'
Login Succeeded

OK: 'docker login' succeeded.
Command 'check' returned no errors.
Will run command 'fetch'
Version '2.9.2' has been fetched.
Running command 'check' succeeded.
Command 'init' returned no errors.

Explaination:

  • Do you want to use your own reverse-proxy server: Answer “y” here if you don’t want to use the preconfigured nginx proxy but want to handle ssl termination, websocket handling etc. by yourself. This is most likely not what you want.
  • Will you use a Grape Egde server: Say yes here if you want to use a Grape Edge server as described in the documentation. If you don’t know what that means it is safe to answer “n”.
  • Please enter docker registry url: The URL to Grape’s docker registry. You can change to port 443 if your firewall/proxy setup needs this.
  • Please enter docker registry username: The username for Grape’s docker registry
  • Please enter docker registry password: The password for Grape’s docker registry
  • Please enter releases registry username: The username for Grape’s distribution service
  • Please enter releases registry password: The password for Grape’s distribution service

If running grape init fails please check your network connectivity (proxy etc.)

Configure Grape

To configure the Grape instance run grape configure:

root@grape-debian:~# grape configure
                                   _            __        ____         
   ____ __________ _____  ___     (_)___  _____/ /_____ _/ / /__  _____
  / __ `/ ___/ __ `/ __ \/ _ \   / / __ \/ ___/ __/ __ `/ / / _ \/ ___/
 / /_/ / /  / /_/ / /_/ /  __/  / / / / (__  ) /_/ /_/ / / /  __/ /    
 \__, /_/   \__,_/ .___/\___/  /_/_/ /_/____/\__/\__,_/_/_/\___/_/     
/____/          /_/                                                    

Grape SETUP Version: 2.8.0


Options for selected command 'configure':
 * clean config         False

General options:
 * verbose              False
 * debug                False

Running Grape configure
Note: Almost all options have a helptext that will be shown when '?' is entered as an answer.
WARNING: This seems to be a clean install. If it isn't, now is the time to press ctrl-c.

Entering section 'global'
External HTTP Port [80]: 
External HTTPS Port [443]: 
HTTP proxy server: 
HTTPS proxy server: 
Hostnames to exclude from proxy:
End of section 'global'

Entering section 'proxy'
Do you want to use a list of subdomains instead of a wildcard [n]: n
End of section 'proxy'

Entering section 'grape'
Hostname of your Grape instance: grape.example.com
Alternative hostname of your Grape instance: 
Email Address of the administrative user: admin@example.com
Initial password of the administrative user: eZniHg+OPI/P2RK3    
Activate single organization mode [n]:
Email address Grape sends mails from: grape@example.com
Support email address [support@chatgrape.com]: 
Mailserver address to use: smtp.example.com
Mailserver port [25]: 
Mail server needs TLS [n]:
Username for SMTP authentification: grape@example.com
Password for SMTP authentification: xMYMFiJ/S4qlFECx
Enable push notifications [y]:
Enable Apple push notifications [y]:
Enable Google push notifications [y]:
Enable Microsoft push notifications [y]:
Do you want to use your own elasticsearch instance/cluster [n]:
Do you want to use your own redis instance [n]:
Do you want to use your own PostgreSQL instance [n]:
Do you want to use a custom SSL cerificate authority [n]: 
Enter a custom session cookie age [1814400]: 
Force daily logout of mobile clients [n]: 
Enable MX record check for email addresses [n]: 
Change name display order to 'Lastname Firstname' [n]: 
Enable Elastic strict mapping [y]: 
Were you given a custom runtime tag by the Grape team [n]:
Enable advanced performance tweaks [n]:
End of section 'grape'

Entering section 'sentry'
Hostname of the Sentry instance: sentry.grape.example.com
Email address of Sentry administrative user: admin@example.com
Initial password of Sentry administrative user: n6Uto7ezC+mQLXln
Email address sentry sends mails from: grape-sentry@example.com
Mailserver address to use: smtp.example.com
Mailserver port to use [25]: 
Mailserver needs TLS [y/n] [y]: n
Username for SMTP authentification: grape-sentry@example.com
Password for SMTP authentification: 5c/Qj+aY3eYISZWr
End of section 'sentry'

Writing settings to '/data/grape/settings.yml'

Command 'configure' returned no errors.
You can now run 'grape install' to apply the changes.

Install Grape

To finalize the installation run grape install:

                                   _            __        ____         
   ____ __________ _____  ___     (_)___  _____/ /_____ _/ / /__  _____
  / __ `/ ___/ __ `/ __ \/ _ \   / / __ \/ ___/ __/ __ `/ / / _ \/ ___/
 / /_/ / /  / /_/ / /_/ /  __/  / / / / (__  ) /_/ /_/ / / /  __/ /    
 \__, /_/   \__,_/ .___/\___/  /_/_/ /_/____/\__/\__,_/_/_/\___/_/     
/____/          /_/                                                    

Grape SETUP Version: 2.8.0


Options for selected command 'install':
 * proxy                True
 * sentry               True
 * application          True

 * dry-run              False
 * diff                 False

General options:
 * verbose              False
 * debug                False


Running Grape installation
Installing/updating reverse proxy...

PLAY [localhost] ***************************************************************

TASK [setup] *******************************************************************
ok: [localhost]

...

PLAY RECAP *********************************************************************
localhost                  : ok=22   changed=16   unreachable=0    failed=0   

Installing/updating Sentry...

PLAY [localhost] ***************************************************************

TASK [setup] *******************************************************************
ok: [localhost]

...

PLAY RECAP *********************************************************************
localhost                  : ok=19   changed=16   unreachable=0    failed=0   

Installing/updating Grape application...
The required files from Sentry have not been generated yet, will wait and check.
Installing/updating Grape application...

PLAY [localhost] ***************************************************************

TASK [setup] *******************************************************************
ok: [localhost]

...

PLAY RECAP *********************************************************************
localhost                  : ok=36   changed=31   unreachable=0    failed=0   

Command 'install' returned no errors.

Note: if the command exits with ERROR Sentry timed out. Please wait some minutes, then try again. please be patient. Depending on your internet connection and the power of the server/VM it can take some time until the docker images are fetched and the containers started.

The full log output of this demo installation can be viewed here: Sample installation log

After grape install is finished it will still take some time until all the services are running, you can check the current status by running grape status.

Once the status of all services is running your Grape instance is ready to use.

If you want to use real SSL certificates (highly recommended!) see the step below.

Updating the SSL certificates used by the reverse proxy

By default Grape setup installs a self-signed SSL certificate for *.grape.example.com to /data/grape/config/ssl. If you are using the old setup that requires root permission, you will find the files in /data/grape/config/ssl instead.

To update it to your own certificates please do as follows:

  • Copy the SSL key for the Grape instance to /data/grape/config/ssl/grape.key
  • Copy the SSL certificate for the Grape instance to /data/grape/config/ssl/grape.crt
  • Copy the SSL key for Grape’s Sentry instance to /data/grape/config/ssl/sentry.key
  • Copy the SSL certificate for Grape’s Sentry instance to /data/grape/config/ssl/sentry.crt

If you have chosen to not use wildcards there will be key and certificate files for every subdomain in the list, e.g. for the subdomain developers there would be /data/grape/config/ssl/developers.grape.key and /data/grape/config/ssl/developers.grape.crt. Copy your key and certificate for developers.grape.yourdomain.com to these filenames.

All these files must be in PEM format (with no password set on the keys).

Once the files have been copied restart the proxy service by running cd /data/grape/config/proxy && docker-compose restart.

Run grape status to see if the proxy is running, otherwise check the copied keys/certificates and the output of docker logs /proxy_nginx_1.

If all services are running you’re good to go!

After installation: quickly test the instance

Before continuing with the setup, we suggest to do the followin minimal test:

  1. Open Grape in the browser and log in with your admin user
  2. Open the selftest page: https://your_grape_server/debug/self-test/
  3. Open the chat and send a message in a group: https://your_grape_server/chat/