1.9. Nouveau Server Installation

Added in version 3.4.0.

CouchDB can build and query full-text search indexes using an external Java service that embeds Apache Lucene. Typically, this service is installed on the same host as CouchDB and communicates with it over the loopback network.

Nouveau server is runtime-compatible with Java 11 or higher.

1.9.1. Enable Nouveau

You need to enable nouveau in CouchDB configuration;

[nouveau]
enable = true

1.9.2. Installation of Binary Packages

The Java side of nouveau is a set of jar files, one for nouveau itself and the rest for dependencies (like Lucene and Dropwizard).

To start the nouveau server:

java -jar /path/to/nouveau.jar server /path/to/nouveau.yaml

Ensure that all the jar files from the release are in the same directory as nouveau.jar

We ship a basic nouveau.yaml configuration with useful defaults; see that file for details.

nouveau.yaml:

maxIndexesOpen: 100
commitIntervalSeconds: 30
idleSeconds: 60
rootDir: target/indexes

As a DropWizard project you can also use the many configuration options that it supports. See configuration reference.

By default Nouveau will attempt a clean shutdown if sent a TERM signal, committing any outstanding index updates, completing any in-progress segment merges, and finally closes all indexes. This is not essential and you may safely kill the JVM without letting it do this, though any uncommitted changes are necessarily lost. Once the JVM is started again this indexing work will be attempted again.

1.9.3. Securing Nouveau

By default Nouveau uses HTTP without client authentication as it is commonly deployed on the same server as CouchDB itself. It is however possible to deploy Nouveau with robust security and this is strongly recommended when Nouveau is running on a separate server, even over a private network you trust.

To enforce secure communications between CouchDB and the Nouveau server you need to modify configuration in both.

We use mutual TLS to achieve private communication and ensure the identity of client and server.

1.9.3.1. Configuring CouchDB to authenticate to Nouveau

You can configure CouchDB to connect to a secured Nouveau server as follows;

[nouveau]
url = https://hostname:port
ssl_key_file = path to keyfile
ssl_cert_file = path to certfile
ssl_cacert_file = path to cacertfile
ssl_password = password

You must set ssl_key_file and ssl_cert_file to activate client certificates. You might also need to set ssl_password if the ssl_key_file is password-protected and might need to set ssl_cacert_file if the Nouveau server’s certificate is signed by a private CA.

1.9.3.2. Configuring Nouveau to authenticate clients

Nouveau is built on the dropwizard framework, which directly supports the HTTPS <https://www.dropwizard.io/en/stable/manual/configuration.html#https> transports.

Acquiring or generating client and server certificates are out of scope of this documentation and we assume they have been created from here onward. We further assume the user can construct a Java keystore.

in nouveau.yaml you should remove all connectors of type http and add new ones using https;

server:
  applicationConnectors:
    - type: https
      port: 5987
      keyStorePath: <path to keystore>
      keyStorePassword: <password to keystore>
      needClientAuth: true
      validateCerts: true
      validatePeers: true

If you’re using self-generated certificates you will also need to set the trustStorePath and trustStorePassword attributes.

1.9.4. Docker

There is a version of of the semi-official CouchDB Docker image available under the *-nouveau tags (eg, 3.4-nouveau).

1.9.4.1. Compose

A minimal CouchDB/Nouveau cluster can be create with this compose:

services:
  couchdb:
    image: couchdb:3
    environment:
      COUCHDB_USER: admin
      COUCHDB_PASSWORD: admin
    volumes:
      - couchdb:/opt/couchdb/data
    ports:
      - 5984:5984
    configs:
      - source: nouveau.ini
        target: /opt/couchdb/etc/local.d/nouveau.ini

  nouveau:
    image: couchdb:3-nouveau

volumes:
  couchdb:

configs:
  nouveau.ini:
    content: |
      [couchdb]
      single_node=true
      [nouveau]
      enable = true
      url = http://nouveau:5987

Note

This is not production ready, but it is a quick way to get Nouveau running.