Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Couchbase Lite on Java — Prerequisites

    March 16, 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.

    Preparatory Steps for Installation and Use

    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:

    Install Couchbase Server and Sync Gateway for instructions — see Install

    For supported versions — see: Compatibility | Supported OS

    Prepare Couchbase Server and Sync Gateway for the Test Build

    1. Within Couchbase Server, create a bucket named getting-started.cblite2

      For instructions — see: Create a Bucket

    2. Create a RBAC user for Sync Gateway

      For instructions — see: Create an RBAC User

      • Set username to sync-gateway

      • Set password to password

    How to Use 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 the Couchbase Downloads page.

    • Community Edition — couchbase-lite-java-2.8.3

    • Enterprise Edition — couchbase-lite-java-ee-2.8.3

    When unpacked the package contains the following:

    • A lib folder containing all necessary JAR files:

      • couchbase-lite-java-2.8.3 or for EE couchbase-lite-java-ee-2.8.3

      • 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

    1. Download the zip file from the Couchbase Downloads page.

    2. 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-2.8.3 — as the <pathToCbl>.

    3. 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
    ViewCopy
    apply plugin: 'java'
apply plugin: 'jar'
// apply plugin: 'war'
sourceCompatibility = 1.8
repositories {
  jcenter()
}
dependencies {
    implementation fileTree(dir: 'libs', include: '*.jar')
    compileOnly "javax.servlet:javax.servlet-api:4.0.1"
}

    Using Native Libraries for Linux

    In addition to setting-up your build environment, you also need to make the supplied native libraries (<pathToCbl/support) available:

    These libraries are provided only in the .zip distributable.
    Web Service/Tomcat

    1. Copy the native libraries (<pathToCbl>/support) to a location accessible to — and usable by — your build and runtime environments.

    2. Add the following libraries to the 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=<pathToCbl>/support/linux/x86_64/:$LD_LIBRARY_PATH
    Desktop

    1. Copy the native libraries (<pathToCbl>/support) to a location accessible to — and usable by — your build and runtime environments.

    2. Add the following libraries to the LD_LIBRARY_PATH in the .bashrc file:

      bashrc
      Copy
      export LD_LIBRARY_PATH=<pathToCbl>/support/linux/x86_64/:$LD_LIBRARY_PATH

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

    Related Content

    How to . . .
    Learn more . . .
    Dive Deeper . . .