Many developers face this frustrating scenario: CouchDB works perfectly via localhost but remains inaccessible from external machines. Let's break down the complete solution based on an Ubuntu 9.04 server case (though these principles apply to most Linux distributions).

First, verify how CouchDB is binding to network interfaces:

netstat -tulnp | grep 5984
# Expected output when properly configured:
# tcp6   0   0 :::5984   :::*    LISTEN   1234/couchdb

If you only see 127.0.0.1:5984, your binding configuration needs adjustment.

For modern CouchDB installations (1.6+), edit the local.ini file:

sudo nano /etc/couchdb/local.ini

Add or modify these settings under the [httpd] section:

[httpd]
bind_address = 0.0.0.0
port = 5984

Ubuntu's init scripts can sometimes fail to properly restart services. Here's a reliable way to ensure complete restart:

sudo service couchdb stop
sudo pkill -9 couchdb  # Force kill any remaining processes
sudo service couchdb start

A more robust iptables approach than simply adding a rule:

sudo iptables -I INPUT 1 -p tcp --dport 5984 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables.rules

From a remote machine, test with curl:

curl -v http://your-server-ip:5984/
# Should return something like:
# {"couchdb":"Welcome","version":"2.3.1","features":[...]}

If using systemd, create an override file:

sudo systemctl edit couchdb

Add these directives:

[Service]
Environment=ERL_FLAGS="-kernel inet_dist_listen_min 9100 -kernel inet_dist_listen_max 9100"

When troubleshooting, always verify:

• CouchDB process actually restarted (check PID changes)
• No SELinux/AppArmor restrictions (check /var/log/auth.log)
• Network routes exist (traceroute your-server-ip)
• No conflicting applications using port 5984

---

When I first installed CouchDB on Ubuntu 9.04 using:

sudo aptitude install couchdb

Everything seemed to work fine locally. Testing with:

telnet localhost 5984

showed successful connections. But attempts from external machines resulted in "connection reset" errors.

First, I checked the basic network configuration:

# Verify listening ports
netstat -an | grep 5984

# Check firewall rules
iptables -L -n -v

The output showed:

tcp        0      0 127.0.0.1:5984          0.0.0.0:*               LISTEN

This revealed the core issue - CouchDB was only binding to localhost.

I modified the configuration file to listen on all interfaces:

# In /etc/couchdb/couch.ini
BindAddress = 0.0.0.0

Then attempted to restart the service:

sudo /etc/init.d/couchdb restart

But netstat still showed the same local-only binding. The service wasn't properly restarting.

Manual process inspection revealed the issue:

# Find and kill existing CouchDB processes
ps aux | grep couchdb
sudo kill -9 [process_id]

# Then start fresh
sudo /etc/init.d/couchdb start

Finally, netstat showed the desired behavior:

tcp        0      0 0.0.0.0:5984            0.0.0.0:*               LISTEN

To ensure complete resolution:

# Test local connection
curl http://localhost:5984

# Test from another machine
curl http://server_ip:5984

# Verify firewall
sudo iptables -A INPUT -p tcp --dport 5984 -j ACCEPT

For production environments, consider creating a proper init script or systemd service file:

# Example systemd override
[Service]
ExecStartPre=/bin/kill -9 $(pgrep -f couchdb)
Restart=always