Skip to content

Latest commit

 

History

History
209 lines (150 loc) · 5.85 KB

README.md

File metadata and controls

209 lines (150 loc) · 5.85 KB
Raw
Localhost Databases

Apache CouchDB is a document-oriented NoSQL database.

About • Disclaimer • Getting Started • Download • How To Use

About

Apache CouchDB is an open-source document-oriented NoSQL database, implemented in Erlang. CouchDB uses multiple formats and protocols to store, transfer, and process its data. It uses JSON to store data, JavaScript as its query language using MapReduce, and HTTP for an API.

Disclaimer

Important

Localhost Databases is not affiliated with the databases' developers/owners and is not an official product.

Localhost Databases has been developed to run databases in a local Docker environment. To install a production instance, read the databases' respective installation guides.

Getting Started

You will need to make sure your system meets the following prerequisites:

  • Docker Engine >= 20.10.0

This repository utilizes Docker to run the CouchDB sample. So, before using the CouchDB, make sure you have Docker installed on your system.

Download

To use CouchDB, you can clone the latest version of Localhost Databases repository for macOS, Linux and Windows.

# Clone this repository.
$ git clone git@github.com:luisaveiro/localhost-databases.git --branch main --single-branch

You can locate the CouchDB Docker configuration in the databases directory.

# Navigate to the CouchDB folder.
$ cd localhost-databases/databases/couchdb

How To Use

There are a few steps you need to follow before you can have an CouchDB database set up and running in Docker container. I have outline the steps you would need to take to get started.

1. Environment Variables

Before you start a database in a Docker container, you will need to create a DotEnv file. The DotEnv file will allow you to configure your database's credentials and map a container's port.

Localhost Databases includes a .env.example file for CouchDB Database. You can run the following command in the terminal to create your DotEnv file.

# Navigate to a database.
$ cd databases/couchdb

# Create .env from .env.example.
$ cp .env.example .env

The CouchDB Docker Compose file uses the follow variables from the DotEnv file.

#--------------------------------------------------------------------------
# Docker env
#--------------------------------------------------------------------------

# The project name. | default: couchdb
APP_NAME="couchdb"

#--------------------------------------------------------------------------
# Database (CouchDB) env
#--------------------------------------------------------------------------

# The CouchDB database container name. | default: couchdb
DB_CONTAINER_NAME="${APP_NAME}"

# The CouchDB database user credentials.
DB_USERNAME=""
DB_PASSWORD=""

#--------------------------------------------------------------------------
# Network env
#--------------------------------------------------------------------------

# Map the database container exposed port to the host port. | default: 5984
DB_PORT=5984

# The Docker network for the containers. | default: local_dbs_network
NETWORK_NAME="local_dbs_network"

#--------------------------------------------------------------------------
# Volume env
#--------------------------------------------------------------------------

# The database container data volume. | default: couchdb_data
DB_VOLUME_DATA_NAME="${DB_CONTAINER_NAME}_data"

2. Start Docker container

To start the CouchDB container, you can run the following command:

# Navigate to CouchDB database.
$ cd databases/couchdb

# Run Docker Compose command.
$ docker compose up -d
Expected result

To check the CouchDB container is running and the port mapping is configured correctly, you can run the following command:

# List containers
$ docker ps

You should see a similar output.

CONTAINER ID   IMAGE            COMMAND                  CREATED              STATUS              PORTS                                        NAMES
8ad2865f5be1   couchdb:latest   "tini -- /docker-ent…"   About a minute ago   Up About a minute   4369/tcp, 9100/tcp, 0.0.0.0:5984->5984/tcp   couchdb

3. Stop Docker container

To stop the CouchDB container, you can run the following command:

$ docker compose down

4. Connect to Database

Fauxton is a native web-based interface built into CouchDB. It provides a basic interface to the majority of the functionality, including the ability to create, update, delete and view documents and design documents. It provides access to the configuration parameters, and an interface for initiating replication.To connect to your EdgeDB CouchDB from your browser, you will need to provide the following settings:

HOST=localhost
PORT="${DB_PORT}"

USER="${DB_USERNAME}"
PASSWORD="${DB_PASSWORD}"

You can access CouchDB Fauxton UI in your web browser at: http://localhost:5984/_utils.

Expected result

Below is a screenshot of the Fauxton UI:

CouchDB Fauxton UI
CouchDB Fauxton UI.

GitHub • LinkedIn • Twitter