Getting Started on Linux

This guide walks through installing a locally accessible FoundationDB server that is suitable for development on Linux.

To install an externally accessible FoundationDB cluster on one or more machines, see Building a Cluster.

First steps

  • Validate your system meets the System requirements.

  • Download the FoundationDB packages for your system from Downloads.

  • Before upgrading from a previous version of FoundationDB, see Upgrading.

Installing or upgrading FoundationDB packages

Warning

Unless using the Multi-version client, the installed client and server packages must have the same version. When upgrading a FoundationDB cluster, be sure also to upgrade all clients to the same version.

To install on Ubuntu use the dpkg command:

user@host$ sudo dpkg -i foundationdb-clients_8.0.0-1_amd64.deb \
foundationdb-server_8.0.0-1_amd64.deb

To install on RHEL/CentOS 6 use the rpm command:

user@host$ sudo rpm -Uvh foundationdb-clients-8.0.0-1.el9.x86_64.rpm \
foundationdb-server-8.0.0-1.el9.x86_64.rpm

To install on RHEL/CentOS 7 use the rpm command:

user@host$ sudo rpm -Uvh foundationdb-clients-8.0.0-1.el9.x86_64.rpm \
foundationdb-server-8.0.0-1.el9.x86_64.rpm

FoundationDB installs in a single-server mode appropriate for a development workstation. In this mode data is not replicated, and therefore the database is not failure tolerant. This default database is also configured to use the memory storage engine which, while using the disk for durability, requires data to fit in RAM.

By default FoundationDB uses the loopback IP (127.0.0.1). In this configuration all parts of FoundationDB, including client applications, must run on the same machine and communicate via 127.0.0.1, not via external IPs.

Installing multiple client versions

The regular foundationdb-clients RPM installs files in shared system paths and is intended for a normal install or upgrade. Do not install two regular client RPMs with rpm -ivh; they own the same files and RPM will report file conflicts.

For multi-version client support, use the separately named CPack versioned client RPMs. Their names have the form foundationdb<version>-clients-1.versioned.<architecture>.rpm and their files are installed below /usr/lib/foundationdb-<version>/. Non-release builds may include build-time and prerelease text in the package name and directory. Install each versioned package with rpm -ivh so the packages can remain installed simultaneously. If a release does not publish its versioned RPM, build the clients-versioned component from source with CPack (run cpack -G RPM from the configured build directory).

The active client is selected through the fdbclients alternatives group. Use update-alternatives --display fdbclients to inspect it and update-alternatives --config fdbclients to select a version. The selected alternative applies consistently to the client tools, library, headers, pkg-config metadata, and CMake package metadata.

Testing your FoundationDB installation

To verify that the local FoundationDB database is operational, open the command line interface (fdbcli) and use the status command.

user@host$ fdbcli
Using cluster file `/etc/foundationdb/fdb.cluster'.

The database is available.

Welcome to the fdbcli. For help, type `help'.
fdb> status

Configuration:
  Redundancy mode        - single
  Storage engine         - memory
  Coordinators           - 1

Cluster:
  FoundationDB processes - 1
  Machines               - 1
  Memory availability    - 4.1 GB per process on machine with least available
  Fault Tolerance        - 0 machines
  Server time            - Thu Mar 15 14:41:34 2018

Data:
  Replication health     - Healthy
  Moving data            - 0.000 GB
  Sum of key-value sizes - 8 MB
  Disk space used        - 103 MB

Operating space:
  Storage server         - 1.0 GB free on most full server
  Transaction log        - 1.0 GB free on most full server

Workload:
  Read rate              - 2 Hz
  Write rate             - 0 Hz
  Transactions started   - 2 Hz
  Transactions committed - 0 Hz
  Conflict rate          - 0 Hz

Backup and DR:
  Running backups        - 0
  Running DRs            - 0

Client time: Thu Mar 15 14:41:34 2018

If these steps were successful you have installed and validated FoundationDB. You can now start using the database!

Note

If the database is not operational the status command will provide diagnostic information to help you resolve the issue.

Managing the FoundationDB service

Next steps

  • Install the APIs for Ruby, Python, Java or Go if you intend to use those languages. The C API was installed along with the foundationdb-clients package above.

  • See Tutorials for samples of developing applications with FoundationDB.

  • See Developer Guide for information of interest to developers, including common design patterns and performance considerations.

  • See Administration for detailed administration information.

  • See Known Limitations of the system.

  • See Building a Cluster for step-by-step instructions on converting your local single-machine cluster to an externally visible cluster of one or more machines.