INTRODUCTION

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.

You can expand or collapse the navigation by clicking icon 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.

Databases

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

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

Search for a Database This text field auto-completes and jumps directly to a specified 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.

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.

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

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

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:

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:

Click the Create Document to save the document.

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.

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

Database Maintenance

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

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

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

Setup

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

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.

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.

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

Configuration

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

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.

Replication

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:

For more information, see /_replicate.

For more information on replication, see Replication.

Documentation

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.

Verify

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