govoplan-files/dev/connectors/README.md

# Connector Dev Stack

This directory keeps local Docker Compose assets for GovOPlaN file connector
development. The stack is intentionally separate from production deployment and
binds services to localhost high ports.

## Start

```bash
cd /mnt/DATA/git/govoplan-files/dev/connectors
cp .env.example .env
mkdir -p data/smb data/webdav
docker compose up -d nextcloud nextcloud-db webdav smb minio
docker compose up -d seafile-db seafile-memcached seafile
```

If the SMB service was already running before a compose change, recreate it so
the image and share configuration are applied:

```bash
docker compose rm -sf smb
docker compose up -d --build smb
```

Endpoints:

- Nextcloud: `http://127.0.0.1:9081`, WebDAV root
  `http://127.0.0.1:9081/remote.php/dav/files/admin/`
- Seafile: `http://127.0.0.1:9082`, WebDAV root
  `http://127.0.0.1:9082/seafdav/`
- WebDAV: `http://127.0.0.1:9083`
- SMB: `smb://127.0.0.1:1445/files`
- MinIO/S3 API: `http://127.0.0.1:9000`, console
  `http://127.0.0.1:9001`

The local fixture data under `data/` is ignored by git.

## GovOPlaN Profile Config

Connector profiles are read from `GOVOPLAN_FILES_CONNECTOR_PROFILES_JSON` or
`GOVOPLAN_FILES_CONNECTOR_PROFILES_FILE`. Credentials should be referenced by
secret refs or environment variables; profile API responses only expose the
credential source and configured state.

Example local profile file:

```json
{
  "profiles": [
    {
      "id": "dev-seafile",
      "label": "Dev Seafile",
      "provider": "seafile",
      "endpoint_url": "http://127.0.0.1:9082",
      "scope_type": "system",
      "credential_mode": "basic",
      "username": "admin@example.local",
      "password_env": "SEAFILE_ADMIN_PASSWORD",
      "capabilities": ["browse", "import"],
      "metadata": { "webdav_endpoint_url": "http://127.0.0.1:9082/seafdav/" },
      "policy": { "allow": { "providers": ["seafile"] } }
    },
    {
      "id": "dev-nextcloud",
      "label": "Dev Nextcloud",
      "provider": "nextcloud",
      "endpoint_url": "http://127.0.0.1:9081/remote.php/dav/files/admin/",
      "scope_type": "system",
      "credential_mode": "basic",
      "username": "admin",
      "password_env": "NEXTCLOUD_ADMIN_PASSWORD",
      "capabilities": ["browse", "import"],
      "policy": { "allow": { "providers": ["nextcloud", "webdav"] } }
    },
    {
      "id": "dev-webdav",
      "label": "Dev WebDAV",
      "provider": "webdav",
      "endpoint_url": "http://127.0.0.1:9083",
      "scope_type": "system",
      "credential_mode": "basic",
      "username": "govoplan",
      "password_env": "WEBDAV_PASSWORD",
      "capabilities": ["browse", "import"],
      "policy": { "allow": { "providers": ["webdav"] } }
    },
    {
      "id": "dev-smb",
      "label": "Dev SMB",
      "provider": "smb",
      "endpoint_url": "smb://127.0.0.1:1445/files",
      "scope_type": "system",
      "credential_mode": "basic",
      "username": "govoplan",
      "password_env": "SMB_PASSWORD",
      "capabilities": ["browse", "import"],
      "policy": { "allow": { "providers": ["smb"] } }
    },
    {
      "id": "dev-s3",
      "label": "Dev MinIO",
      "provider": "s3",
      "endpoint_url": "http://127.0.0.1:9000",
      "base_path": "",
      "scope_type": "system",
      "credential_mode": "basic",
      "username": "govoplan",
      "password_env": "MINIO_ROOT_PASSWORD",
      "capabilities": ["browse", "import"],
      "metadata": {
        "bucket": "govoplan",
        "region": "us-east-1",
        "path_style": true,
        "verify_tls": false
      },
      "policy": { "allow": { "providers": ["s3"] } }
    }
  ]
}
```

Start GovOPlaN with:

```bash
export GOVOPLAN_FILES_CONNECTOR_PROFILES_FILE=/mnt/DATA/git/govoplan-files/dev/connectors/profiles.local.json
```

## Smoke Test

Run the connector helper smoke checks from an environment where
`govoplan-files` and `httpx` are importable:

```bash
cd /mnt/DATA/git/govoplan-files/dev/connectors
/mnt/DATA/git/govoplan-core/.venv/bin/python smoke.py
```

The script reads `.env` from this directory when present, seeds tiny WebDAV,
Nextcloud, SMB, and MinIO fixtures, then browses and imports them through the
connector helper layer. Pass `--require-smb` after recreating the SMB container
to fail on SMB access errors instead of reporting them as an optional skip. Pass
`--require-s3` after starting MinIO and installing `govoplan-files[s3]` to fail
on S3 access errors instead of reporting them as an optional skip.

SMB smoke checks need the optional Python dependency in the environment running
the script:

```bash
/mnt/DATA/git/govoplan-core/.venv/bin/python -m pip install -e /mnt/DATA/git/govoplan-files[smb]
```

S3 smoke checks need the optional boto3 dependency in the environment running
the script:

```bash
/mnt/DATA/git/govoplan-core/.venv/bin/python -m pip install -e /mnt/DATA/git/govoplan-files[s3]
```

The SMB service is built from `dev/connectors/smb/` so the development share is
deterministic: one `files` share backed by `data/smb`, with the credentials from
`.env`.

The SMB image runs as the non-root `govoplan` user with UID/GID `1000` and
listens on unprivileged container port `1445`. The default host endpoint remains
`smb://127.0.0.1:1445/files`. `SMB_USER` must stay `govoplan` unless the image is
rebuilt with a matching user; `SMB_PORT` must be `1024` or higher. `SMB_PASSWORD`
is applied when the image is built, so rebuild the `smb` service after changing
it in `.env`.