wip(TRUEREF-0018): commit version-scoped indexing work

README.md

@@ -645,6 +645,96 @@ This builds the image and starts two services:
 
 The SQLite database is stored in a named Docker volume (`trueref-data`) and persists across restarts.
 
+### Corporate deployment
+
+TrueRef supports deployment in corporate environments with private git repositories hosted on Bitbucket Server/Data Center and self-hosted GitLab instances (TRUEREF-0019).
+
+#### Required setup
+
+1. **Export your corporate CA certificate** (Windows):
+   - Open `certmgr.msc` → Trusted Root Certification Authorities
+   - Right-click your corporate CA → All Tasks → Export
+   - Choose Base64-encoded X.509 (.CER) format
+   - Save to a known location (e.g., `C:\certs\corp-ca.crt`)
+
+2. **Generate personal access tokens**:
+   - Bitbucket Server: Settings → HTTP access tokens (requires `REPO_READ` permission)
+   - GitLab: User Settings → Access Tokens (requires `read_repository` scope)
+
+3. **Update `.env` file**:
+
+```env
+# Corporate CA certificate path (PEM or DER — auto-detected)
+CORP_CA_CERT=C:/path/to/corp-ca.crt
+
+# Git remote hostnames (without https://)
+BITBUCKET_HOST=bitbucket.corp.example.com
+GITLAB_HOST=gitlab.corp.example.com
+
+# Personal access tokens (NEVER commit these)
+GIT_TOKEN_BITBUCKET=your-bitbucket-token-here
+GIT_TOKEN_GITLAB=your-gitlab-token-here
+```
+
+4. **Uncomment volume mounts in `docker-compose.yml`**:
+
+```yaml
+services:
+  web:
+    volumes:
+      - trueref-data:/data
+      - ${USERPROFILE:-$HOME}/.ssh:/root/.ssh:ro
+      - ${USERPROFILE:-$HOME}/.gitconfig:/root/.gitconfig:ro
+      - ${CORP_CA_CERT}:/certs/corp-ca.crt:ro
+    environment:
+      BITBUCKET_HOST: "${BITBUCKET_HOST}"
+      GITLAB_HOST: "${GITLAB_HOST}"
+      GIT_TOKEN_BITBUCKET: "${GIT_TOKEN_BITBUCKET}"
+      GIT_TOKEN_GITLAB: "${GIT_TOKEN_GITLAB}"
+```
+
+5. **Start the services**:
+
+```sh
+docker compose up --build
+```
+
+#### How it works
+
+The Docker entrypoint script (`docker-entrypoint.sh`) runs these steps in order:
+
+1. **Trust corporate CA**: Detects PEM/DER format and installs the certificate at the OS level so git, curl, and Node.js fetch all trust it automatically.
+2. **Fix SSH key permissions**: Corrects world-readable permissions from Windows NTFS mounts so SSH works properly.
+3. **Configure git credentials**: Sets up per-host credential helpers that provide the correct username and token for each remote.
+
+This setup works for:
+- HTTPS cloning with personal access tokens
+- SSH cloning with mounted SSH keys
+- On-premise servers with custom CA certificates
+- Mixed environments (multiple git remotes with different credentials)
+
+#### SSH authentication (alternative to HTTPS)
+
+For long-lived deployments, SSH authentication is recommended:
+
+1. Generate an SSH key pair if you don't have one:
+   ```sh
+   ssh-keygen -t ed25519 -C "trueref@your-company.com"
+   ```
+
+2. Add the public key to your git hosting service:
+   - Bitbucket: Settings → SSH keys
+   - GitLab: User Settings → SSH Keys
+
+3. Ensure your `~/.ssh/config` has the correct host entries:
+   ```
+   Host bitbucket.corp.example.com
+     IdentityFile ~/.ssh/id_ed25519
+     User git
+   ```
+
+4. The Docker Compose configuration already mounts `~/.ssh` read-only — no additional changes needed.
+
 ### Environment variables
 
 | Variable | Default | Description |