Fauxton Visual Guide

Fauxton Visual Guide
Fauxton
Visual Guide
GETTING STARTED
USING FAUXTON
ANSWERS
GETTING STARTED
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
USING FAUXTON
00
01 //
ALL DATABASES
ADD A NEW DATABASE
A SINGLE DB (ALL DOCS)
THE EDITOR
DATABASE ACTIONS
02 //
SETUP
03 //
ACTIVE TASKS
04 //
CONFIGURATION
05 //
REPLICATION
06 //
DOCUMENTATION
07 //
LOGIN / ADMIN
08 //
VERIFY
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
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.
Answers
Answers!
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