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

cd /mnt/DATA/git/govoplan-files/dev/connectors
cp .env.example .env
docker compose up -d nextcloud nextcloud-db webdav smb
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:

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

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:

{
  "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"] } }
    }
  ]
}

Start GovOPlaN with:

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:

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, and SMB 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.

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

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

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.