Fauxton Visual Guide

Welcome to Fauxton.

Apache CouchDB is a database that uses JSON for documents, JavaScript for MapReduce indexes, and regular HTTP for its API.
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.

Getting Started


Start by downloading the CouchDB suite:
1. Go to couchdb.apache.org, and click
2. Learn how to install and setup CouchDB from here, then go to


Features Overview

This guide is from September 2016. Fauxton is continuously being improved, so there may be slight differences in the examples in this document vs the latest and greatest Fauxton on npm.

When you first start to use Fauxton, the left most navigation panel will allow you jump quickly between viewing different parts of what's going on in your CouchDB instance.

First Start

You can expand or collapse the navigation by clicking in the top left corner of the page.

Databases will show you a list of all your databases, their size, number of documents, and provides quick links to it's permissions page and replication page.

Setup is a wizard to set up and configure CouchDB clusters or a single node.

Active Tasks displays a list of the running background tasks on the server. Background tasks include view index building, compaction and replication. This page is an interface to the Active Tasks API call.

Config is an interface for the configuration of your CouchDB installation. The interface allows you to edit different configurable parameters. For more details on configuration, see Configuring CouchDB.

Replication is an interface to the replication system, enabling you to initiate replication between local and remote databases.

Documentation will direct you to your local copy of the documentation. The link shown in this guide is to the online version.

Login/User Management lets you can change your password, or add administrator to your CouchDB instance.

Verify verifies your installation and allows you to check whether all of the components of your CouchDB installation are correctly installed.


Create Database Click this button on the top bar, and enter the name of the database you want to create. Create a database

Once created, you should see a success message in green at the top of the window: Create DB Sucess

Search for a Database This text field auto-completes and jumps directly to a specified database. Search for a database

View a Database This link will take to that database's "All Docs" page where you can view all of that database's contents. You can also delete, replicate, and change the permissions for a database from the database's 'All Docs' page. Select a DB

A Single Database

All Documents When you click on the database name, from the Databases page, you will see the All Docs page. Here you can create and edit documents, and create and edit views. All Docs

Create a Document Click on the plus symbol to open the 'Add new' menu. Create a Doc Menu

This should open a menu that will let you choose what the new document type you would like to create.

Create a Doc Menu

If you click New Doc, you'll be taken to the Fauxton text editor.

The Editor

The Editor When you first arrive at the editor, you will see: Editor

At this point, nothing has been created yet. The document on screen is pre-filled with a JSON object, and an _id with a Globally Unique Identifier (GUID). If you want to change the value of the _id, you must do that before you create the document.

You can edit any data for the document before or after creating the document, except for the _id, after it has been created.

Adding Data: Adding data

Click the Create Document to save the document.

Click Create

After you click Create Document you will go to back to the All Docs page, and you should see it there with a success message in green up top. If you did not change the ID, you may not be able to see your data on this screen. Create Document Success

You can click on the Include Docs checkbox to see the entire document on this screen. Included Docs

Included Docs

Database Maintenance

DB Maintenance DB Admin Menu This menu will allows you replicate the Database, and as well as delete it. DB Admin Menu

Replication Link Jump directly to the Replication page for this database. Replicate a DB

Permissions Link Jump directly to the Permissions page for this database. Jump to Permissions


The Setup tab provides an installation wizard to help you setup a cluster, in case you haven’t done before, or in case you would prefer to use Fauxton.

You can read more about it in the docs: Cluster Setup Wizard

Setup 1 Setup 2

You can read more about CouchDB clusters in the docs as well: CouchDB Clusters

Active Tasks

1 Change Polling Interval The status of each task can change as you are watching the Active Tasks page. The page auto-updates, but polls at regular intervals. You can set the amount of time that the page updates itself by dragging on this bar. Active Tasks Polling

2 API URL This page is an interface to the Active Tasks API call. You can view or copy the raw JSON by clicking on this button. Active Tasks API

3 Filter You can filter by the type of task, or search active tasks by database name (either source or target) using these tabs. Active Tasks Filter


This may be disabled in Fauxton if you are using CouchDB 2.0, and you can only change config parameters via the backdoor port. It's best not to use Fauxton for setting config in 2.0, rather use a config tool like chef, puppet, ansible, etc.

In earlier versions, the interface allows you to edit some of the different configurable parameters.



CORS stands for Cross Origin Resource Sharing. It is a setting that pertains only to browsers.

By enabling CORS, you allow other people, from their browsers, to access the data you have stored in your CouchDB databases.

They can ping your CouchDB instance through an AJAX request, and it will return information. Or they can POST data to your CouchDB instance, and CORS allows you to recieve that information.

For example, if your CouchDB installation is running on the domain alice.example you can ping someone else's CouchDB instance through an AJAX request from a different domain, e.g. bob.example - or even localhost!

But be careful - allowing any domain to access your data can be a security risk. If you only want certain websites (origins) to be able to retrieve and change data, you can set 'Restrict to specific domains', and then list which origins you want to allow access for.

By setting, 'All domains', you allow anyone from anywhere to ping your databases, and retrieve information that way.

If you disable CORS, the JavaScript that makes the AJAX request needs to run on the same domain. With CORS disabled frontend code that runs on alice.example must be also hosted on alice.example. Disabling CORS, means that no browser that pings your databases will recieve information.

You can also limit who can ping you. If you only want certain websites, or origins, to be able to recieve data from your stores, you can set 'Restrict to specific domains', and then list which origins you want to allow access.

This is a browser specific layer of protection, a second layer of protection, if you will. The first layer of protection comes from the permissions you set on each database using roles. (For more information, see CouchDB Security)


For more details on configuration, see the Configuring CouchDB section.


This is the interface to the replication system, enabling you to initiate replication between local and remote databases.

You will see two boxes, with 3 boxes in each bigger box.


Depending on how big your screen is, the top (or leftmost) box is the Source database. The bottom (or rightmost) box is the Target database.


From the Source database box, you can choose an existing database from the dropdown, by selecting 'Local' like in the image to the left. Or you can specify a remote database as the Source, by clicking on 'Remote' in that box, and typing in the remote database's address.

In the Target database box, choose either a local or remote database. If you want to create a new database, and replicate into that new DB, check the 'Create Target' button.

For continuous Replications, select the 'continuous' checkbox. 'Continous' means that the target database will update itself whenever the source database is updated, from now on. It will continue to update itself until you cancel the continous replication.

If you are specifying a remote database name, you must specify the full URL of the remote database (including the host, port number and database name). If the remote instance requires authentication, you can specify the username and password as part of the URL, for example http://username:pass@remotehost:5984/demo.

Under the Active Tasks tab, you should see in the table your new created replication. You might miss it if the database being replicated is on the small side, but continous replications will always show up while they are active.

New Interface

We recently released a new version of the replication menu. The first screen shows a list of all replications. From this screen you can, view, delete, filter or create replications.


You can create a new replication by clicking on the green button, which will take you to the new replication form: Replication

For more information, see /_replicate.

For more information on replication, see Replication.


Here you will find helpful online and offline versions of CouchDB Documentation, as well as links to various related links regarding the CouchDB community. If you need to look at this guide again, the link is also here.


Login/User Management

You can change your password, or add admins to your CouchDB instance within this tab. Admin


The Verify Installation allows you to check whether all of the components of your CouchDB installation are correctly installed.




Q: Where can I find answers about CouchDB?

A: Checkout the CouchDB FAQ.

Q: Wow! this is awesome! how can I contribute?

A: Thanks! If you want to contribute, you can open a pull request on Github.

Q: What can I do?

A: Lots of things! checkout our GitHub Issues page for a list of things we need help fixing or building.

Q: I'm not a programmer. What can I do?

A: Good question. There are many things you can do to help out! Find a place that you think needs fixing, and find out how to fix it.

If you have design skills, or would like to learn architecture skills, you can help out by finding a cumbersome or non-intuitive part of CouchDB and/or Fauxton and propose a fix. Good ideas are always welcome :)

Another thing is documentation. We have a lot, but the more the better! If you find a place in CouchDB that is not well-documented, feel free!

Q: I found a bug and I know how to fix it!!

A: Awesome! Open a pull request and we can make that happen!

Helpful Links

CouchDB Homepage (more info is available here!)

How to Install/Setup

Install via npm

CouchDB Documentation

CouchDB Blog Updates Weekly! :)

CouchDB Wiki

CouchDB: The Definitive Guide

CouchDB Tutorials General and Tutorials for Specific Languages

CouchDB IRC Our chat channel

Apache Software Foundation About the ASF