This is an automated email from the ASF dual-hosted git repository.
wohali pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/couchdb-docker.git
The following commit(s) were added to refs/heads/master by this push:
new fd69b25 Improve README for configuration changes, closes #47
fd69b25 is described below
commit fd69b2576be3409fca4fef29e8d16204cc5a9e39
Author: Joan Touzet <jo...@atypical.net>
AuthorDate: Wed Jan 31 14:38:57 2018 -0500
Improve README for configuration changes, closes #47
---
README.md | 43 ++++++++++++++++++++++++++++++++-----------
1 file changed, 32 insertions(+), 11 deletions(-)
diff --git a/README.md b/README.md
index 8de242c..aa066c1 100644
--- a/README.md
+++ b/README.md
@@ -23,27 +23,48 @@ If you're looking for a CouchDB with SSL support you can
check out [klaemo/couch
## Run (latest/2.1.1)
Available on the docker registry as
[apache/couchdb:latest](https://hub.docker.com/r/apache/couchdb/).
-This is a build of the CouchDB 2.1 release. A data volume
-is exposed on `/opt/couchdb/data`, and the node's port is exposed on `5984`.
+This is a build of the CouchDB 2.1 release.
-Please note that CouchDB no longer autocreates system tables for you, so you
will
-have to create `_global_changes`, `_metadata`, `_replicator` and `_users`
manually (the admin interface has a "Setup" menu that does this for you).
-The node will also start in [admin party
mode](http://guide.couchdb.org/draft/security.html#party)!
+By default, CouchDB's HTTP interface is exposed on port `5984`. Once running,
you can visit the new admin interface at `http://<dockerhost>:5984/_utils/`
+
+CouchDB uses `/opt/couchdb/data` to store its data, and is exposed as a volume.
+
+Here is an example launch line for a single-node CouchDB with an admin
username and password of `admin` and `password`, exposed to the world on port
`5984`:
```bash
-# expose it to the world on port 5984 and use your current directory as the
CouchDB Database directory
-[sudo] docker run -p 5984:5984 -v $(pwd):/opt/couchdb/data apache/couchdb
+$ docker run -p 5984:5984 --volume ~/data:/opt/couchdb/data --volume
~/etc/local.d:/opt/couchdb/etc/local.d --env COUCHDB_USER=admin --env
COUCHDB_PASSWORD=password apache/couchdb:2.1.1
18:54:48.780 [info] Application lager started on node nonode@nohost
18:54:48.780 [info] Application couch_log_lager started on node nonode@nohost
18:54:48.780 [info] Application couch_mrview started on node nonode@nohost
18:54:48.780 [info] Application couch_plugins started on node nonode@nohost
-[...]
```
-Note that you can also use the NODENAME environment variable to set the name
of the CouchDB node inside the container.
-Once running, you can visit the new admin interface at
`http://dockerhost:5984/_utils/`
+### Detailed configuration (latest/2.x)
+
+CouchDB uses `/opt/couchdb/etc/local.d` to store its configuration. It is
highly recommended to bind map this to an external directory, to persist the
configuration across restarts.
+
+CouchDB also uses `/opt/couchdb/etc/vm.args` to store Erlang runtime-specific
changes. Changing these values is less common. If you need to change the epmd
port, for instance, you will want to bind mount this file as well. (Note: files
cannot be bind-mounted on Windows hosts.)
+
+In addition, a few environment variables are provided to set very common
parameters:
+
+* `COUCHDB_USER` and `COUCHDB_PASSWORD` will create an ini-file based local
admin user with the given username and password in the file
`/opt/couchdb/etc/local.d/docker.ini`.
+* `COUCHDB_SECRET` will set the CouchDB shared cluster secret value, in the
file `/opt/couchdb/etc/local.d/docker.ini`.
+* `NODENAME` will set the name of the CouchDB node inside the container to
`couchdb@${NODENAME}`, in the file `/opt/couchdb/etc/vm.args`. This is used for
clustering purposes and can be ignored for single-node setups.
+
+If other configuration settings are desired, externally mount
`/opt/couchdb/etc` and provide `.ini` configuration files under the
`/opt/couchdb/etc/local.d` directory.
+
+### Important notes (latest/2.x)
+
+Please note that CouchDB no longer autocreates system databases for you. This
is intentional; multi-node CouchDB deployments must be joined into a cluster
before creating these databases.
+
+You must create `_global_changes`, `_metadata`, `_replicator` and `_users`
after the cluster has been fully configured. (The Fauxton UI has a "Setup"
wizard that does this for you.)
+
+The node will also start in [admin party
mode](http://guide.couchdb.org/draft/security.html#party)!
+
+[...]
+```
-Note also that port 5986 is not exposed, as this can present *significant*
security risks. We recommend either connecting to the node directly to access
this port, via `docker exec -it <instance> /bin/bash` and accessing port 5986,
or use of `--expose 5986` when launching the container, but **ONLY** if you do
not expose this port publicly.
+Note also that port 5986 is not exposed, as this can present *significant*
security risks. We recommend either connecting to the node directly to access
this port, via `docker exec -it <instance> /bin/bash` and accessing port 5986,
or use of `--expose 5986` when launching the container, but **ONLY** if you do
not expose this port publicly. Port 5986 is scheduled to be removed with the
3.x release series.
## Run (1.7.1)
--
To stop receiving notification emails like this one, please contact
woh...@apache.org.
