Environment Setup
This section provides you with an overview of the prerequisites required to build Grainite applications.
In addition to any system requirements specified by Docker, your machine should meet the following requirements:
- 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.

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
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.
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:- 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
- 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
- 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
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.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:- 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 thepip
Python package installer have been installed:
python3 -V
pip3 -V
- 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 thepip
Python package installer have been installed:
python3 -v
pip3 -v
- 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
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>
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/

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
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
The GX VS Code extension makes it a easier to write Grainite applications by offering useful tools for interacting with the Grainite server.
Last modified 1mo ago