UbuntuUbuntu Based

How To Install Apache CouchDB on Ubuntu 24.04 LTS

Install Apache CouchDB on Ubuntu 24.04

In this tutorial, we will show you how to install Apache CouchDB on Ubuntu 24.04 LTS. Apache CouchDB stands as a powerful, open-source document-oriented database system that has gained significant traction in the world of NoSQL databases. Known for its flexible JSON document storage, robust HTTP API, and impressive replication capabilities, CouchDB offers a unique approach to data management that resonates with developers across various domains. As Ubuntu continues to evolve, with version 24.04 on the horizon, it’s crucial for system administrators and developers to understand the nuances of installing and configuring CouchDB on this cutting-edge Linux distribution.

This comprehensive guide will walk you through the process of installing Apache CouchDB on Ubuntu 24.04, exploring multiple installation methods, configuration best practices, and essential post-installation steps. Whether you’re setting up a development environment or preparing for a production deployment, this article aims to equip you with the knowledge and tools necessary to harness the full potential of CouchDB on Ubuntu’s latest long-term support release.

Prerequisites

Before diving into the installation process, it’s essential to ensure your system meets the necessary requirements and is properly prepared. Let’s outline the prerequisites for a smooth CouchDB installation on Ubuntu 24.04.

System Requirements

To run Apache CouchDB efficiently, your Ubuntu 24.04 system should meet or exceed the following specifications:

  • A clean installation of Ubuntu 24.04 (minimal server recommended for production environments)
  • At least 2GB of RAM (4GB or more recommended for optimal performance)
  • 20GB of available disk space (more if you plan to store large amounts of data)
  • A user account with sudo privileges for administrative tasks

Preparation Checklist

Before proceeding with the installation, complete the following preparatory steps:

  1. Update your system packages:
    sudo apt update && sudo apt upgrade -y
  2. Install essential dependencies:
    sudo apt install -y build-essential curl apt-transport-https gnupg
  3. Verify that your firewall allows incoming connections on port 5984 (CouchDB’s default port):
    sudo ufw allow 5984/tcp

With these prerequisites in place, you’re ready to explore the various installation methods available for Apache CouchDB on Ubuntu 24.04.

Installation Methods

Apache CouchDB can be installed on Ubuntu 24.04 through several methods, each with its own advantages and considerations. We’ll explore four primary approaches: official package installation, Snap package deployment, manual installation from source, and using Docker containers.

Official Package Installation

As of early 2025, the official CouchDB packages for Ubuntu 24.04 are still in development. However, we can use a workaround by leveraging packages from Ubuntu 22.04. Here’s how to proceed:

  1. Add the CouchDB repository:
    echo "deb https://apache.jfrog.io/artifactory/couchdb-deb/ jammy main" | sudo tee /etc/apt/sources.list.d/couchdb.list
  2. Import the repository key:
    curl -L https://couchdb.apache.org/repo/keys.asc | gpg --dearmor | sudo tee /usr/share/keyrings/couchdb-archive-keyring.gpg >/dev/null 2>&1
  3. Update package lists:
    sudo apt update
  4. Install CouchDB:
    sudo apt install -y couchdb

During the installation, you’ll be prompted to choose between standalone and clustered mode. For most single-server setups, standalone mode is sufficient.

Snap Package Installation

Snap packages offer a convenient and isolated method for installing software. To install CouchDB using Snap:

sudo snap install couchdb

While Snap installation is straightforward, be aware that the version available might lag behind the latest release. Additionally, Snap’s confinement may require additional configuration for certain advanced setups.

Manual Installation from Source

For those who require the latest features or need to customize their installation, building CouchDB from source is an excellent option:

  1. Install build dependencies:
    sudo apt install -y erlang libicu-dev libmozjs-91-dev build-essential
  2. Download the latest CouchDB source:
    curl -L https://apache.org/dist/couchdb/source/3.3.2/apache-couchdb-3.3.2.tar.gz -o couchdb.tar.gz
  3. Extract and enter the source directory:
    tar xvzf couchdb.tar.gz
    cd apache-couchdb-3.3.2/
  4. Configure and build CouchDB:
    ./configure
    make release
  5. Install the built release:
    sudo make install

After installation, you’ll need to set up a systemd service file to manage CouchDB as a system service.

Docker Container Method

Docker provides a flexible and isolated environment for running CouchDB. Here’s a basic docker-compose.yml file to get started:

version: '3'
services:
  couchdb:
    image: couchdb:latest
    ports:
      - "5984:5984"
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=password
    volumes:
      - ./couchdb_data:/opt/couchdb/data

To start CouchDB using this configuration:

docker-compose up -d

This method is particularly useful for development environments or when you need to run multiple isolated instances of CouchDB.

Post-Installation Configuration

After successfully installing CouchDB, it’s crucial to properly configure the database for security and optimal performance. Let’s walk through the essential post-installation steps.

Admin Setup

Creating an admin user is your first line of defense in securing your CouchDB installation:

  1. Access the CouchDB configuration:
    sudo couchdb -c
  2. Set the admin username and password:
    [-admin]
    admin = mysecurepassword
  3. Save and exit the configuration file.

Remember to use a strong, unique password for your admin account. Consider using a password manager to generate and store complex passwords securely.

Network Configuration

By default, CouchDB listens on localhost. To make it accessible from other machines:

  1. Edit the CouchDB configuration file:
    sudo nano /opt/couchdb/etc/local.ini
  2. Locate the [chttpd] section and modify the bind_address:
    [chttpd]
    bind_address = 0.0.0.0
  3. Save and exit the file.
  4. Restart CouchDB:
    sudo systemctl restart couchdb

For production environments, it’s recommended to set up a reverse proxy like Nginx to handle incoming connections and provide an additional layer of security.

Security Hardening

Enhance your CouchDB installation’s security with these measures:

  1. Enable SSL/TLS:
    • Generate SSL certificates using Let’s Encrypt or a similar service.
    • Configure CouchDB to use SSL in the local.ini file:
      [ssl]
      cert_file = /path/to/cert.pem
      key_file = /path/to/key.pem
  2. Implement role-based access control:
    • Create roles and assign permissions using the _users database.
    • Use the _security document in each database to define read and write permissions.
  3. Enable audit logging:
    • Add the following to your local.ini file:
      [log]
      writer = file
      file = /var/log/couchdb/couch.log
      level = info

Using Fauxton Web Interface

Fauxton, CouchDB’s built-in web interface, provides a user-friendly way to manage your databases, documents, and queries. To access Fauxton:

  1. Open your web browser and navigate to http://localhost:5984/_utils
  2. Log in using the admin credentials you set earlier.

Install Apache CouchDB on Ubuntu 24.04 LTS

From the Fauxton dashboard, you can:

  • Create and manage databases
  • Add, edit, and delete documents
  • Design and execute Mango queries
  • Monitor cluster health and performance

To create your first database:

  1. Click on “Create Database” in the sidebar.
  2. Enter a name for your database and click “Create”.
  3. To add a document, click on the newly created database, then “Create Document”.
  4. Enter your JSON data and save the document.

Fauxton also provides a query interface where you can experiment with Mango syntax to retrieve and filter your data efficiently.

Basic Operations

Mastering basic CouchDB operations is essential for effective database management. Let’s explore some fundamental tasks you’ll frequently perform.

CLI Management

CouchDB can be managed via command-line interface (CLI) using system commands and curl requests:

  • Start CouchDB:
    sudo systemctl start couchdb
  • Stop CouchDB:
    sudo systemctl stop couchdb
  • Restart CouchDB:
    sudo systemctl restart couchdb
  • Check CouchDB status:
    sudo systemctl status couchdb

For API interactions, curl is a powerful tool:

  • Create a database:
    curl -X PUT http://admin:password@localhost:5984/mydb
  • Add a document:
    curl -X POST -H "Content-Type: application/json" -d '{"name":"Nadia Shela"}' http://admin:password@localhost:5984/mydb
  • Retrieve a document:
    curl http://admin:password@localhost:5984/mydb/document_id

Backup Strategies

Regular backups are crucial for data integrity. Here are two common backup methods:

  1. File system snapshots:
    • Stop CouchDB
    • Create a snapshot of the data directory
    • Restart CouchDB
  2. Using couchdb-dump utility:
    npm install -g couchdb-dump
    couchdb-dump http://admin:password@localhost:5984/mydb > backup.json

Monitoring

CouchDB provides built-in monitoring capabilities:

  • Access the statistics endpoint:
    curl http://admin:password@localhost:5984/_stats
  • For more comprehensive monitoring, consider integrating with Prometheus and Grafana:
    1. Install the CouchDB Prometheus exporter
    2. Configure Prometheus to scrape CouchDB metrics
    3. Set up Grafana dashboards to visualize the collected data

Troubleshooting

Even with careful installation and configuration, issues may arise. Here are some common problems and their solutions:

Dependency Conflicts with SpiderMonkey

If you encounter errors related to SpiderMonkey during installation:

  1. Ensure you have the correct version installed:
    sudo apt install libmozjs-91-dev
  2. If conflicts persist, consider building SpiderMonkey from source.

“No Release File” Errors

This error often occurs when repository information is outdated:

  1. Update your package lists:
    sudo apt update
  2. If the error persists, check the CouchDB repository status and consider using an alternative installation method.

Service Startup Failures

If CouchDB fails to start:

  1. Check the system logs:
    sudo journalctl -u couchdb
  2. Verify file permissions in the CouchDB data directory:
    sudo chown -R couchdb:couchdb /opt/couchdb

Authentication Problems

If you’re having trouble logging in:

  1. Double-check your admin credentials in the CouchDB configuration file.
  2. Ensure that CouchDB is running and accessible:
    curl http://localhost:5984

Replication Errors

For replication issues:

  1. Verify network connectivity between nodes.
  2. Check SSL certificate validity if using HTTPS.
  3. Ensure both source and target databases exist and are accessible.

Diagnostic Tools

Utilize these diagnostic tools for troubleshooting:

  • Examine CouchDB logs:
    sudo tail -f /var/log/couchdb/couch.log
  • Check CouchDB version:
    couchdb -V
  • Test network connectivity:
    telnet localhost 5984

Performance Optimization

To ensure your CouchDB installation runs at peak efficiency, consider these optimization strategies:

  1. Adjust memory allocation:
    • Increase the maximum number of file descriptors:
      sudo ulimit -n 65536
    • Optimize Erlang VM settings in vm.args file.
  2. Implement efficient view indexing:
    • Use composite keys to reduce the number of views.
    • Implement incremental map/reduce for large datasets.

Congratulations! You have successfully installed CouchDB. Thanks for using this tutorial for installing Apache CouchDB open-source non-relational database on Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the Apache website.

VPS Manage Service Offer
If you don’t have time to do all of this stuff, or if this is not your area of expertise, we offer a service to do “VPS Manage Service Offer”, starting from $10 (Paypal payment). Please contact us to get the best deal!

r00t

r00t is an experienced Linux enthusiast and technical writer with a passion for open-source software. With years of hands-on experience in various Linux distributions, r00t has developed a deep understanding of the Linux ecosystem and its powerful tools. He holds certifications in SCE and has contributed to several open-source projects. r00t is dedicated to sharing her knowledge and expertise through well-researched and informative articles, helping others navigate the world of Linux with confidence.
Back to top button