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

Make sure you have root access and the server can reach the internet during the setup in order to download required system packages.

Prerequisites

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

Mandatory

  • 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

  • Login data for the Grape docker registry (provided by the Grape team)

Optional

  • 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. sentry-grape@example.com

  • Proxy URL and authentification (if required) - must be exported to the environment (put it into grape user .bashrc or similar)

Installation step-by-step

  1. Install docker (as superuser)

    install docker, e.g. for Ubuntu: https://docs.docker.com/install/linux/docker-ce/ubuntu/ (you can also find tutorials for other distributions on that page) docker-engine CE versions 18.03.0+ are supported.

  2. Install docker-compose (as superuser)

    Download the docker-compose 1.27.4 executable

    curl -L https://github.com/docker/compose/releases/download/1.27.4/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
    chmod ug+x /usr/local/bin/docker-compose
    chown root:docker /usr/local/bin/docker-compose
    
  3. Create a grape user and group (as superuser)

    Note: Grape will be running as this user, and important environment variables will be set in this user’s .bashrc We need root permissions only for the basic setup. Later on for all grape-related updates only the grape user will be used!

    Create the grape user and home directory with bash as default shell

    useradd -m -s /bin/bash grape
    

    Make sure the grape user is in the docker group

    usermod -aG docker grape
    

    at this point make sure the docker socket /run/docker.sock is also in the group docker so the grape user can use docker with ls -l /run/ | grep docker.sock

    Should look like this: srw-rw----  1 root docker    0 Nov  7 15:18 docker.sock

  4. Setting your proxy for docker (as superuser)

    For Docker the Proxy needs to be set via a systemd dropin

    Create the directory for the dropin

    mkdir -p /etc/systemd/system/docker.service.d
    

    Configure the proxy by writing the following configuration into

    /etc/systemd/system/docker.service.d/http-proxy.conf
    
    [Service]
    Environment="HTTP_PROXY=http://user:pass@proxyurl:port"
    Environment="HTTPS_PROXY=http://user:pass@proxyurl:port"
    Environment="NO_PROXY="
    

    Flush the changes

    systemctl daemon-reload
    

    Finally restart docker

    systemctl restart docker
    
  5. Create the base directory (as superuser)

    Create the base directory for grape

    mkdir -p /data/grape
    

    Give the grape user read/write permissions in that directory

    chown grape /data/grape
    
  6. Optional: If your proxy is terminating TLS the respective CA must be registered to prevent SSLErrors (as superuser)

    Upload the .crt CA file in PEM format to the server

    Prepare a directory for Grape to hold the CA bundle

    mkdir -p /data/grape/ca
    chown -R grape /data/grape
    

    UBUNTU:

    Create the directory for the custom root CA

    mkdir -p /usr/local/share/ca-certificates
    

    and copy the CA .crt file into this directory

    Install the CA

    update-ca-certificates
    

    Copy the newly generated ca-bundle to a folder where grape can read it

    cp /etc/ssl/certs/ca-certificates.crt /data/grape/ca/ca-bundle.crt
    

    RHEL:

    Create the directory for your custom root CA

    mkdir -p /etc/pki/ca-trust/source/anchors
    

    and copy the CA .crt file into this directory

    Install the CA

    update-ca-trust extract
    

    Copy the newly generated ca-bundle to a folder where grape can read it

    cp  /etc/pki/tls/certs/ca-bundle.crt /data/grape/ca/ca-bundle.crt
    

    All distributions:

    Switch to the Grape User

    su - grape
    

    Edit the .bashrc file

    vim ~/.bashrc
    

    and add the following line at the bottom of the file

    export REQUESTS_CA_BUNDLE=/data/grape/ca/ca-bundle.crt
    

    export the environment

    source ~/.bashrc
    

    the Grape installer will pick up on this setting and make sure it is used in it’s containers.

  7. Setting proxy for the grape user (as grape user)

    If you are not the grape user yet

    su - grape
    

    Edit the .bashrc file

    vim ~/.bashrc
    

    and add the following lines at the bottom of the file

    export http_proxy=http://user:pass@proxyurl:port
    export HTTP_PROXY=http://user:pass@proxyurl:port
    export https_proxy=http://user:pass@proxyurl:port
    export HTTPS_PROXY=http://user:pass@proxyurl:port
    

    apply the environment to your active session

    source ~/.bashrc
    
  8. Download and run the Grape install script (as grape user)

    If you are not the grape user yet

    su - grape
    

    Go to grape user home directory

    cd
    

    Download the setup script install.sh

    wget https://gitlab.chatgrape.com/customers/quicksetup/raw/master/install.sh
    

    Run it …

    bash install.sh 
    

    while this install is running, it will ask you for the credentials provided by the Grape team.

    Output:

    Welcome to the Grape quick setup!
    Please enter the grape username: supercorp
    Please enter the grape password:
    Login Succeeded
    Variable 'http_proxy' is set, adding to container environment.
    Variable 'https_proxy' is set, adding to container environment.
    Generating a RSA private key
    .................................................+++++
    .................+++++
    writing new private key to '/data/grape/websetup/ssl/websetup.key.pem'
    -----
    Creating dhparam file, this will take a while...
    Creating shell wrapper for grape command
    Adding ~/.local/bin to PATH (in ~/.bashrc)
    Pulling nginx  ... done
    Pulling django ... done
    Pulling redis  ... done
    Creating network "websetup_default" with the default driver
    Creating volume "websetup_websetup_static" with default driver
    Creating websetup_nginx_1  ... done
    Creating websetup_redis_1  ... done
    Creating websetup_django_1 ... done
    Please open https://VM_IP_Address:8888 to configure Grape now.
    
  9. Enter the Websetup

    the Websetup runs by default on your Server’s IP with port 8888

    The Websetup is protected by HTTP Authentication, and can be unlocked with the same credentials you used when running install.sh

    The very first thing the websetup will ask of you is to download a Grape version.

    So please pick Stable (only ever install other versions if instructed to do so by a Grape technician)

    ../_images/fetch.png

    After successfully fetching a Grape version, you need to start configuring Grape

    ../_images/configure.png

    Most settings have meaningful default values that don’t need to be changed.

    The following fields need to be configured:

    In section grape:

    • Hostname of your Grape instance (this is the name configured on your DNS that points to the Grape server) e.g. grape.example.com

    • Email address Grape sends mails from (if you don’t have this decided yet, just use dummy data - e.g. grape@example.org)

    • Mailserver address to use (if you don’t have this decided yet, just use dummy data - e.g. localhost)

    • Single Organization Mode: turn this on, if you want to use only one Organization (grape running on your hostname) rather than multiple organizations by using subdomains (e.g. foo., bar., etc.)

    In section sentry:

    • Hostname of the Sentry instance (this is the name configured on your DNS that points to the Grape server for sentry) e.g. sentry-grape.example.com

    • Email address sentry sends mails from (if you don’t have this decided yet, just use dummy data - e.g. grape@example.org)

    • Mailserver address to use (if you don’t have this decided yet, just use dummy data - e.g. localhost)

    After successfully configuring Grape, you can now install for the first time. This will generate and populate all Grape containers with the configuration and start the Grape stack.

    ../_images/install.png

    Click Apply configuration and restart Grape to start the installation. This will take several minutes. The first time it takes the longest because many docker images must be pulled.

    Once Grape is up-and-running (see the Status page for details) you can login to Grape with the auto-generated admin user that is provided in Status -> credentials Please change this password ASAP.

Setup Certificates for Grape and Sentry

As mentioned earlier, you need certificates in x509 format in .key and .crt format for both the Grape Hostname and the Sentry Hostname

After first installing Grape, there appears a new option Certificates in the Navigation bar which allows looking at the installed Certificates, upload new certificates and set the uploaded Certificates to be used.

Current Certificates:

../_images/certificate_overview.png

In the Overview page you get to see the currently installed Certificates’ metadata as you may expect from using openssl

Upload Certificates:

Upload your .crt and .key files for grape and sentry - the files are stored in /data/grape/uploads

../_images/certificate_upload.png

in this example we upload the files grape_cert.key and grape_cert.crt

Update Certificates:

After uploading, pick the correct uploaded files to set the Certificates for Grape and Sentry.

../_images/certificate_update.png

Note: If you are specifying subdomains in Proxy Configuration, you can configure the Certificate for each Subdomain separately.

Finally, in order to apply those new Certificates, you need to restart the proxy. Currently the easist way to do that from the Websetup is to just restart Grape in the Status section.