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.
​
Docker Desktop Settings
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:
https://gitlab.com/api/v4/projects/41132986/releases/permalink/latest/downloads/gx-bin/install_gx.sh
gitlab.com
install_gx.sh
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)"
2.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.
3.Now you can install JDK.
brew install openjdk@17
4.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
2.Next, let's install JDK 17.
sudo apt install openjdk-17-jdk
3.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
2.Next, let's install JDK 17. 
sudo yum install java-17-openjdk
3.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)"
2.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.
3.Now you can install Python (brew should install pip along with Python).
brew install [email protected]
4.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
2.Next, let's install Python and the pip package installer.
sudo apt install python3.10
sudo apt install python3-pip
3.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
2.Next, let's install Python and the pip package installer
sudo yum install python3.11
sudo yum install python3-pip
3.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:
Java
Python
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>
If developing on Grainite in Python, the Grainite Client Library for Python must be imported using the pip installer:
pip3 install grainite-cl --index-url https://gitlab.com/api/v4/projects/41132986/packages/pypi/simple
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).
pip3 install grainite-cl --index-url https://gitlab.com/api/v4/projects/41132986/packages/pypi/simple grainite_cl==<version>
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
Environment Setup
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.
https://marketplace.visualstudio.com/items?itemName=Grainite.gx
marketplace.visualstudio.com
GX VS Code Extension
Last modified 1mo ago