Skip to content
Permalink
Browse files
snap file rework by @sklassen (#27)
snap improvements;

* Split the DATA directory into log and etc; added vm.args; coded snap configuration hook for name and setcookie; bumped version number to 2.2; and added a description how to install and set options

* Moved snap.ini into local.d; configure now can manage both vm.args and (small subset of) local.d/*.ini; snap does not touch local.ini, so as not to interfer with web configuration interface; Reverted root README.md and added snap/README.md

* Removed the log directory as default writer=stderr is best

* Removed unrequired home plug in for hooks

* Empty rather than Nil plug-ins

* Renamed common subdirectory 2.x

* Removed hooks from snacraft.yaml: no special plugs needed

* Update README.md

* Single data directory suffices

* Unified data and index directory

* Removed user name from snap name

* Expanded the Snap Configuration

* Removed erlang from snapcraft; snap now 70M smaller

* prepare and build have been replaced by single override-build

* Added back explicit essential packages; excluded share/doc

* Added a HOWTO file

* Tidy up the md

* Added new line
  • Loading branch information
sklassen authored and wohali committed Nov 2, 2018
1 parent 148c4ba commit 2c63fe067a7f5e52e216d4870cfcb724b423b6db
Showing 10 changed files with 394 additions and 40 deletions.
@@ -16,7 +16,7 @@ repo/dists
repo/pool
pkgs/
couchdb/
couchdb_2.0_amd64.snap
couchdb_*.snap
parts/
prime/
snap/.snapcraft/
@@ -55,3 +55,4 @@ with issue reporting or contributing to the upkeep of this project.
[1]: http://mail-archives.apache.org/mod_mbox/couchdb-user/
[2]: http://mail-archives.apache.org/mod_mbox/couchdb-dev/
[3]: https://github.com/apache/couchdb/blob/master/CONTRIBUTING.md

@@ -0,0 +1,109 @@
# HOW TO install a cluster using snap

# Create three machines

In the instruction below, we are going to set up a three -- the miniumn number needed to gain performace improvement -- Couch cluster database. In this potted example we will be using LXD.

We launch a new container and install couchdb on one machine

1. localhost> `lxc launch ubuntu:18.04 couchdb-c1`
1. localhost> `lxc exec couchdb-c1 bash`
1. couchdb-c1> `apt update`
1. couchdb-c1> `snap install couchdb`
1. couchdb-c1> `logout`

Here we use LXD copy function to speed up the test
```
lxc copy couchdb-c1 couchdb-c2
lxc copy couchdb-c1 couchdb-c3
lxc copy couchdb-c1 cdb-backup
lxc start couchdb-c2
lxc start couchdb-c3
lxc start cdb-backup
```

# Configure CouchDB (using the snap tool)

We are going to need the IP addresses. You can find them here.
```
lxc list
```

Now lets use the snap configuration tool to set the configuration files.
```
lxc exec couchdb-c1 snap set couchdb name=couchdb@10.210.199.199 setcookie=monster admin=password bind-address=0.0.0.0
lxc exec couchdb-c2 snap set couchdb name=couchdb@10.210.199.254 setcookie=monster admin=password bind-address=0.0.0.0
lxc exec couchdb-c3 snap set couchdb name=couchdb@10.210.199.24 setcookie=monster admin=password bind-address=0.0.0.0
```
The backup machine we will leave as a single instance and no sharding.
```
lxc exec cdb-backup snap set couchdb name=couchdb@127.0.0.1 setcookie=monster admin=password bind-address=0.0.0.0 n=1 q=1
```

The snap must be restarted for the new configurations to take affect.
```
lxc exec couchdb-c1 snap restart couchdb
lxc exec couchdb-c2 snap restart couchdb
lxc exec couchdb-c3 snap restart couchdb
lxc exec cdb-backup snap restart couchdb
```
The configuration files are stored here.
```
lxc exec cdb-backup cat /var/snap/couchdb/current/etc/vm.args
lxc exec cdb-backup cat /var/snap/couchdb/current/etc/local.d/*
```
Any changes to couchdb from the http configutation tool are made here
```
lxc exec cdb-backup cat /var/snap/couchdb/current/etc/local.d/local.ini
```

# Configure CouchDB Cluster (using the http interface)

Now we set up the cluster via the http front-end. This only needs to be run once on the first machine. The last command syncs with the other nodes and creates the standard databases.
```
curl -X POST -H "Content-Type: application/json" http://admin:password@10.210.199.199:5984/_cluster_setup -d '{"action": "add_node", "host":"10.210.199.254", "port": "5984", "username": "admin", "password":"password"}'
curl -X POST -H "Content-Type: application/json" http://admin:password@10.210.199.199:5984/_cluster_setup -d '{"action": "add_node", "host":"10.210.199.24", "port": "5984", "username": "admin", "password":"password"}'
curl -X POST -H "Content-Type: application/json" http://admin:password@10.210.199.199:5984/_cluster_setup -d '{"action": "finish_cluster"}'
```
Now we have a functioning three node cluster.

# An Example Database

Let's create an example database ...
```
curl -X PUT http://admin:password@10.210.199.199:5984/example
curl -X PUT http://admin:password@10.210.199.199:5984/example/aaa -d '{"test":1}' -H "Content-Type: application/json"
curl -X PUT http://admin:password@10.210.199.199:5984/example/aab -d '{"test":2}' -H "Content-Type: application/json"
curl -X PUT http://admin:password@10.210.199.199:5984/example/aac -d '{"test":3}' -H "Content-Type: application/json"
```
... And see that it is sync'd accross the three nodes.
```
curl -X GET http://admin:password@10.210.199.199:5984/example/_all_docs
curl -X GET http://admin:password@10.210.199.254:5984/example/_all_docs
curl -X GET http://admin:password@10.210.199.24:5984/example/_all_docs
```
# Backing Up CouchDB

Our back up server is on 10.210.199.242. We will manually replicate this from one (anyone) of the nodes.
```
curl -X POST http://admin:password@10.210.199.242:5984/_replicate -d '{"source":"http://10.210.199.199:5984/example", "target":"example", "continuous":false,"create_target":true}' -H "Content-Type: application/json"
curl -X GET http://admin:password@10.210.199.242:5984/example/_all_docs
```
The data store for the clusters nodes are sharded
```
lxc exec couchdb-c1 ls /var/snap/couchdb/common/2.x/data/shards/
```

The backup database is a single file.
```
lxc exec cdb-backup ls /var/snap/couchdb/common/2.x/data/shards/00000000-ffffffff/
```

# Monitoring CouchDB

The logs, by default, are captured by journald
```
lxc exec couchdb-c1 bash
journalctl -u snap.couchdb -f
```

@@ -0,0 +1,61 @@
# Building snaps

## Prerequisites

CouchDB requires Ubuntu 16.04. If building on 18.04, then LXD might be useful.

1. `lxc launch ubuntu:16.04 couchdb-pkg`
1. `lxc exec couchdb-pkg bash`
1. `sudo apt update`
1. `sudo apt install snapd snapcraft`

1. `git clone https://github.com/couchdb/couchdb-pkg.git`
1. `cd couchdb-pkg`

## How to do it

1. Edit `snap/snapcraft.yaml` to point to the correct tag (e.g. `2.2.0`)
1. `snapcraft`

# Snap Instalation

You may need to pull the LXD file to the host system.

$ lxc file pull couchdb-pkg/root/couchdb-pkg/couchdb_2.2.0_amd64.snap /tmp/couchdb_2.2.0_amd64.snap

The self crafted snap will need to be installed in devmode

$ sudo snap install /tmp/couchdb_2.2.0_amd64.snap --devmode

# Snap Configuration

There are two levels of erlang and couchdb configuration hierarchy.

The default layer is stored in /snap/couchdb/current/rel/couchdb/etc/ and is read only.
The user override layer, is stored in /var/snap/couchdb/current/etc/ and is writable.
Within this second layer, configurations are set with the local.d directory (one file
per section) or the local.ini (co-mingled). The "snap set" command works with the
former (local.d) and couchdb http configuration overwrites the latter (local.ini).
Entries in local.ini supersede those in the local.d directory.

The name of the erlang process and the security cookie used is set in vm.args file.
This can be set through the snap native configuration. For example, when setting up
a cluster over several machines the convention is to set the erlang
name to couchdb@your.ip.address. Both erlang and couchdb configuration changes can be
made at the same time.

$ sudo snap set couchdb name=couchdb@216.3.128.12 setcookie=cutter admin=Be1stDB bind-address=0.0.0.0

Snap set variable can not contain underscore character, but any dashes are converted to underscore when
writing to file. Wrap double quotes around any bracets and avoid spaces.

$ sudo snap set couchdb delayed-commits=true erlang="{couch_native_process,start_link,[]}"

Snap Native Configuration changes only come into effect after a restart

$ sudo snap restart couchdb

# Example Cluster

See the HOWTO.md file to see an example of a three node cluster.

@@ -0,0 +1,3 @@
[couchdb]
database_dir = /var/snap/couchdb/common/data
view_index_dir = /var/snap/couchdb/common/data
@@ -0,0 +1,178 @@
#!/bin/sh

set -e

VM_ARGS=$SNAP_DATA/etc/vm.args
LOCAL_DIR=$SNAP_DATA/etc/local.d


## add or replace for the vm.arg file
_modify_vm_args() {
opt=$1
value="$2"
replace_line="-$opt $value"
if $(grep -q "^-$opt " $VM_ARGS); then
sed "s/^-$opt .*/$replace_line/" $VM_ARGS 2>/dev/null >${VM_ARGS}.new
mv -f ${VM_ARGS}.new $VM_ARGS 2>/dev/null
else
echo $replace_line >> $VM_ARGS
fi
}

_modify_ini_file() {
section=$1
opt=`echo $2 | tr "-" "_"`
value="$3"
config_file=${LOCAL_DIR}/${section}.ini
if [ ! -e ${config_file} ]; then
echo "[${section}]" > $config_file
fi
replace_line="$opt=$value"
if $(grep -q "^$opt=" $config_file); then
sed "s/^$opt=.*/$replace_line/" $config_file 2>/dev/null >${config_file}.new
mv -f ${config_file}.new ${config_file} 2>/dev/null
else
echo $replace_line >> $config_file
fi
}

# The vm_args file can only be changed from the filesystem
# configutaion vm.args file

VM_ARGS_OPTIONS="name setcookie"
for key in $VM_ARGS_OPTIONS
do
val=$(snapctl get $key)
if [ ! -z "$val" ]; then
_modify_vm_args $key $val
sleep 0.125
fi
done

# The following list is either those fields that are whitelisted but
# useful to modifiy before first run; or those fields blacklisted
# The snap set command modifies the files in local.d; any changes
# via the URL are reflected in local.ini

# Special Cases

# local.d/admins.ini
passwd=$(snapctl get admin)
if [ ! -z "$passwd" ]; then
_modify_ini_file admins admin $passwd
chmod 600 $SNAP_DATA/etc/local.d/admins.ini
sleep 0.125
fi

# local.d/ssl.ini
port=$(snapctl get ssl-port)
if [ ! -z "$port" ]; then
_modify_ini_file ssl port $port
sleep 0.125
fi

# local.d/httpd.ini
port=$(snapctl get httpd-port)
if [ ! -z "$port" ]; then
_modify_ini_file httpd port $port
sleep 0.125
fi

# local.d/chttpd.ini
port=$(snapctl get chttpd-port)
if [ ! -z "$port" ]; then
_modify_ini_file chttpd port $port
sleep 0.125
fi

# Generic Cases

# local.d/chttpd.ini
CHTTPD_OPTIONS="port bind-address require-valid-user"
for key in $CHTTPD_OPTIONS
do
val=$(snapctl get $key)
if [ ! -z "$val" ]; then
_modify_ini_file chttpd $key $val
sleep 0.125
fi
done

# local.d/cluster.ini
CLUSTER_OPTIONS="n q"
for key in $CLUSTER_OPTIONS
do
val=$(snapctl get $key)
if [ ! -z "$val" ]; then
_modify_ini_file cluster $key $val
sleep 0.125
fi
done

# local.d/compaction_daemon.ini
COMPACTION_DAEMON_OPTIONS="check-interval"
for key in $COMPACTION_DAEMON_OPTIONS
do
val=$(snapctl get $key)
if [ ! -z "$val" ]; then
_modify_ini_file compaction_daemon $key $val
sleep 0.125
fi
done

# local.d/couchdb.ini
COUCHDB_OPTIONS="database-dir view-index-dir delayed-commits"
for key in $COUCHDB_OPTIONS
do
val=$(snapctl get $key)
if [ ! -z "$val" ]; then
_modify_ini_file couchdb $key $val
sleep 0.125
fi
done

# local.d/log.ini
LOG_OPTIONS="writer file level"
for key in $LOG_OPTIONS
do
val=$(snapctl get $key)
if [ ! -z "$val" ]; then
_modify_ini_file log $key $val
sleep 0.125
fi
done

# local.d/native_query_servers.ini
NATIVE_QUERY_SERVERS_OPTIONS="query erlang"
for key in $NATIVE_QUERY_SERVERS_OPTIONS
do
val=$(snapctl get $key)
if [ ! -z "$val" ]; then
_modify_ini_file native_query_servers $key $val
sleep 0.125
fi
done

# local.d/couch_peruser.ini
COUCH_PERUSER_OPTIONS="database-prefix delete-dbs enable"
for key in $COUCH_PERUSER_OPTIONS
do
val=$(snapctl get $key)
if [ ! -z "$val" ]; then
_modify_ini_file couch_peruser $key $val
sleep 0.125
fi
done

# local.d/uuids.ini
UUIDS_OPTIONS="algorithm max-count"
for key in $UUIDS_OPTIONS
do
val=$(snapctl get $key)
if [ ! -z "$val" ]; then
_modify_ini_file uuids $key $val
sleep 0.125
fi
done


@@ -0,0 +1,9 @@
#!/bin/sh

mkdir -p ${SNAP_DATA}/etc/local.d

cp ${SNAP}/rel/couchdb/etc/vm.args ${SNAP_DATA}/etc/vm.args

cp ${SNAP}/rel/couchdb/etc/local.d/*.ini ${SNAP_DATA}/etc/local.d


This file was deleted.

0 comments on commit 2c63fe0

Please sign in to comment.