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.20 to 1.21.2 are supported. CAUTION docker-compose version 1.22 and higher are not supported yet and will break the setup!

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:

  • A dedicated user and group to run Grape. This documentation assumes an existing grape user and group.

  • 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.

Create the base directory for Grape:

sudo mkdir /data
sudo chown -R grape:grape /data/

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.

grape@grape-debian:/Install$ ./install.sh
Grape base dir '/data/grape' does not exist yet, will try to create it...
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 >= 18.03.0
OK: docker-engine version 18.09.5 valid

Checking for docker-compose version >= 1.21.0
OK: docker-compose version 1.21.2 valid

Checking for ansible version >= 2.4
OK: ansible version 2.6.4 valid
Checking for GnuPG
GnuPG found.
Requirement already satisfied: asn1crypto==0.24.0 in /usr/local/lib/python2.7/dist-packages (from -r requirements.txt (line 7))
Collecting backports.ssl-match-hostname==3.5.0.1 (from -r requirements.txt (line 8))
...
Successfully installed backports.ssl-match-hostname-3.5.0.1 certifi-2017.4.17 cffi-1.11.5 chardet-3.0.4 colorama-0.4.0 colorlog-3.1.4 cryptography-2.3.1 docker-py-1.10.6 docker-pycreds-0.2.1 elasticsearch-2.4.1 idna-2.5 ipaddress-1.0.18 pyopenssl-17.3.0 python-dotenv-0.9.1 python-gnupg-0.4.3 requests-2.18.1 semantic-version-2.6.0 six-1.10.0 urllib3-1.21.1 websocket-client-0.44.0
Importing Grape Distribution GnuPG public key
Setting ownertrust for Grape Distribution GnuPG public key
Creating config folder and default config (if required)
Updating config.yml Grape paths
Creating initial setup dir
Copying and linking grape command
Adding '/data/grape/bin' to PATH

IMPORTANT: Please run 'source ~/.bash_login' to update the PATH variable in your running shell!

Done!

You can now initialize your Grape setup by running 'grape init'.

Update the $PATH variable as advised: source ~/.bash_login

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.

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

Grape SETUP Version: 4.0.1


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

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]:
Please enter docker registry username: DOCKER_REGISTRY_USERNAME
Please enter docker registry password: DOCKER_REGISTRY_PASSWORD
Please enter releases registry username: RELEASES_REGISTRY_USERNAME
Please enter releases registry password: RELEASES_REGISTRY_PASSWORD
Command 'init' returned no errors.
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'

Login Succeeded

OK: 'docker login' succeeded.
Command 'check' returned no errors.
Will run command 'fetch'
Version '4.0.1' has been fetched.
Running command 'fetch' 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 “y” 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 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:

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

Grape SETUP Version: 4.0.1


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.

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 in seconds [1814400]:
Force daily logout of mobile clients [n]:
Enable MX record check for email addresses [n]:
Change name display order to 'Lastname Firstname' [n]:
Time between full AD resyncs in minutes [1440]:
Were you given a custom runtime tag by the Grape team [n]:
Enable advanced performance tweaks [n]:
Set timeout for editing messages (in seconds) [300]:
Enable extra runtime environment [n]:
Size limit of uploaded files (in MB) [50]:
Extra hosts for the grape runtime container:
Hosts to add to the CORS whitelist:
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/config/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@grape-debian:~$ grape install
                                             __
   ____ __________ _____  ___     ________  / /___  ______
  / __ `/ ___/ __ `/ __ \/ _ \   / ___/ _ \/ __/ / / / __ \
 / /_/ / /  / /_/ / /_/ /  __/  (__  )  __/ /_/ /_/ / /_/ /
 \__, /_/   \__,_/ .___/\___/  /____/\___/\__/\__,_/ .___/
/____/          /_/                               /_/

Grape SETUP Version: 4.0.1


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.

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.

grape@grape-debian:~$ grape status
                                             __
   ____ __________ _____  ___     ________  / /___  ______
  / __ `/ ___/ __ `/ __ \/ _ \   / ___/ _ \/ __/ / / / __ \
 / /_/ / /  / /_/ / /_/ /  __/  (__  )  __/ /_/ /_/ / /_/ /
 \__, /_/   \__,_/ .___/\___/  /____/\___/\__/\__,_/ .___/
/____/          /_/                               /_/

Grape SETUP Version: 4.0.1

Options for selected command 'status':

General options:
 * verbose              False
 * debug                False

Running Grape status check
 * Proxy:
    Container: running
 * Sentry:
    Container: running
 * Grape:
    Image:     onpremises-4.0.1
    Container: running
    Processes:
      chatgrape-ws: running
      grape-check: stopped
      chatgrape-celery-worker-emails: running
      chatgrape-celery-beat: running
      chatgrape-rr: running
      chatgrape-celery-worker-notifications: running
      chatgrape-celery-worker: running

Command 'status' returned no errors.

Once the status of all services except grape-check 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/proxy/ssl. If you are using the old setup that requires root permission, you will find the files in /etc/grape/proxy/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/proxy/ssl/grape.key

  • Copy the SSL certificate for the Grape instance to /data/grape/config/proxy/ssl/grape.crt

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

  • Copy the SSL certificate for Grape’s Sentry instance to /data/grape/config/proxy/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/proxy/ssl/developers.grape.key and /data/grape/config/proxy/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/