Couch Photon

Photon is an alternative CouchDB admin panel with all standard and a lot of unique features. Photon is a single CouchDB design document with attachments, so it can be installed on any running CouchDB without rebuilding or reconfiguring.

Basic Photon features are shown in a short screencast at youtu.be/M9ptWXfwMN8.

Photon is completely self-contained and is safe for restricted networks. Unless configured differently, users must have _admin or app-photon role to use Photon; this restriction only protects the app, it doesn’t add more security to CouchDB itself.

Unique features

Group dump to ZIP, and also restore
Instant search in view results and JSON trees
JSON editor with JS syntax and out-of-order undo
Group operations with DBs, ACLs, docs and sync tasks
View editor with JS, Erlang, Mango and SQL support
Node and cluster level stats display and config
Document revisions structured diff
Local docs list and view
Conflicts list
Docs purge

Installation

Photon installation process is one-step: put _design/photon JSON doc into CouchDB. There are 3 ways: use command line, simply copy/paste, or use replication.

Install using curl

First, copy the script below into a text editor and provide admin username/password in the first line. Then copy/paste result to the command line and press Enter. The script creates photon bucket, makes the bucket public (an important step if you have CouchDB 3+), downloads Photon ddoc, and puts it into Couch.

For CouchDB 3.0 and earlier:

couch="http://USER:PASSWORD@127.0.0.1:5984"; \
head="-H Content-Type:application/json"; \
curl $head -X PUT $couch/photon; curl https://raw.githubusercontent.com/ermouth/couch-photon/master/photon.json | \
curl $head -X PUT $couch/photon/_design/photon -d @- ; curl $head -X PUT $couch/photon/_security -d '{}' ; \
couch=''; head='';

For CouchDB 3.1+, Couch config tuning added.

couch="http://USER:PASSWORD@127.0.0.1:5984"; \
head="-H Content-Type:application/json"; \
curl $head -X PUT $couch/photon; curl https://raw.githubusercontent.com/ermouth/couch-photon/master/photon.json | \
curl $head -X PUT $couch/photon/_design/photon -d @- ; curl $head -X PUT $couch/photon/_security -d '{}' ; \
curl $head -X PUT $couch/_node/_local/_config/csp/attachments_enable -d '"false"' ; \
curl $head -X PUT $couch/_node/_local/_config/chttpd_auth/same_site -d '"lax"' ; \
couch=''; head='';

After the process is finished, open http://127.0.0.1:5984/photon/_design/photon/index.html in your browser.

Next time you can upgrade Photon directly from Photon itself: just click the rightmost button on the navbar, then click Check for updates button.

Install using copy/paste

Download photon.json from Github or CloudWall CDN, and then use one of the following ways:

a) Open JSON in any text editor. Create a doc in any CouchDB bucket, using Futon or Fauxton. Copy-paste JSON text into it. Save. Run index.html attachment by clicking it in Futon or Fauxton, or directly typing smth like yourcouchdomain.xyz/photon/_design/photon/index.html.

b) curl -H Content-Type:application/json -X PUT http://yourdomain.com:5984/photon/_design/photon -d @photon.json. Run index.html.

Next time you can upgrade Photon directly from Photon itself: just click the rightmost button on the navbar, then click Check for updates button.

For CouchDB 3.x: you should explicitly make photon DB public to run Photon. For 3.1+ you also need to set csp/attachments_enable config key to false, and chttpd_auth/same_site to lax.

Install using replication

You can install Photon using native CouchDB replication. Since the DB you will replicate from has very limited capacity, please only replicate once, do not make sync continuous.

For CouchDB 1.7.2 and earlier. Create a new doc in your _replicator DB and copy-paste below JSON into it. Save – and you are done.

{
  "_id":      "Photon",
  "source":   "https://photon.cloudwall.me/dist-photon",
  "target":   "photon",
  "create_target": true,
  "doc_ids":  ["_design/photon"],
  "user_ctx": {"name":"admin", "roles":["_admin"]}
}

To make sure user_ctx section works properly, you must have CouchDB proxy auth turned on. By default it’s active in CouchDB 1.x.

For CouchDB 2+ JSON is bit different (see below). You need to insert credentials since CouchDB 2+ does not understand user_ctx param.

{
  "_id":      "Photon",
  "source":   "https://photon.cloudwall.me/dist-photon",
  "target":   "http://admin:__________@localhost:5984/photon",
  "create_target": true,
  "doc_ids":  ["_design/photon"]
}

Next time you can upgrade Photon directly from inside Photon without replication. Just click the rightmost button on the navbar, then click Check for updates.

For CouchDB 3.x: you should explicitly make photon DB public to run Photon. For 3.1+ you also need to set csp/attachments_enable config key to false, and chttpd_auth/same_site to lax.

Configuring access

By default, Photon only starts if a user has _admin or app-photon role. Allowed roles are listed in .settings.roles array of the Photon design document. You can edit the array, save ddoc and reload Photon. Making the list empty allows any user to run Photon.

To preserve settings during Photon update use Check for updates button, not replication.

Dump to ZIP and restore

The Zip…/Restore… dialog manages DB dump/restore process. Photon can dump several DBs into one archive file, and later restore them, in full or in part, under the original or different names. In most modern browsers in safe environment (https) Photon uses streaming and can handle gigabytes of data without stalling.

Photon can also backup a subset of selected DB documents, as a partial DB dump. Also any single document with attachments can be downloaded as ZIP, with all attachments as separate files. Download button is available in doc JSON editor.

Photon is also able to restore a DB from a full dump of _changes or _all_docs provided the dump is stored as a .json, and also has all attachments base64 data in place, if any.

Actually, any JSON file with an array of docs is ok for Restore… dialog – given all docs in the array are valid CouchDB docs.

CouchDB performance test

Photon design document includes superficial CouchDB performance test accessible from About tab for users with _admin role.

The test provides good insights how q,n cluster params impact performance. Also, the test shows JS query server costs, and how QS performance depends on sharding options.

SQL queries

Photon supports a subset of SQL for querying CouchDB, SQL expressions are translated into Mango client-side. Only features allowed by Mango are supported, particularly – no joins are allowed and ordering is limited. Anyway, even a subset of SQL is very handy and concise.

Photon understands RegExps passed in MySQL style: WHERE field RLIKE '^a[bc]$'. Case-insensitive equivalent is RLIKE '(?i)^a[bc]$'. Both LIKE and ILIKE are also supported. All queries of that sort invoke full bucket scan, they never use full-text index even if one is present.

SQL command line and stored queries live in viewindices dropdown.

Dedicated host

Photon can run as a couchapp on a dedicated domain. To set up Photon for a dedicated host
just configure CouchDB properly. First, set up CORS for the domain. Then set up two config keys:

[vhosts] 
photon.mydomain.xyz = /photon/_design/photon/_rewrite
[httpd]
secure_rewrites = false

Now typing photon.mydomain.xyz in the browser runs Photon.

FAQ

Where are source files?

Photon never existed as source files, its sources are CouchDB docs. Photon is developed and built using specialized dev environment, CloudWall. You can explore Photon source code right in the browser, using CloudWall demo built-in IDE. Left IDE panel has ▶︎ button that builds and runs Photon in a popup.

What is underlying technology?

Photon employs conservative and bullet-proof approaches whenever possible: mostly ES5 sources, jQuery plus established plugins to render UI, XMLHttpRequest to interact with CouchDB, no corporate OSS libs. The only exception is the ZIP processor, it requires modern browser technologies to work with decent speed, or to work at all.

Is it safe to update Photon from the default CDN?

Basically, CloudWall CDN is the “source of truth” for all other places where latest stable version of Photon is available. Default CDN has very superficial logging, however if you are concerned about your node IP is logged during update, you always can download Photon json from Github manually.

Note that updates are always explicit and are never performed until you click the update button. Time to time update reminder never makes any requests to check for new version, it’s just a timer.

ermouth / couch-photon

readme