---
title: "Install Gravitino"
slug: "/how-to-install"
license: "This software is licensed under the Apache License version 2."
---

## Install from a Binary Release

:::note
Apache Gravitino supports running on Java 17, and higher versions should also work but not fully tested. Make sure you have Java installed and
`JAVA_HOME` configured correctly. To confirm the Java version, run the
`${JAVA_HOME}/bin/java -version` command.
:::

The Gravitino package comprises both the Gravitino server and the Gravitino Iceberg REST server. Manage these servers independently or run them concurrently on a single server.

### Get the Binary Distribution Package

Before installing Gravitino, make sure you have the Gravitino binary distribution package. Download the latest Gravitino binary distribution package from [GitHub](https://github.com/apache/gravitino/releases).
To build it yourself, follow the instructions in [How to Build Gravitino](./how-to-build.md).

- If you build Gravitino yourself using the `./gradlew compileDistribution` command, you can find the Gravitino binary distribution package in the `distribution/package` and `distribution/package-all` directory. The main difference between these two packages is that the `package-all` package contains all catalogs including catalog under folder `catalogs-contrib`, while the `package` package only contains the main catalogs under folder `catalogs`.

- If you build Gravitino yourself using the `./gradlew assembleDistribution` command, you can get the compressed Gravitino binary distribution package with the name `gravitino-<version>-bin.tar.gz` in the `distribution` directory with sha256 checksum file `gravitino-<version>-bin.tar.gz.sha256`. Also, you can get the complete compressed Gravitino binary distribution package with the name `gravitino-<version>-bin-all.tar.gz` in the `distribution` directory with sha256 checksum file `gravitino-<version>-bin-all.tar.gz.sha256`. The main difference between these two packages is that the `-all` package contains all catalogs including catalog under folder `catalogs-contrib` while the normal package only contains the main catalogs under folder `catalogs`.

Note: **Apache Gravitino only releases `gravitino-<version>-bin.tar.gz` packages on GitHub releases and the `gravitino-<version>-bin-all.tar.gz` packages are only for users who build Gravitino from source code by themselves if interested.**

The Gravitino binary distribution package contains the following files:

```text
|── ...
└── distribution/package
    |── bin/
    |   ├── gravitino.sh                        # Gravitino server Launching scripts.
    |   └── gravitino-iceberg-rest-server.sh    # Gravitino Iceberg REST server Launching scripts.
    |── catalogs
    |   └── fileset/                            # Fileset catalog dependencies and configurations.
    |   └── hive/                               # Apache Hive catalog dependencies and configurations.
    |   └── jdbc-doris/                         # JDBC doris catalog dependencies and configurations.
    |   └── jdbc-mysql/                         # JDBC MySQL catalog dependencies and configurations.
    |   └── jdbc-starrocks/                     # JDBC Starrocks catalog dependencies and configurations.
    |   └── jdbc-postgresql/                    # JDBC PostgreSQL catalog dependencies and configurations.
    |   └── jdbc-hudi/                          # Hudi catalog dependencies and configurations.
    |   └── kafka/                              # Apache Kafka catalog dependencies and configurations.
    |   └── lakehouse-iceberg/                  # Apache Iceberg catalog dependencies and configurations.
    |   └── lakehouse-paimon/                   # Apache Paimon catalog dependencies and configurations.
    |   └── model/                              # Model catalog dependencies and configurations.
    |── conf/                                   # All configurations for Gravitino.
    |   ├── gravitino.conf                      # Gravitino server and Gravitino Iceberg REST server configuration.
    |   ├── gravitino-iceberg-rest-server.conf  # Gravitino server configuration.
    |   ├── gravitino-env.sh                    # Environment variables, etc., JAVA_HOME, GRAVITINO_HOME, and more.
    |   └── log4j2.properties                   # log4j configuration for the Gravitino server and Gravitino Iceberg REST server.
    |── libs/                                   # Gravitino server dependencies libraries.
    |── logs/                                   # Gravitino server and Gravitino Iceberg REST server logs. Automatically created after the server starts.
    |── data/                                   # Default directory for the Gravitino server to store data.
    |── iceberg-rest-server/                    # Gravitino Iceberg REST server package and dependencies libraries.
    └── scripts/                                # Extra scripts for Gravitino.
```

:::note
Catalogs `OceanBase` and `ClickHouse` are not included in the Gravitino binary distribution package (see above) by default due to package size limitations and License compatibility issues since 1.2.0.
If you want to use these two catalogs, build the Gravitino binary distribution package yourself and use tarball `gravitino-<version>-bin-all.tar.gz`, which contains all catalogs including those in the `catalogs-contrib` module.
For more details about it, refer to [Reorg catalogs structure](https://github.com/apache/gravitino/pull/9781)
:::

#### Initialize the RDBMS (Optional)

If you want to use the relational backend storage, you need to initialize the RDBMS first. For the details on initializing the RDBMS, see [How to use relational backend storage](./how-to-use-relational-backend-storage.md).

#### Configure the Server

The Gravitino server configuration file is `conf/gravitino.conf`. Configure the Gravitino server by modifying this file. Basic configurations have already been added to this file. All the configurations are listed in [Gravitino Server Configurations](./gravitino-server-config.md).

#### Configure the Server Log

The Gravitino server log configuration file is `conf/log4j2.properties`. Gravitino uses Log4j2 as the logging system. Refer to the [Log4j2 configuration guide](https://logging.apache.org/log4j/2.x/) to do the log configuration.

#### Configure the Server Environment

The Gravitino server environment configuration file is `conf/gravitino-env.sh`. Gravitino exposes several environment variables. Modify them in this file.

#### Configure Catalogs

Gravitino supports multiple catalogs. Configure the catalog-level configurations by modifying the related configuration file in the `catalogs/<catalog-provider>/conf` directory. The configurations you set here apply to all the catalogs of the same type you create.

For example, if you want to configure the Hive catalog, you can modify the file `catalogs/hive/conf/hive.conf`. The detailed configurations are listed in the specific catalog documentation.

:::note
Gravitino takes the catalog configurations in the following order:

1. Catalog `properties` specified in catalog creation API or REST API.
2. Catalog configurations specified in the catalog configuration file.

The catalog `properties` can override the catalog configurations specified in the configurationfile.
:::

Gravitino supports passing in catalog-specific configurations if you add `gravitino.bypass.`. For example, if you want to pass in the HMS-specific configuration `hive.metastore.client.capability.check` to the underlying Hive client in the Hive catalog, add the `gravitino.bypass.` prefix.

Also, Gravitino supports loading catalog-specific configurations from external files. For example,you can put your own `hive-site.xml` file in the `catalogs/hive/conf` directory, and Gravitino loads it automatically.

#### Start the Server

After configuring the Gravitino server, start the Gravitino server by running:

```shell
./bin/gravitino.sh start
```

Alternatively, to start the Gravitino server Web UI, run:

```shell
./bin/gravitino.sh run
```

Access the Gravitino Web UI by typing [http://localhost:8090](http://localhost:8090) in your browser, or you can run:

```shell
curl -v -X GET -H "Accept: application/vnd.gravitino.v1+json" -H "Content-Type: application/json" http://localhost:8090/api/version
```

to make sure Gravitino is running.

:::info
If you need to debug the Gravitino server, enable the `GRAVITINO_DEBUG_OPTS` environment variable in the `conf/gravitino-env.sh` file. Then create a `Remote JVM Debug` configuration in `IntelliJ IDEA` and debug `gravitino.server.main`.
:::

#### Manage Gravitino Iceberg REST Server in Gravitino Package

Run the Iceberg REST server as either a standalone server or as an auxiliary service embedded in the Gravitino server. To start it as a standalone server, use the command `./bin/gravitino-iceberg-rest-server.sh start` with configurations specified in `./conf/gravitino-iceberg-rest-server.conf`. Alternatively, use `./bin/gravitino.sh start` to launch a Gravitino server that integrates both the Iceberg REST service and the Gravitino service, with all configurations centralized in `conf/gravitino.conf`. 

For more detailed information about the Gravitino Iceberg REST server, refer to [Iceberg REST server document](./iceberg-rest-service.md).

## Install Using Docker

### Get the Docker Image

Gravitino publishes the Docker image to [Docker Hub](https://hub.docker.com/r/apache/gravitino/tags).
Run the Gravitino Docker image by running:

```shell
docker run -d -i -p 8090:8090 apache/gravitino:<version>
```

Access the Gravitino Web UI by typing `http://localhost:8090` in your browser, or you
can run

```shell
curl -v -X GET -H "Accept: application/vnd.gravitino.v1+json" -H "Content-Type: application/json" http://localhost:8090/api/version
```

to make sure Gravitino is running.

### Using GCS as Object Store with Docker

If your catalog uses Google Cloud Storage (GCS) as the object store, set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable and mount the service account key file into the container:

```shell
docker run -d -i -p 8090:8090 \
  -v /path/to/your-service-account-key.json:/etc/gcs/key.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/etc/gcs/key.json \
  apache/gravitino:<version>
```

## Install Using Docker Compose

The published Gravitino Docker image only contains the Gravitino server with a basic configuration. If you want to experience the whole Gravitino system with other components, use the Docker `compose` file.

For the details, review the
[Gravitino playground repository](https://github.com/apache/gravitino-playground) and
[playground example](./how-to-use-the-playground.md).

<img src="https://analytics.apache.org/matomo.php?idsite=62&rec=1&bots=1&action_name=HowToInstall" alt="" />

## Deploy on Kubernetes Using Helm Chart

The Apache Gravitino Helm chart provides a way to deploy Gravitino on Kubernetes with fully customizable configurations. 
For detailed installation instructions and configuration options, refer to the [Apache Gravitino Helm Chart](./chart.md).
