API References
Grainite Homepage

Environment Setup

This section provides you with an overview of the prerequisites required to build Grainite applications.

System Requirements

In addition to any system requirements specified by Docker, your machine should meet the following requirements:

  • Operating system: Linux, Mac OS, or Windows with WSL

  • 4 physical CPU cores

  • 4 GB of RAM

  • 1 GB of Swap space

  • 32 GB of available disk space

  • 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 CLI can be downloaded by downloading the installer script by clicking the below link or running the wget command below it:

wget https://gitlab.com/api/v4/projects/41132986/releases/permalink/latest/downloads/gx-bin/install_gx.sh

After downloading the script, run it using the following command to install gx:

chmod +x install_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

  1. We'll be using Homebrew to install JDK. If you don't already have it, let's install that first.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

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

  2. Now you can install JDK.

brew install openjdk@17

  1. 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)

  1. We'll be using apt to install JDK. Let's first ensure it's up-to-date.

sudo apt update && sudo apt upgrade

  1. Next, let's install JDK 17.

sudo apt install openjdk-17-jdk

  1. 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)

  1. We'll be using Yum to install JDK. Let's first ensure its up-to-date.

sudo yum update

  1. Next, let's install JDK 17. 

sudo yum install java-17-openjdk

  1. 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, our client repository includes 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

  1. We'll be using Homebrew to install Python 3.10. If you don't already have Homebrew, let's install that first.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

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

  2. Now you can install Python (brew should install pip along with Python).

brew install python@3.10

  1. After the installation, you should verify that python and the pip Python package installer have been installed:

python3 -V
pip3 -V

on Linux (Debian/Ubuntu)

  1. We'll be using apt to install Python 3.10. Let's first ensure it's up-to-date.

sudo apt update && sudo apt upgrade

  1. Next, let's install Python and the pip package installer.

sudo apt install python3.10
sudo apt install python3-pip

  1. 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)

  1. We'll be using apt to install Python 3.11. Let's first ensure its up-to-date

sudo yum update

  1. Next, let's install Python and the pip package installer

sudo yum install python3.11
sudo yum install python3-pip

  1. 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).

pom.xml
<dependencyManagement> 
  ... 
  <dependency>
    <groupId>com.grainite</groupId>
    <artifactId>libgrainite</artifactId>
    <version>latest</version>
  </dependency>
</dependencyManagement>

<repositories>
   ...
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/41132986/packages/maven</url>
  </repository>
</repositories>

Docker Desktop

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:

git clone https://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.

sudo sysctl -w kernel.core_pattern=/home/grainite/dx/cores/core.%e.%p.%t

Optional: VS Code Extension

The GX VS Code extension makes it a easier to write Grainite applications by offering useful tools for interacting with the Grainite server.

PreviousGetting StartedNextRunning Grainite in Docker

Last updated