{"id":13556525,"url":"https://github.com/ermouth/couch-photon","last_synced_at":"2025-04-07T11:10:18.380Z","repository":{"id":47200842,"uuid":"102568704","full_name":"ermouth/couch-photon","owner":"ermouth","description":"An alternative CouchDB admin panel","archived":false,"fork":false,"pushed_at":"2025-03-01T21:06:41.000Z","size":45390,"stargazers_count":89,"open_issues_count":0,"forks_count":12,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-31T10:05:53.744Z","etag":null,"topics":["couch-photon","couchdb"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ermouth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":"ermouth","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2017-09-06T05:58:29.000Z","updated_at":"2025-03-01T21:06:44.000Z","dependencies_parsed_at":"2023-02-10T12:01:25.319Z","dependency_job_id":"1e95f33b-8e33-4575-8d96-36efc76fbdbe","html_url":"https://github.com/ermouth/couch-photon","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermouth%2Fcouch-photon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermouth%2Fcouch-photon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermouth%2Fcouch-photon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermouth%2Fcouch-photon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ermouth","download_url":"https://codeload.github.com/ermouth/couch-photon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640465,"owners_count":20971557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["couch-photon","couchdb"],"created_at":"2024-08-01T12:03:53.487Z","updated_at":"2025-04-07T11:10:18.339Z","avatar_url":"https://github.com/ermouth.png","language":null,"funding_links":["https://patreon.com/ermouth"],"categories":["Others","others"],"sub_categories":[],"readme":"# \u003cimg align=\"right\" src=\"https://cdn.cloudwall.me/photon/photon-github.svg\" /\u003e Couch Photon\nPhoton 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.\n\nBasic Photon features are shown in a short screencast at [youtu.be/M9ptWXfwMN8](https://youtu.be/M9ptWXfwMN8).\n\nPhoton is completely self-contained and is safe for restricted networks. Unless configured [differently](#configuring-access), 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.\n\n## Unique features\n\n* [Group dump to ZIP](#dump-to-zip-and-restore), and also restore\n* Instant search in view results and JSON trees\n* JSON editor with JS syntax and out-of-order undo\n* Group operations with DBs, ACLs, docs and sync tasks\n* View editor with JS, Erlang, Mango and [SQL](#sql-queries) support\n* Node and cluster level stats display and config\n* Document revisions structured diff\n* Local docs list and view\n* Conflicts list\n* Docs purge\n\n## Installation\n\nPhoton installation process is one-step: put `_design/photon` JSON doc into CouchDB. There are 3 ways: [use command line](#install-using-curl), [simply copy/paste](#install-using-copypaste), or use [replication](#install-using-replication).\n\n## Install using curl\n\nFirst, 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.\n\n__For CouchDB 3.0 and earlier:__\n```bash\ncouch=\"http://USER:PASSWORD@127.0.0.1:5984\"; \\\nhead=\"-H Content-Type:application/json\"; \\\ncurl $head -X PUT $couch/photon; curl https://raw.githubusercontent.com/ermouth/couch-photon/master/photon.json | \\\ncurl $head -X PUT $couch/photon/_design/photon -d @- ; curl $head -X PUT $couch/photon/_security -d '{}' ; \\\ncouch=''; head='';\n```\n\n__For CouchDB 3.1+,__ Couch config tuning added.\n```bash\ncouch=\"http://USER:PASSWORD@127.0.0.1:5984\"; \\\nhead=\"-H Content-Type:application/json\"; \\\ncurl $head -X PUT $couch/photon; curl https://raw.githubusercontent.com/ermouth/couch-photon/master/photon.json | \\\ncurl $head -X PUT $couch/photon/_design/photon -d @- ; curl $head -X PUT $couch/photon/_security -d '{}' ; \\\ncurl $head -X PUT $couch/_node/_local/_config/csp/attachments_enable -d '\"false\"' ; \\\ncurl $head -X PUT $couch/_node/_local/_config/chttpd_auth/same_site -d '\"lax\"' ; \\\ncouch=''; head='';\n```\n\nAfter the process is finished, open `http://127.0.0.1:5984/photon/_design/photon/index.html` in your browser. \n\nNext time you can upgrade Photon directly from Photon itself: just click the rightmost button on the navbar, then click `Check for updates` button.\n\n## Install using copy/paste\n\nDownload `photon.json` from [Github](https://raw.githubusercontent.com/ermouth/couch-photon/master/photon.json) or [CloudWall CDN](https://cdn.cloudwall.me/photon/photon.json), and then use one of the following ways:\n\na) 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`.\n\nb) `curl -H Content-Type:application/json -X PUT http://yourdomain.com:5984/photon/_design/photon -d @photon.json`. Run `index.html`.\n\nNext time you can upgrade Photon directly from Photon itself: just click the rightmost button on the navbar, then click `Check for updates` button.\n\n**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`.\n\n## Install using replication\n\nYou 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.\n\n__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.\n```json\n{\n  \"_id\":      \"Photon\",\n  \"source\":   \"https://photon.cloudwall.me/dist-photon\",\n  \"target\":   \"photon\",\n  \"create_target\": true,\n  \"doc_ids\":  [\"_design/photon\"],\n  \"user_ctx\": {\"name\":\"admin\", \"roles\":[\"_admin\"]}\n}\n```\nTo make sure `user_ctx` section works properly, you must have CouchDB proxy auth turned on. By default it’s active in CouchDB 1.x.\n\n__For CouchDB 2+__ JSON is bit different (see below). You need to insert credentials since CouchDB 2+ does not understand `user_ctx` param.\n```json\n{\n  \"_id\":      \"Photon\",\n  \"source\":   \"https://photon.cloudwall.me/dist-photon\",\n  \"target\":   \"http://admin:__________@localhost:5984/photon\",\n  \"create_target\": true,\n  \"doc_ids\":  [\"_design/photon\"]\n}\n```\n\nNext time you can upgrade Photon directly from inside Photon without replication. Just click the rightmost button on the navbar, then click `Check for updates`.\n\n**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`.\n\n## Configuring access\n\nBy 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.\n\nTo preserve settings during Photon update use `Check for updates` button, not replication.\n\n## Dump to ZIP and restore\n\nThe `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.\n\nPhoton 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.\n\nPhoton 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.\n\nActually, any JSON file with an array of docs is ok for `Restore…` dialog – given all docs in the array are valid CouchDB docs.\n\n## CouchDB performance test\n\nPhoton design document includes superficial CouchDB performance test accessible from About tab for users with `_admin` role.\n\nThe 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.\n\n## SQL queries\n\nPhoton 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.\n\nPhoton 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.\n\nSQL command line and stored queries live in viewindices dropdown.\n\n## Dedicated host\n\nPhoton can run as a couchapp on a dedicated domain. To set up Photon for a dedicated host  \njust configure CouchDB properly. First, [set up CORS](https://cloudwall.me/setup_couch#h-16ylld74) \nfor the domain. Then set up two config keys:\n```\n[vhosts] \nphoton.mydomain.xyz = /photon/_design/photon/_rewrite\n[httpd]\nsecure_rewrites = false\n```\nNow typing `photon.mydomain.xyz` in the browser runs Photon.\n\n## FAQ\n\n__Where are source files?__\n\nPhoton 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](https://cloudwall.me/_demo/?pin=\u0026user=demouser#cw/Manifest/!WyJlZGl0IiwiY3ctUGhvdG9uLTFjY2QiXQ--) right in the browser, using CloudWall demo built-in IDE. Left IDE panel has ` ▶︎ ` button that builds and runs Photon in a popup.\n\n__What is underlying technology?__\n\nPhoton 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.\n\n__Is it safe to update Photon from the default CDN?__\n\nBasically, 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.\n\nNote 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.\n\n---\n\n(c) 2025 ermouth. Photon is MIT licensed. Works in all modern browsers. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fermouth%2Fcouch-photon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fermouth%2Fcouch-photon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fermouth%2Fcouch-photon/lists"}