CouchDB : installation sur Ubuntu

Apache CouchDB est une base de données orientée documents JSON, pilotée par une API HTTP : toute l’administration se fait avec curl ou avec l’interface web Fauxton. Ce guide l’installe sur Ubuntu 24.04 et 26.04 et se limite à l’usage en ligne de commande. Les exemples utilisent des noms génériques (boutique, app).

Origine du paquet

CouchDB n’est pas fourni par les dépôts d’Ubuntu : il s’installe depuis le dépôt APT officiel du projet Apache (paquet couchdb), qui embarque ses propres composants (dont Erlang). Une alternative est le paquet snap (sudo snap install couchdb), dont le fonctionnement diffère (chemins et configuration dans le dossier du snap) : ce guide décrit le paquet APT.

Ajouter le dépôt et installer

sudo apt update
sudo apt install -y curl apt-transport-https gnupg
curl https://couchdb.apache.org/repo/keys.asc | gpg --dearmor | sudo tee /usr/share/keyrings/couchdb-archive-keyring.gpg >/dev/null
. /etc/os-release
echo "deb [signed-by=/usr/share/keyrings/couchdb-archive-keyring.gpg] https://apache.jfrog.io/artifactory/couchdb-deb/ ${VERSION_CODENAME} main" \
  | sudo tee /etc/apt/sources.list.d/couchdb.list >/dev/null
sudo apt update
apt policy couchdb

apt policy couchdb doit afficher un candidat venant du dépôt Apache. S’il n’affiche rien, le dépôt ne propose pas encore de paquet pour le nom de code de la version d’Ubuntu utilisée (echo $VERSION_CODENAME) : consulter la page d’installation officielle de CouchDB pour les distributions prises en charge.

sudo apt install couchdb

L’installation pose des questions (configuration debconf) :

Question	Réponse conseillée
Type d’installation	`standalone` (serveur unique)
Cookie Erlang	Utile seulement en grappe (cluster) : une valeur aléatoire
Adresse d’écoute	`127.0.0.1` (accès local uniquement)
Mot de passe de l’administrateur `admin`	Un mot de passe long et unique

Les réponses se retrouvent dans /opt/couchdb/etc/local.d/.

Premier contrôle

sudo systemctl status couchdb
sudo systemctl enable --now couchdb
curl http://127.0.0.1:5984/
curl http://127.0.0.1:5984/_up

{"couchdb":"Welcome","version":"3.5.0","git_sha":"…","uuid":"…","features":["access-ready","partitioned","pluggable-storage-engines","reshard","scheduler"],"vendor":{"name":"The Apache Software Foundation"}}

Le serveur répond en JSON ; /_up renvoie {"status":"ok"} quand il est prêt.

Authentification

Depuis CouchDB 3.0, un compte administrateur est obligatoire : les routes d’administration et de création de bases refusent l’accès anonyme.

curl -u admin http://127.0.0.1:5984/_all_dbs        # mot de passe demandé
curl -u admin http://127.0.0.1:5984/_membership

Éviter -u admin:MOTDEPASSE : le mot de passe apparaîtrait dans l’historique et la liste des processus. Pour des scripts, un fichier ~/.netrc protégé :

machine 127.0.0.1
login admin
password <mot-de-passe-de-l-administrateur>

chmod 600 ~/.netrc
curl -n http://127.0.0.1:5984/_all_dbs

Bases système

En mode autonome, CouchDB crée les bases _users (comptes), _replicator (réplications permanentes) et _global_changes. Vérifier :

curl -n http://127.0.0.1:5984/_all_dbs

Si _users et _replicator manquent (installation incomplète), les créer :

curl -n -X PUT http://127.0.0.1:5984/_users
curl -n -X PUT http://127.0.0.1:5984/_replicator

Interface web : Fauxton

Fauxton est servi sur http://127.0.0.1:5984/_utils. Sur un serveur distant, y accéder par un tunnel SSH :

ssh -N -L 5984:127.0.0.1:5984 utilisateur@serveur.exemple.com

puis ouvrir http://127.0.0.1:5984/_utils dans le navigateur local (voir SSH : tunnels).

Fichiers et dossiers

Chemin	Rôle
`/opt/couchdb/etc/local.ini`	Configuration locale (modifiée par l’API de configuration)
`/opt/couchdb/etc/local.d/*.ini`	Fragments de configuration
`/opt/couchdb/etc/default.ini`	Valeurs par défaut (ne pas modifier)
`/opt/couchdb/data/`	Données (fichiers `.couch`)
`/var/log/couchdb/couchdb.log`	Journal

Après une modification de fichier :

sudo systemctl restart couchdb

Lire ou modifier un réglage par l’API (sans redémarrage) :

curl -n http://127.0.0.1:5984/_node/_local/_config/chttpd/bind_address
curl -n -X PUT http://127.0.0.1:5984/_node/_local/_config/couchdb/max_document_size -d '"8000000"'

Sécurité de base

Garder bind_address = 127.0.0.1 tant que l’accès distant n’est pas nécessaire.
Pour un accès distant, passer par un reverse proxy HTTPS ou un tunnel SSH, jamais le port 5984 ouvert à Internet (voir Utilisateurs et droits).
Un mot de passe administrateur fort, jamais dans un dépôt de code.

sudo ss -tlnp | grep 5984          # 127.0.0.1:5984 attendu

Mise à jour et désinstallation

sudo apt update && sudo apt upgrade
sudo apt purge couchdb

Dépannage

Symptôme	Piste
`{"error":"unauthorized","reason":"Authentication required."}`	Passer un compte (`-u admin` ou `-n`)
`curl: (7) Failed to connect`	Service arrêté (`systemctl status couchdb`) ou mauvaise adresse
Le service ne démarre pas	`sudo journalctl -u couchdb -n 50`, `/var/log/couchdb/couchdb.log`
`E: Unable to locate package couchdb`	Dépôt Apache non ajouté ou non pris en charge pour ce nom de code : `apt policy couchdb`
Erreur de signature du dépôt	Clé absente : refaire l’import de `keys.asc` dans `/usr/share/keyrings/`
`_users` introuvable	Créer les bases système (voir plus haut)

Ubuntu 24.04 et 26.04 : différences à connaître

La procédure est la même : seul le nom de code du dépôt change (noble pour 24.04, celui de 26.04 pour la suivante). Vérifier avec apt policy couchdb que le dépôt Apache fournit un paquet pour la version utilisée avant de poursuivre.

Pour aller plus loin

Documentation : docs.couchdb.org
Suite : Utilisation en console