summaryrefslogtreecommitdiff
path: root/doc/services/couchdb.md
blob: cc40dc32713d092a3fbcec6f75095ae650deb5b6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
@title = "couchdb"
@summary = "Data storage for all user data."

Topology
------------------------

Required:

* Nodes with `couchdb` service must also have `soledad` service, if email is enabled.

Suggested:

* Nodes with `couchdb` service communicate heavily with `webapp` and `mx`.

`couchdb` nodes do not need to be reachable from the public internet, although the `soledad` service does require this.

Configuration
----------------------------

### Nighly dumps

You can do a nightly couchdb data dump by adding this to your node config:

    "couch": {
      "backup": true
    }

Data will get dumped to `/var/backups/couchdb`.

### Plain CouchDB

BigCouch is not supported on Platform version 0.8 and higher: only plain CouchDB is possible. For earlier versions, you must do this in order to use plain CouchDB:

    "couch": {
      "master": true,
      "pwhash_alg": "pbkdf2"
    }

Various Tasks
-------------------------------------------------

### Re-enabling blocked account

When a user account gets destroyed from the webapp, there's still a leftover doc in the identities db so other people can't claim that account without an admin's intervention. You can remove this username reservation through the webapp.

However, here is how you could do it manually, if you wanted to:

grep the identities db for the email address:

    curl -s --netrc-file /etc/couchdb/couchdb.netrc -X GET http://127.0.0.1:5984/identities/_all_docs?include_docs=true|grep test_127@bitmask.net

lookup "id" and "rev" to delete the doc:

    curl -s --netrc-file /etc/couchdb/couchdb.netrc -X DELETE 'http://127.0.0.1:5984/identities/b25cf10f935b58088f0d547fca823265?rev=2-715a9beba597a2ab01851676f12c3e4a'

### How to find out which userstore belongs to which identity?

    /usr/bin/curl -s --netrc-file /etc/couchdb/couchdb.netrc '127.0.0.1:5984/identities/_all_docs?include_docs=true' | grep testuser

    {"id":"665e004870ee17aa4c94331ff3ecb173","key":"665e004870ee17aa4c94331ff3ecb173","value":{"rev":"2-2e335a75c4b79a5c2ef5c9950706fe1b"},"doc":{"_id":"665e004870ee17aa4c94331ff3ecb173","_rev":"2-2e335a75c4b79a5c2ef5c9950706fe1b","user_id":"665e004870ee17aa4c94331ff3cd59eb","address":"testuser@example.org","destination":"testuser@example.org","keys": ...

* search for the "user_id" field
* in this example testuser@example.org uses the database user-665e004870ee17aa4c94331ff3cd59eb


### How much disk space is used by a userstore

Beware that this returns the uncompacted disk size (see http://wiki.apache.org/couchdb/Compaction)

    echo "`curl --netrc -s -X GET 'http://127.0.0.1:5984/user-dcd6492d74b90967b6b874100b7dbfcf'|json_pp|grep disk_size|cut -d: -f 2`/1024"|bc


Deprecated BigCouch Tasks
-----------------------------------------

As of release 0.8, the LEAP platform no longer supports BigCouch. This information is kept here for historical reference.

### Rebalance Cluster

Bigcouch currently does not have automatic rebalancing.
It will probably be added after merging into couchdb.
If you add a node, or remove one node from the cluster,

1. make sure you have a backup of all DBs !

1. put the webapp into [[maintenance mode => services/webapp#maintenance-mode]]

1. Stop all services that access the database:

    ```
    workstation$ leap ssh soledad-nodes
    server# /etc/init.d/soledad-server stop

    workstation$ leap ssh mx-node
    server# /etc/init.d/postfix stop
    server# /etc/init.d/leap-mx stop

    workstation$ leap ssh webapp
    server# /etc/init.d/nickserver stop
    ```

    Alternately, you can create a temporary firewall rule to block access (run on couchdb server):

    ```
    server# iptables -A INPUT -p tcp --dport 5984 --jump REJECT
    ```

1. dump the dbs:

    ```
    cd /srv/leap/couchdb/scripts
    time ./couchdb_dumpall.sh
    ```

1. delete all dbs

1. shut down old node

1. check the couchdb members

    ```
    curl -s —netrc-file /etc/couchdb/couchdb.netrc -X GET http://127.0.0.1:5986/nodes/_all_docs
    curl -s —netrc-file /etc/couchdb/couchdb.netrc http://127.0.0.1:5984/_membership
    ```

1. remove bigcouch from all nodes

    ```
    apt-get --purge remove bigcouch
    ```

1. deploy to all couch nodes

    ```
    leap deploy couchdb
    ```

1. most likely, deploy will fail because bigcouch will complain about not all nodes beeing connected. Let the deploy finish, restart the bigcouch service on all nodes and re-deploy:

    ```
    /etc/init.d/bigcouch restart
    ```

1. restore the backup

    ```
    cd /srv/leap/couchdb/scripts
    time ./couchdb_restoreall.sh
    ```

### Migrating from BigCouch to plain CouchDB

<%= render :partial => 'docs/platform/common/bigcouch_migration_begin.md' %>


<%= render :partial => 'docs/platform/common/bigcouch_migration_end.md' %>


<%= render :partial => 'docs/platform/common/bigcouch_migration_finish.md' %>