| <!DOCTYPE html><html><head><title>Fauxton Visual Guide</title><link rel="stylesheet" href="https://opensource.keycdn.com/fontawesome/4.7.0/font-awesome.min.css "><link rel="stylesheet" href="main.css"><script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.1/jquery.min.js" integrity="sha256-hVVnYaiADRTO2PzUGmuLJr8BLUSjGIZsDYGmIJLv2b8=" crossorigin="anonymous"></script><script src="js/jquery.visible.min.js"></script><script src="js/main.js"></script></head><body><div id="redsidebar"><div class="header"> <img src="imgs/CouchDB-SVG.svg" class="logo svg"><span class="title">Fauxton<span class="subtitle"> Visual Guide</span></span></div><a href="#getting-started" data-nav="getting-started" class="section getting-started"><div class="large-icon"></div><div class="big-nav-subtitle">GETTING STARTED</div></a><a href="#using-fauxton" data-nav="using-fauxton" class="section using-fauxton"><div class="large-icon"></div><div class="big-nav-subtitle">USING FAUXTON</div></a><a href="#answers" data-nav="answers" class="section answers"><div class="large-icon"></div><div class="big-nav-subtitle">ANSWERS</div></a></div><div id="content" class="showSideBar"><div id="getting-started" class="section shown"><div class="middleBar"><img src="imgs/getting-started-light.png" class="topic-image"><div class="section-title">GETTING STARTED</div></div><div id="rightContent"><div class="intro-section"><h1>Welcome to Fauxton.</h1><div>Apache CouchDB is a database that uses JSON for documents, JavaScript for MapReduce indexes, and regular HTTP for its API.</div><div>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.</div></div><div class="intro-section"><h1>Getting Started</h1><h2>Download</h2><div class="dl-space">Start by downloading the CouchDB suite:</div><div>1. Go to <a href="https://couchdb.apache.org/">couchdb.apache.org</a><span>, and click </span><a href="https://couchdb.apache.org/#download"><img src="imgs/download-btn.png" class="download-btn"></a></div><div>2. Learn how to install and setup CouchDB from <a href="http://docs.couchdb.org/en/latest/install/index.html">here</a><span>, then go to </span><a href="http://127.0.0.1:5984/_utils">http://127.0.0.1:5984/_utils</a></div></div><div id="end-getting-started"></div></div></div><div id="using-fauxton" class="section"><div class="middleBar"><img src="imgs/using-fauxton-light.png" class="topic-image"><div class="section-title">USING FAUXTON</div><div class="fauxton-toc"><div class="icon-menu"><div><a href="#_all_dbs" class="icon-menu-_all_dbs"><i aria-hidden="true" class="fa fa-database"></i></a><div class="line"></div></div><div><a href="#setup" class="icon-menu-setup"><i aria-hidden="true" class="fa fa-wrench"></i></a><div class="line"></div></div><div><a href="#_activetasks" class="icon-menu-_activetasks"><i aria-hidden="true" class="fa fa-tasks"></i></a><div class="line"></div></div><div><a href="#_config" class="icon-menu-_config"><i aria-hidden="true" class="fa fa-cog"></i></a><div class="line"></div></div><div><a href="#replication" class="icon-menu-replication"><img src="imgs/replicate.svg" class="svg replicate-icon"></a><div class="line"></div></div><div><a href="#documentation" class="icon-menu-documentation"><img src="imgs/bookmark.svg" class="svg docs-icon"></a><div class="line"></div></div><div><a href="#login" class="icon-menu-login"><img src="imgs/user.svg" class="svg user-icon"></a><div class="line"></div></div><div><a href="#verifyinstall" class="icon-menu-verifyinstall"><i aria-hidden="true" class="fa fa-check-circle"></i></a></div></div><div class="toc"><a href="#intro" id="toc-intro" class="heading selected"> <div class="heading-title"> <span class="number">00</span><span class="heading-text"></span></div></a><div id="toc-_all_dbs" class="heading"> <a href="#_all_dbs" class="heading-title"> <span class="number">01 // </span><span class="heading-text">ALL DATABASES</span></a><a href="#_all_dbs" id="_all_dbs-sub" class="subheading">ADD A NEW DATABASE</a><a href="#_all_docs" id="_all_docs-sub" class="subheading">A SINGLE DB (ALL DOCS)</a><a href="#editor" id="editor-sub" class="subheading">THE EDITOR</a><a href="#db-action" id="db-actions-sub" class="subheading">DATABASE ACTIONS</a></div><a href="#setup" id="toc-setup" class="heading"><div class="heading-title"> <span class="number">02 // </span><span class="heading-text">SETUP</span></div></a><a href="#_activetasks" id="toc-_activetasks" class="heading"><div class="heading-title"> <span class="number">03 // </span><span class="heading-text">ACTIVE TASKS</span></div></a><a href="#_config" id="toc-_config" class="heading"><div class="heading-title"> <span class="number">04 // </span><span class="heading-text">CONFIGURATION</span></div></a><a href="#replication" id="toc-replication" class="heading"><div class="heading-title"> <span class="number">05 // </span><span class="heading-text">REPLICATION</span></div></a><a href="#documentation" id="toc-documentation" class="heading"> <div class="heading-title"> <span class="number">06 // </span><span class="heading-text">DOCUMENTATION </span></div></a><a href="#login" id="toc-login" class="heading"> <div class="heading-title"> <span class="number">07 // </span><span class="heading-text">LOGIN / ADMIN</span></div></a><a href="#verifyinstall" id="toc-verifyinstall" class="heading"> <div class="heading-title"> <span class="number">08 // </span><span class="heading-text">VERIFY</span></div></a></div></div></div><div id="rightContent"><div class="box"><div id="intro" class="chapter"> <h1 id="introduction">INTRODUCTION</h1> |
| <h2 id="features-overview">Features Overview</h2> |
| <p>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 <a href="https://www.npmjs.com/package/fauxton">Fauxton on npm</a>.</p> |
| <p>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.</p> |
| <p><img src="imgs/screen-shots/start.png" alt="First Start" title="On Startup"></p> |
| <p>You can expand or collapse the navigation by clicking <i aria-hidden="true" class="fa fa-bars"> icon</i> in the top left corner of the page.</p> |
| <p><a href="#_all_dbs">Databases</a> 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.</p> |
| <p><a href="#setup">Setup</a> is a wizard to set up and configure CouchDB clusters or a single node.</p> |
| <p><a href="#_activetasks">Active Tasks</a> 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 <a href="http://docs.couchdb.org/en/latest/api/server/common.html#api-server-active-tasks">Active Tasks API</a> |
| call.</p> |
| <p><a href="#_config">Config</a> 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 |
| <a href="http://docs.couchdb.org/en/latest/config/index.html#config">Configuring CouchDB</a>.</p> |
| <p><a href="#replication">Replication</a> is an interface to the replication |
| system, enabling you to initiate replication between local and remote |
| databases.</p> |
| <p><a href="http://docs.couchdb.org/en/latest/">Documentation</a> |
| will direct you to your local copy of the documentation. The link |
| shown in this guide is to the online version.</p> |
| <p><a href="#login">Login/User Management</a> lets you can change your password, |
| or add administrator to your CouchDB instance.</p> |
| <p><a href="#verifyinstall">Verify</a> verifies your installation and allows you to |
| check whether all of the components of your CouchDB installation are |
| correctly installed.</p> |
| </div><div id="_all_dbs" class="chapter"><h1 id="databases">Databases</h1> |
| <p><strong> Create Database </strong> |
| Click this button on the top bar, and |
| enter the name of the database you want to create. |
| <img src="imgs/screen-shots/createdb.png" alt="Create a database" title="Create a database"></p> |
| <p>Once created, you should see a success message in green at the top of the window: |
| <img src="imgs/screen-shots/successful_create.png" alt="Create DB Sucess" title="Create DB Sucess"></p> |
| <p><strong> Search for a Database </strong> |
| This text field auto-completes and jumps directly to a specified |
| database. |
| <img src="imgs/screen-shots/couchd-search-db.png" alt="Search for a database" title="Search for a DB"></p> |
| <p><strong> View a Database </strong> |
| This link will take to that database's "<a href="#_all_docs">All Docs</a>" |
| 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. |
| <img src="imgs/screen-shots/selectdb.png" alt="Select a DB" title="Select a DB"></p> |
| <h1 id="_all_docs" class="sub">A Single Database<p><strong> All Documents </strong> |
| When you click on the database name, from the Databases page, you will see the <strong>All Docs</strong> page. Here you can create and edit documents, and create and edit views. |
| <img src="imgs/screen-shots/empty_alldocs.png" alt="All Docs" title="All Docs"></p> |
| <p><strong> Create a Document </strong> |
| Click on the plus symbol to open the 'Add new' menu. |
| <img src="imgs/screen-shots/create-doc-menu.png" alt="Create a Doc Menu" title="Create a Doc Menu"></p> |
| <p>This should open a menu that will let you choose what the new document type you would like to create.</p> |
| <p><img src="imgs/screen-shots/create-doc-menu-2.png" alt="Create a Doc Menu" title="Create a Doc Menu"></p> |
| <p>If you click New Doc, you'll be taken to the Fauxton text editor.</p> |
| </h1><h1 id="editor" class="sub">The Editor<p><strong> The Editor </strong> |
| When you first arrive at the editor, you will see: |
| <img src="imgs/screen-shots/editor1.png" alt="Editor" title="Editor"></p> |
| <p>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.</p> |
| <p>You can edit any data for the document before or after creating the document, except for the _id, after it has been created.</p> |
| <p>Adding Data: |
| <img src="imgs/screen-shots/editor2.png" alt="Adding data" title="Adding data"></p> |
| <p>Click the <strong>Create Document</strong> to save the document.</p> |
| <p><img src="imgs/screen-shots/editor3.png" alt="Click Create" title="Click Create Document"></p> |
| <p>After you click <strong>Create Document</strong> 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. |
| <img src="imgs/screen-shots/editor4 |
| .png" alt="Create Document Success" title="Create Document Success"></p> |
| <p>You can click on the <strong> Include Docs </strong> checkbox to see the entire document on this screen. |
| <img src="imgs/screen-shots/editor5.png" alt="Included Docs" title="Include Docs"></p> |
| <p><img src="imgs/screen-shots/editor6.png" alt="Included Docs" title="Include Docs"></p> |
| </h1><h1 id="db-action" class="sub">Database Maintenance<p><strong> DB Maintenance</strong> |
| <img src="imgs/screen-shots/db-admin1.png" alt="DB Admin Menu" title="DB Admin Menu"> |
| This menu will allows you replicate the Database, and as well as delete it. |
| <img src="imgs/screen-shots/db-admin2.png" alt="DB Admin Menu" title="DB Admin Menu"></p> |
| <p><strong> Replication Link </strong> |
| Jump directly to the Replication page for this database. |
| <img src="imgs/screen-shots/jumptoreplicate.png" alt="Replicate a DB" title="Replicate a DB"></p> |
| <p><strong> Permissions Link </strong> |
| Jump directly to the Permissions page for this database. |
| <img src="imgs/screen-shots/jumptopermissions.png" alt="Jump to Permissions" title="Jump to Permissions"></p> |
| </h1></div><div id="setup" class="chapter"><h1 id="setup">Setup</h1> |
| <p>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.</p> |
| <p>You can read more about it in the docs: |
| <a href="https://docs.couchdb.org/en/stable/setup/cluster.html#the-cluster-setup-wizard">Cluster Setup Wizard</a></p> |
| <p><img src="imgs/screen-shots/setup1.png" alt="Setup 1" title="Setup 1"> |
| <img src="imgs/screen-shots/setup2.png" alt="Setup 2" title="Setup 2"></p> |
| <p>You can read more about CouchDB clusters in the docs as well: |
| <a href="http://docs.couchdb.org/en/stable/cluster/index.html">CouchDB Clusters</a></p> |
| </div><div id="_activetasks" class="chapter"><h1 id="active-tasks">Active Tasks</h1> |
| <p><strong> 1 Change Polling Interval </strong> |
| 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. |
| <img src="imgs/screen-shots/activetasks1.png" alt="Active Tasks Polling" title="Active Tasks Polling"></p> |
| <p><strong> 2 API URL </strong> |
| This page is an interface to the |
| <a href="http://docs.couchdb.org/en/latest/api/server/common.html#api-server-active-tasks">Active Tasks API</a> |
| call. You can view or copy the raw JSON by clicking on this button. |
| <img src="imgs/screen-shots/activetasks2.png" alt="Active Tasks API" title="Active Tasks API"></p> |
| <p><strong> 3 Filter </strong> |
| You can filter by the type of task, or search active tasks by |
| database name (either source or target) using these tabs. |
| <img src="imgs/screen-shots/activetasks3.png" alt="Active Tasks Filter" title="Active Tasks Filter"></p> |
| </div><div id="_config" class="chapter"><h1 id="configuration">Configuration</h1> |
| <p>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.</p> |
| <p>In earlier versions, the interface allows you to edit some of the different configurable parameters. </p> |
| <p><img src="imgs/screen-shots/config.png" alt="Config" title="Config"></p> |
| <h1 id="cors">CORS</h1> |
| <p>CORS stands for Cross Origin Resource Sharing. It is a setting that pertains only to browsers.</p> |
| <p>By enabling CORS, you allow other people, from their browsers, to access the data you have stored in your CouchDB databases.</p> |
| <p>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.</p> |
| <p>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!</p> |
| <p>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.</p> |
| <p>By setting, 'All domains', you allow anyone from anywhere to ping your databases, and retrieve information that way.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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 <a href="http://docs.couchdb.org/en/latest/api/database/security.html">CouchDB Security</a>)</p> |
| <p><img src="imgs/screen-shots/cors.png" alt="CORS" title="CORS"></p> |
| <p>For more details on configuration, see the |
| <a href="http://docs.couchdb.org/en/latest/config/index.html#config">Configuring CouchDB</a> |
| section.</p> |
| </div><div id="replication" class="chapter"><h1 id="replication">Replication</h1> |
| <p>This is the interface to the replication system, enabling you to initiate |
| replication between local and remote databases.</p> |
| <p>You will see two boxes, with 3 boxes in each bigger box.</p> |
| <p><img src="imgs/screen-shots/replication1.png" alt="Replication" title="Replication"></p> |
| <p>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.</p> |
| <p><img src="imgs/screen-shots/replcationSourceTarget.png" alt="Replication" title="Replication"></p> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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 |
| <code>http://username:pass@remotehost:5984/demo</code>.</p> |
| <p>Under the <a href="#_activetasks">Active Tasks</a> 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.</p> |
| <p><strong> New Interface </strong></p> |
| <p>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.</p> |
| <p><img src="imgs/screen-shots/replication-list.png" alt="Replication" title="Replication"></p> |
| <p>You can create a new replication by clicking on the green button, which will take you to the new replication form: |
| <img src="imgs/screen-shots/new-replication.png" alt="Replication" title="Replication"></p> |
| <p>For more information, see |
| <a href="http://docs.couchdb.org/en/latest/api/server/common.html#api-server-replicate">/_replicate</a>.</p> |
| <p>For more information on replication, see |
| <a href="http://docs.couchdb.org/en/latest/replication/index.html#replication">Replication</a>.</p> |
| </div><div id="documentation" class="chapter"><h1 id="documentation">Documentation</h1> |
| <p>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.</p> |
| <p><img src="imgs/screen-shots/documentation.png" alt="Documentation" title="Documentation"></p> |
| </div><div id="login" class="chapter"> <h1 id="login-user-management">Login/User Management</h1> |
| <p>You can change your password, or add admins to your CouchDB instance within this tab. |
| <img src="imgs/screen-shots/admin.png" alt="Admin" title="![Documentation](imgs/screen-shots/documentation.png "Documentation"></p> |
| </div><div id="verifyinstall" class="chapter"><h1 id="verify">Verify</h1> |
| <p>The Verify Installation allows you to check whether all of the components of your CouchDB installation are correctly installed.</p> |
| <p><img src="imgs/screen-shots/verify.png" alt="Verify" title="Verify"></p> |
| </div><div id="end-using-fauxton"></div></div></div></div><div id="answers" class="section"><div class="middleBar"> <img src="imgs/answers-light.png" class="topic-image"><div class="section-title">Answers</div></div><div id="rightContent"> <h1>Answers!<p class="question">Q: Where can I find answers about CouchDB?</p><p class="answer">A: Checkout the <a href="http://wiki.apache.org/couchdb/Frequently_asked_questions">CouchDB FAQ</a>.</p><p class="question">Q: Wow! this is awesome! how can I contribute?</p><p class="answer">A: Thanks! If you want to contribute, you can open a pull request |
| on <a href="https://github.com/apache/couchdb-fauxton">Github</a>.</p><p class="question">Q: What can I do?</p><p class="answer">A: Lots of things! checkout our <a href="https://github.com/apache/couchdb-fauxton/issues">GitHub Issues</a> page for a list of things we need help fixing or building.</p><p class="question">Q: I'm not a programmer. What can I do?</p><p class="answer">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. |
| </p><p>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 :)</p> |
| <p>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!</p> |
| <p class="question">Q: I found a bug and I know how to fix it!!</p><p class="answer">A: Awesome! Open a pull request and we can make that happen! |
| </p></h1><h1>Helpful Links<p><a href="https://couchdb.apache.org/">CouchDB Homepage</a> (more info is |
| available here!)</p> |
| <p><a href="http://docs.couchdb.org/en/latest/install/index.html">How to Install/Setup</a></p> |
| <p><a href="https://www.npmjs.com/package/fauxton">Install via npm</a> </p> |
| <p><a href="http://docs.couchdb.org/en/latest/">CouchDB Documentation</a></p> |
| <p><a href="http://blog.couchdb.org/">CouchDB Blog</a> Updates Weekly! :)</p> |
| <p><a href="http://wiki.apache.org/couchdb/">CouchDB Wiki</a></p> |
| <p><a href="http://guide.couchdb.org/index.html">CouchDB: The Definitive Guide</a></p> |
| <p><a href="http://wiki.apache.org/couchdb/Basics">CouchDB Tutorials</a> General and |
| Tutorials for Specific Languages</p> |
| <p><a href="https://web.libera.chat/#couchdb">CouchDB IRC</a> Our chat |
| channel</p> |
| <p><a href="http://www.apache.org/">Apache Software Foundation</a> About the ASF</p> |
| </h1><div id="end-answers"></div></div></div><div id="hamburger" class="showSideBar"><i aria-hidden="true" class="fa fa-bars"></i></div></div></body></html> |
