# Modow CouchDB Installer

[Modow home](https://modow.vip/en/) · [Sync & installation guide](https://modow.vip/en/sync/) · [中文](https://modow.vip/couchdb/README.md)

This installer prepares a self-hosted CouchDB service for Modow and Obsidian Self-hosted LiveSync. It creates a CouchDB container, an everyday sync account with limited privileges, and a LiveSync-compatible database without deleting an existing database.

For the visual, step-by-step guide, open <https://modow.vip/en/sync/>.

## Before you begin

- Install and start Docker Desktop or a Docker-compatible engine.
- Use an always-on NAS, home server, or cloud host if you expect the phone to sync at any time.
- Back up an important vault before its first sync.
- Use HTTP only on a trusted local network. Public access must use HTTPS, a VPN, or a secure tunnel.
- Never expose CouchDB port `5984` directly to the public internet.

## macOS, Linux, and NAS

Download the installer and checksum list, verify the file, then run it:

```bash
curl -fsSL https://modow.vip/couchdb/install.sh -o install.sh
curl -fsSL https://modow.vip/couchdb/checksums.txt -o checksums.txt
grep ' install.sh$' checksums.txt | shasum -a 256 -c -
bash install.sh
```

Check the environment without installing:

```bash
bash install.sh --doctor
```

## Windows 10 and 11

Start Docker Desktop, open PowerShell, and run:

```powershell
Invoke-WebRequest https://modow.vip/couchdb/install.ps1 -OutFile install.ps1
Invoke-WebRequest https://modow.vip/couchdb/checksums.txt -OutFile checksums.txt
(Get-FileHash .\install.ps1 -Algorithm SHA256).Hash
Get-Content .\checksums.txt
Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1
```

Compare the displayed SHA256 with `checksums.txt`. Check the environment without installing:

```powershell
.\install.ps1 -Doctor
```

## What the installer creates

- One isolated CouchDB container and persistent Docker volume.
- One administrator account used for deployment and database creation.
- One lower-privilege account for everyday synchronization.
- One database initialized for Self-hosted LiveSync compatibility.
- A local `.env` file containing the generated configuration and credentials.

The installer is safe to run again. It reuses compatible resources and does not delete or empty an existing database. If an existing database has incompatible LiveSync metadata, the installer stops and explains the conflict instead of overwriting it.

## Keep credentials private

The local `.env` file contains passwords. Do not upload it to Git, include it in a release archive, paste it into a support ticket, or share it in a screenshot. Store production credentials and signing material outside the project repository with permissions restricted to the current user.

Use the everyday sync account in Obsidian and Modow. Keep the administrator account for maintenance only.

## Configure the clients

Both Obsidian Self-hosted LiveSync and Modow must use the same four values:

| Field | Meaning |
| --- | --- |
| Service URL | The CouchDB root URL, without `/_utils` |
| Database | The same CouchDB database name on both ends |
| Username | The everyday sync account |
| Password | The everyday sync password |

For a trusted LAN, a service URL may look like `http://192.168.1.10:5984`. For public access, put CouchDB behind an HTTPS reverse proxy and use a URL such as `https://sync.example.com`.

If you have a Modow official sync account, use exactly:

```text
https://sync.modow.vip
```

Do not add `:5984`. Do not add `/_utils`. HTTPS uses port `443` by default. The compatible alias `https://sync.modow.net` also works, but `.vip` is the recommended address.

The browser admin panel is `https://sync.modow.vip/_utils/`. It is for administration only and must not be entered as the client service URL.

## Troubleshooting

- **Docker is unavailable:** start Docker Desktop or the Docker service, then rerun `--doctor`.
- **Port conflict:** choose another local port, or stop the service already using the selected port.
- **Database creation is denied:** the everyday sync account may not have permission to create databases. Create and authorize the database with the administrator account, then switch back.
- **Works on the LAN but not outside:** configure a VPN, secure tunnel, or HTTPS reverse proxy. Do not open port `5984` publicly.
- **Connection succeeds but no notes appear:** confirm Obsidian has written data, both clients use the same database name, and the everyday account has read/write permission.
- **Encrypted profile rejected:** Modow 3.0 supports unencrypted DB12 / P2 profiles with path obfuscation disabled. It stops safely on unsupported encrypted profiles.

## Relationship between the four components

- **Obsidian** stores local files in a desktop vault. It is not a server.
- **Self-hosted LiveSync** is an Obsidian community plugin that replicates changes. It is not the server or database.
- **CouchDB** is the remote sync database used to exchange changes.
- **Modow** is an independent local-first HarmonyOS app. It is not an Obsidian port; it connects to the same CouchDB through a compatible LiveSync protocol.