Skip to content

Latest commit

 

History

History
93 lines (58 loc) · 3.87 KB

SOURCE-INSTALLATION.md

File metadata and controls

93 lines (58 loc) · 3.87 KB

ZomboDB Source Installation Instructions

If you're a sponsor you might want to also read the [BINARY-INSTALLATION.md] documentation.

Prerequisites

  • Postgres 10.x, 11.x, 12.x, or 13.x installed (probably from your package manager), including the "-server" package

  • A toolchain capable of building Postgres:

    For Ubuntu, this is enough:

    apt install bison flex zlib1g zlib1g-dev \
    pkg-config make libssl-dev libreadline-dev

  • The Rust toolchain

  • cargo install cargo-pgrx

  • A 64bit Intel Architecture

Building from Sources

First off, and you'll only need to do this once, you need to initialize cargo-pgrx, and you'll want to tell it the path to the version of Postgres on your computer.

If that version of Postgres is pg12, and assuming its pg_config tool is on your $PATH, this will likely work:

$ cargo pgrx init --pg12=`which pg_config`

Next, clone this repo, change into the checkout directory and simply run:

$ cargo pgrx install --release

This will compile ZomboDB and install it into the Postgres installation described by pg_config. The user that runs the above command will need write permissions to the Postgres $PG_INSTALL_PATH/lib/postgresql/ and $PG_INSTALL_PATH/share/postgresql/extension/ directories.

Updating ZomboDB to a New Version

Updating ZomboDB from sources will simply require a git pull, another make clean install and running ALTER EXTENSION zombodb UPDATE; in all databases that use the ZomboDB extension.

TLS Support via rustls

ZomboDB supports TLS connections to Elasticsearch via the rustls and native-tls crates. By default, ZomboDB is compiled with rustls support. By default it will trust webpki-roots, a copy of the Mozilla Root program that is bundled into ZomboDB.

If you want to use custom certificates you will need to enable rustls_native_certs feature when building ZomboDB. This will use the OS certificate verifier and trust store.

Note

If you want to load a certificate from the file - you can set the SSL_CERT_FILE environment variable to the path of the certificate file.

Enabling TLS Support via native-tls

By default, ZomboDB is compiled with rustls support. If you'd like to use native-tls instead, you'll need to enable the native_tls feature when building ZomboDB.

Both rustls and native-tls support TLS connections via the https scheme. Both features will use the OS certificate verifier and trust store.

You may want to use native-tls if you are using TLS 1.1 or 1.0, as rustls does not support these older TLS versions or if you need to validate the certificates for IP addresses.

Building Binary Artifacts with Docker

If you have a proper Docker installation you can simply run:

$ cd docker-build-system
$ cargo run <branch-name> [<docker-image-name> <pg major version>]

Likely for the <branch-name> argument you'll want to specify master, unless perhaps you're working on a custom branch.

If you're only targeting one Linux distro and Postgres version, you'll want to specify all three arguments.

This process will take a long time (potentially hours depending on your download speeds), but it will build ZomboDB for all supported Linux distro and Postgres version permutations.

You can set an environment variable named CPUS to limit the number of CPUs the build process will use, but the default is however many your computer has.

The final binary artifacts will be placed in the ./target/zdb-build/artifacts/ directory.

No logs are created, but in the event of Docker/compilation errors, the entire output of the thing that failed is printed to stdout.

Once binary artifacts are build, follow the instructions in [BINARY-INSTALLATION.md] to install the proper artifact for your environment.