A newer version of this documentation is available.

Couchbase Lite on Java — Prerequisites

March 23, 2025

+ 12

Description — Couchbase Lite on Java — a framework for developing offline-first Java applications for mobile and edge
Abstract — This content identities the pre-requisites and preparatory steps to be considered before installing Couchbase Lite for java

Introduction

Couchbase Lite on Java enables development and deployment of Couchbase Lite applications to a JVM environment. You can deploy to a desktop or web server (for example, Tomcat), including embedded Tomcat deployments.

We use Intellij IDEA, gradle, Maven and Tomcat as tools to build and run the examples presented in this content. You are free to use the tools of your choice.

Install Companion Software

If you want to use Couchbase Lite on Java with Couchbase Server and-or Sync Gateway you will need to have installed operational instances of these before completing the installation and test build steps.

So, If you have not already done so, see Prepare Sync Gateway

Within Couchbase Server, create a bucket named getting-started.cblite2
Create a RBAC user for Sync Gateway with username = sync-gateway and password = password

Downloaded Binaries

Package Contents

The download package contains a license file, jar libraries for the appropriate edition of the Couchbase Lite and a set of Linux shared libraries.

Get the download package from here — Extend with Mobile.

Community Edition — couchbase-lite-java-3.0.15
Enterprise Edition — couchbase-lite-java-ee-3.0.15

When unpacked the package contains the following:

A lib folder containing all necessary JAR files:
- couchbase-lite-java-3.0.15 or for EE couchbase-lite-java-ee-3.0.15
- okhttp-3.14.7.jar
- okio-1.17.2.jar
A support folder containing the Linux native libraries:

This means you do not need to download and-or build compatible versions of system libraries for the Linux platform of choice.
- libz (requires zlib v.1.2.11+)
- libC++ requires libc++ v.3.6.0+)
- libicu (requires ICU4C v.5.4.1+)

Steps

Download the zip file from here — Extend with Mobile.
Unpack the downloaded file to a location accessible to — and usable by — your chosen build environment.

We’ll refer to that location — <your dir>/couchbase-lite-java-3.0.15 — as the <pathToCbl>.
Include the following dependency in your build.gradle file, you can remove any Couchbase Lite Maven references:
```
Java
Copy
Dependencies {
  implementation fileTree(include: ['*.jar'], dir: <pathToCbl>/lib>
}
```

Where <pathToCbl> is the location of the downloaded Couchbase Lite library.

Sample build gradle

Java
Copy

Using Native Libraries for Linux

Additional Steps for Linux

In addition to setting-up your build environment, you also need to make the supplied support libraries available:

These libraries are provided only in the .zip distributable.

Web Service/Tomcat
Desktop

Copy the directory <exploded-distribution-zip>/support to a location accessible and executable by your build and runtime environments.

Unresolved include directive in modules/java/pages/_partials/gs-additional-steps-for-linux.adoc - include::partial$directory-diagrams.adoc[]
Add the paths of the directories libc++ and libicu to LD_LIBRARY_PATH in `$CATALINA_BASE/bin/setenv.sh. (If the setenv.sh file doesn’t exist, you will need to create a new file.)
```
bashrc
Copy
LD_LIBRARY_PATH=<lib-directory>/support/libc++:<lib-directory>/support/libicu:$LD_LIBRARY_PATH
```

Copy the directory <exploded-distribution-zip>/support to a location accessible and executable by your build and runtime environments.

Unresolved include directive in modules/java/pages/_partials/gs-additional-steps-for-linux.adoc - include::partial$directory-diagrams.adoc[]
Add the paths of the directories <lib-directory>/support/libc++ and <lib-directory>/support/libicu to LD_LIBRARY_PATH in the .bashrc file:
```
bashrc
Copy
export LD_LIBRARY_PATH=<lib-directory>/support/libc++:<lib-directory>/support/libicu:$LD_LIBRARY_PATH
```

Please refer to the Linux Platform Support section for the minimum version requirements of those libraries.

How to . . .

Learn more . . .

Dive Deeper . . .

Mobile Forum | Blog | Tutorials