☠️ tiffs.dev

obsidian sync com couchdb e wireguard (debian 12 + docker)

leitura de 8 min

este guia documenta como configurar um servidor com CouchDB em Docker para servir como backend do plugin Self-hosted LiveSync do Obsidian, garantindo sincronização segura entre dispositivos via VPN com WireGuard.

pré-requisitos

fluxograma do projeto

sequenceDiagram
    participant usuário
    participant VPS
    participant Docker/CouchDB
    participant WireGuard
    participant Obsidian App
    participant Google Drive

    usuário->>VPS: instala Debian 12 e Docker
    usuário->>VPS: cria diretório e docker-compose.yml
    usuário->>Docker/CouchDB: inicia container CouchDB
    usuário->>VPS: cria túnel SSH
    usuário->>Docker/CouchDB: acessa interface web e cria DB
    usuário->>Docker/CouchDB: configura permissões

    usuário->>WireGuard: instala e configura no VPS e clientes
    WireGuard->>Obsidian App: estabelece túnel VPN
    Obsidian App->>Docker/CouchDB: acessa banco via VPN

    usuário->>Obsidian App: instala plugin LiveSync
    Obsidian App->>Docker/CouchDB: sincroniza notas

    usuário->>VPS: cria script de backup com rclone
    VPS->>Google Drive: envia backup diário via cron

    usuário->>VPS: restaura backup em caso de falha

instância do CouchDB no Docker

  • CouchDB: banco de dados NoSQL orientado a documentos (JSON).
  • por que usar: o plugin de obsidian sync usa CouchDB para armazenar e replicar notas entre dispositivos.
  • interface: possui uma UI web chamada Fauxton, acessível em /_utils.

1. criação do diretório do projeto

mkdir obsidian-sync
cd obsidian-sync

2. criação do docker-compose.yml

criar o arquivo docker-compose.yml na raiz do projeto (obsidian-sync)

services:
  couchdb:
    image: couchdb:latest
    container_name: couchdb-for-ols
    environment:
      - COUCHDB_USER=admin                     # ajuste conforme preferir
      - COUCHDB_PASSWORD=senha_forte_aqui      # use uma senha forte
    volumes:
      - ./couchdb-data:/opt/couchdb/data
      - ./couchdb-etc:/opt/couchdb/etc/local.d
    ports:
      - "5984:5984"
    restart: unless-stopped
 
networks:
  default:
    driver: bridge
  • image: couchdb:latest → especifica o uso da versão mais recente do CouchDB.
  • environment → define usuário e senha de administrador (só funcionam na primeira inicialização).
  • volumes → mapeia diretórios locais para dentro do container, garantindo persistência.
  • ports → expõe a porta 5984 (api e interface web do CouchDB).
  • restart: unless-stopped → garante que o container reinicie automaticamente em caso de falha ou reboot do servidor.
  • as variáveis de ambiente só funcionam na primeira inicialização
  • usar uma senha forte e segura.

3. inicialização

criar os diretórios antes, para evitar erros de permissão.

mkdir -p couchdb-data couchdb-etc
docker compose up -d
docker compose logs -f couchdb
  • docker compose up -d → sobe o container em segundo plano.
  • docker compose logs -f couchdb → mostra os logs em tempo real.
  • mensagem esperada: Apache CouchDB has started. Time to relax.

diretórios criados para armazenar dados e configurações persistentes do CouchDB. isso garante que, mesmo que o container seja recriado, os dados não se percam.

  • couchdb-data → onde ficam os dados do banco (notas, índices, etc)
  • couchdb-etc → onde ficam arquivos de configuração adicionais

configuração do CouchDB

com o container do CouchDB rodando, é hora de criar o banco de dados e configurar as permissões.

1. acesso à interface web

na máquina local, utilizar túnel SSH:

ssh -L 5984:localhost:5984 [usuário]@[IP_do_servidor]

acessar via navegador na máquina local: http://localhost:5984/_utils

2. criação do banco de dados

  • fazer login com as variáveis definidas no docker-compose.yml
  • clicar em “create database”
  • database name: obsidian
  • partitioning: non-partitioned

3. configuração de permissões

adicionar o username obsidian_user no campo “members” → “users” → “add user”

backup automatizado

1. instalação do rclone e configuração do Google Drive

  • instalar rclone no servidor: 
    curl https://rclone.org/install.sh | sudo bash
  • configurar o acesso ao Google Drive: 
    rclone config
    • n para criar uma nova configuração
    • dar um nome para a configuração (exemplo: gdrive)
    • escolher o tipo de storage drive
    • seguir as instruções para autenticar a conta do google com o client id previamente criado
    • escolher o escopo de acesso 3 (drive.file)
    • seguir as instruções para autenticação do rclone

2. criação do script

script que compacta apenas o diretório couchdb-data, onde ficam armazenados os bancos. o script mantém apenas os últimos 7 dias de backup (ajustável), e roda em um cronjob, garantindo a execução automática sem intervenção manual. os logs ajudam a verificar se o backup rodou corretamente.

  • criar o script backup-couchdb.sh em /usr/local/bin/: 
    #!/bin/bash
 
# diretório do projeto
PROJECT_DIR=/home/[USER]/obsidian-sync
BACKUP_DIR=/home/[USER]/backups
 
# nome do arquivo de backup com data
BACKUP_FILE=backup-couchdb-$(date +%F).tar.gz
 
# garante que a pasta de backup existe
mkdir -p $BACKUP_DIR
 
# compacta o diretório de dados
tar -czf $BACKUP_DIR/$BACKUP_FILE -C $PROJECT_DIR couchdb-data
 
# envia para google drive
rclone copy "$BACKUP_DIR/$BACKUP_FILE" gdrive:/backups-couchdb
 
# remove backups mais antigos que 7 dias
find $BACKUP_DIR -type f -name "backup-couchdb-*.tar.gz" -mtime +7 -delete
  • dar permissão de execução: 
    sudo chmod +x /usr/local/bin/backup-couchdb.sh

3. criação do cronjob

  • editar o cron do usuário: 
    crontab -e
  • adicionar ao arquivo a linha abaixo, para rodar o job de backup diariamente às 2h da manhã: 
    0 2 * * * /usr/local/bin/backup-couchdb.sh >> /var/log/couchdb-backup.log 2>&1
  • logs ficam salvos em /var/log/couchdb-backup.log
  • backups em /home/[USER]/backups
  • cada arquivo terá o formato backup-couchdb-[YYYY]-[MM]-[DD].tar.gz

acesso seguro ao CouchDB com WireGuard

para permitir que o plugin Obsidian LiveSync acesse o CouchDB hospedado em um servidor remoto, pode-se configurar uma VPN privada com WireGuard para acessar o banco remotamente, sem exposição à internet.

  • o servidor (onde está o CouchDB) atua como host da VPN.
  • os dispositivos clientes (computador, celular, tablet) se conectam ao servidor via WireGuard.
  • após a conexão, os clientes acessam o CouchDB como se estivessem na mesma rede local.

1. instalação WireGuard

o WireGuard deve ser instalado no servidor onde está o banco de dados, e também em todos os dispositivos (clientes) que irão sincronizar com ele.

instalação no servidor

  • instalar WireGuard: 
    sudo apt update
sudo apt install wireguard

instalação nos clientes

  • Linux: instalação via gerenciador de pacotes (apt, brew, etc.)
  • Windows/macOS: download do instalador
  • Android/iOS: disponível na loja de aplicativos (WireGuard VPN)

2. criação de chaves

WireGuard usa criptografia de chave pública. cada dispositivo (servidor e cliente) precisa de um par de chaves.

chaves no servidor

wg genkey | tee server_private.key | wg pubkey > server_public.key

chaves nos clientes

mobile
  • abrir o app WireGuard
  • tocar em “+” → “criar do zero”.
  • o app gera automaticamente:
    • PrivateKey: chave privada do cliente
    • PublicKey: chave pública do cliente

desktops

wg genkey | tee client_private.key | wg pubkey > client_public.key

3. arquivo de configuração

configuração no servidor

  • criar o arquivo /etc/wireguard/wg0.conf: 
    [Interface]
Address = 10.100.0.1/24
PrivateKey = <server_private_key>
ListenPort = 51820
 
[Peer]
PublicKey = <client_public_key>
AllowedIPs = 10.100.0.2/32

configuração nos clientes

  • exemplo: cliente-obsidian.conf
[Interface]
Address = 10.100.0.2/24
PrivateKey = <client_private_key>
 
[Peer]
PublicKey = <server_public_key>
Endpoint = [VPS_IP]:51820
AllowedIPs = 10.100.0.1/32
PersistentKeepalive = 25

campos dos arquivos de configuração

campofunção
AddressIP interno da VPN (ex: 10.100.0.1 para servidor, 10.100.0.2 para cliente)
PrivateKeychave privada do dispositivo (nunca compartilhar)
PublicKeychave pública do outro dispositivo
ListenPortporta que o servidor escuta (ex: 51820, escolha acima de 1024)
EndpointIP público + porta do servidor (ex: vpn.exemplo.com:51820)
AllowedIPsIPs que podem ser acessados via VPN (ex: IP do servidor)
PersistentKeepalivemantém o túnel ativo em redes NAT (recomendado: 25)

4. ativação da VPN

no servidor

sudo wg-quick up wg0

no cliente

  • clientes linux/macOS: 
    sudo wg-quick up computador-obsidian
  • clientes mobile/desktop: ativar túnel no app wireguard

5. testar a conexão

  • no cliente: 
    curl http://10.100.0.1:51820
    resultado esperado: retornar dados do couchdb

plugin Obsidian LiveSync

1. instalação do plugin

  • abrir o Obsidian no dispositivo que desejar sincronizar
  • ⚙️ → “community plugins”
  • instalar e ativar o plugin Self-hosted LiveSync (by vorotamoroz)

2. configurações do plugin

  • ⚙️ → “self-hosted livesync”
  • “setup” → “manual setup” → next
  • na opção “remote configuration”, preencher as informações:
    • url do couchdb: http://10.100.0.1:51820
    • usuário e senha conforme configuração do docker-compose.yml
    • database: nome do banco usado para sincronização (obsidian)

manutenção

atualizações

  • atualizar imagens do Docker regularmente 
    docker compose pull
docker compose up -d
  • atualizar pacotes do sistema 
    sudo apt update && sudo apt upgrade -y

restauração de backup

  • parar o container e limpar os diretórios: 
    docker compose down
sudo rm -rf couchdb-data couchdb-etc
mkdir couchdb-data couchdb-etc
  • copiar o backup da máquina local para o servidor: 
    scp backup-couchdb-[YYYY]-[MM]-[DD].tar.gz [USER]@[VPS_IP]:/home/user/
  • restaurar: 
    tar -xzf backup-couchdb-[YYYY]-[MM]-[DD].tar.gz -C /home/user/obsidian-sync
  • subir o container novamente: 
    docker compose up -d
  • testar o acesso em /_utils (acessando a interface web do couchdb)

comandos úteis

subir/derrubar um container

docker compose up -d
docker compose down

logs do Docker

docker compose logs -f couchdb

healthcheck

curl http://[COUCHDB_USER]:[COUCHDB_PASSWORD]@localhost:[COUCHDB_PORT]/

reset completo

docker compose down && sudo rm -rf couchdb-data couchdb-etc && mkdir couchdb-data couchdb-etc && docker compose up -d

problemas comuns

erro no login do CouchDB

  • sintoma: foram alterados os valores das variáveis COUCHDB_USER/COUCHDB_PASSWORD e não é possível logar no CouchDB.
  • causa: variáveis só valem na primeira inicialização do diretório de dados. provavelmente o diretório couchdb-data já tinha dados antigos.
  • solução:
    • limpar e reiniciar os diretórios:
    docker compose down
sudo rm -rf couchdb-data couchdb-etc
mkdir couchdb-data couchdb-etc
docker compose up -d

erro de permissão em volumes

  • sintoma: “Permission denied” ao escrever em /opt/couchdb/...
  • soluções:
    • preferida: não usar user: no compose (deixar padrão do container).
    • alternativa: ajustar ownership no host:
    sudo chown -R 5984:5984 couchdb-data couchdb-etc

warn sobre bancos do sistema ausentes

  • sintoma: avisos sobre bancos do sistema ausentes (_users, _replicator, _global_changes)
  • causas: inicialização não criou DBs; falta de permissão de escrita.
  • soluções:
    • verificar permissões (item acima)
    • criar os DBs manualmente:
    curl -X PUT http://admin:112@localhost:5984/_users
curl -X PUT http://admin:112@localhost:5984/_replicator
curl -X PUT http://admin:112@localhost:5984/_global_changes

visão de gráfico