If using Docker Desktop, select gRPC FUSE as the file sharing implementation.
If you are on MacOS, we recommend a configuration of 4 CPUs, 4GB RAM, 1GB of swap space and a minimum of 32 GB of available disk space. This can be done by going to Docker > Preferences (gear icon in top right of window) > Resources > Advanced and using the slider controls there for CPUs and Memory. If necessary, the Grainite container can run with only 2 CPUs allocated, but performance will be degraded.
gx CLI
The gx CLIcan be downloaded by downloading the installer script by clicking the below link or running the wget command below it:
After downloading the script, run it using the following command to install gx:
chmod+xinstall_gx.sh&&sudo./install_gx.sh
This will install gx into /usr/local/bin. Once the installation is complete, you can run the following to verify gx has been installed:
gx--version
Java or Python
Grainite currently exposes APIs in Java and Python and plans to support other languages in the future. For now, you will either need to have Java (JDK 11 or above) or Python (3.7 or above) installed in order to begin developing applications on Grainite. Currently, the Extensions provided by Grainite are mostly implemented in Java and require installation of Java.
If you don't have Java or Python installed in your environment, you can use the following instructions to install one of them, depending on your preference. Feel free to follow both setup instructions if you'd like to be able to run any of our sample apps.
Java Setup
You'll need to have a JDK installation on your system. JDK 11 is the minimum supported version for building Grainite applications, and we recommend JDK 17. You'll need to ensure either the java executable is in your PATH or set the JAVA_HOME environment variable to point to your JDK installation. Below are instructions for installing JDK for a few different platforms using a package manager, in case you don't already have Java on your system:
Install Java
on MacOS
We'll be using Homebrew to install JDK. If you don't already have it, let's install that first.
Once Homebrew is finished installing, it will print some next steps at the end of the output which will add brew to your path. Please follow those steps.
Now you can install JDK.
brewinstallopenjdk@17
After the installation, brew will provide you with instructions to add java to your path. Please follow those steps. Afterwards, you can run the below command to confirm the JDK installation was successful (it should return some output which includes the version that was just downloaded).
java--version
on Linux (Debian/Ubuntu)
We'll be using apt to install JDK. Let's first ensure it's up-to-date.
sudoaptupdate&&sudoaptupgrade
Next, let's install JDK 17.
sudoaptinstallopenjdk-17-jdk
Lastly, let's run the below command to confirm the JDK installation was successful (it should return some output which includes the version that was just downloaded).
java--version
on Linux (RHEL/UBI)
We'll be using Yum to install JDK. Let's first ensure its up-to-date.
sudoyumupdate
Next, let's install JDK 17.
sudoyuminstalljava-17-openjdk
Lastly, let's run the below command to confirm the JDK installation was successful (it should return some output which includes the version that was just downloaded)
java--version
Build Tool
You'll need a build tool, such as Maven (minimum version: 3.8.3) or Gradle, for support building Grainite applications. All of our java app documentation refers to Maven for building and our sample applications build with Maven, so we strongly recommend using Maven. Additionally, ourclient repositoryincludes a Maven Wrapper to enable quickly building your first Grainite application without directly needing to install Maven yourself.
Our sample applications have pom.xml files prepackaged with them. For creating your own applications, we recommend using gx gen all which will generates classes, constants, and other files based on the YAML configuration file you define for your application. For Maven users, it will by default create a pom.xml file for you which contains the necessary Grainite dependency and repository. If you choose to use Gradle, you can specify gx gen all --gradle to produce an equivalent build.gradle file instead.
Optional: If you happen to already have an application with a pom.xml or build.gradle file or for some other reason choose not to use gx gen all , further instructions can be found here.
Python Setup
We will first need to install Python and the pip package installer. Grainite supports Python version 3.8 or higher. Below are instructions for installing Python for a few different platforms using a package manager, in case you don't already have Python on your system:
Install Python and pip
on MacOS
We'll be using Homebrew to install Python 3.10. If you don't already have Homebrew, let's install that first.
Once Homebrew is finished installing, it will print some next steps at the end of the output which will add brew to your path. Please follow those steps.
Now you can install Python (brew should install pip along with Python).
brewinstallpython@3.10
After the installation, you should verify that python and the pip Python package installer have been installed:
python3-Vpip3-V
on Linux (Debian/Ubuntu)
We'll be using apt to install Python 3.10. Let's first ensure it's up-to-date.
sudoaptupdate&&sudoaptupgrade
Next, let's install Python and the pip package installer.
sudoaptinstallpython3.10sudoaptinstallpython3-pip
After the installation, you should verify that python and the pip Python package installer have been installed:
python3 -v
pip3 -v
on Linux (RHEL/UBI)
We'll be using apt to install Python 3.11. Let's first ensure its up-to-date
sudo yum update
Next, let's install Python and the pip package installer
After installation, you should verify that python and pip Python package installers have been installed.
python3 -v
pip3 -v
Grainite Client Library
When developing Grainite applications, you'll need to invoke the Grainite API for the language you are using through the Grainite Client Library. See how to access it for one of the supported languages below:
The Client Library for Java is resolved while building an app, after you specify it as a dependency in the app's pom.xml file as shown in the snippet below. This dependency is automatically added to the new pom.xml file that's generated you when you use our code-generation feature (see Creating a New Java App).
The above will install the latest version of the Grainite Client Library if none exists locally. To specify a different Grainite version, use the command below, replacing <version> with the intended version. Note the version specified should be of the form 23.27.0 (for Grainite version 2327).
To run your application locally, you'll need to download and install Docker on the laptop or VM you're using for development, if not already installed. This will enable you to run the Grainite server inside a Docker container that your application will then run on.
You may use your default package manager to install Docker - or go to this link https://docs.docker.com/get-docker/
Client Repository
The client repository includes sample apps to help you get started on developing with Grainite as well as support bundle collection scripts. Run the following command to clone the client repository onto your machine:
gitclonehttps://gitlab.com/grainite/samples
Crash Reports (Linux)
If you'll be running Grainite in Linux, please run the below command to enable cores to be generated, which will allow you to properly report any crashes to Grainite support.