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
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:

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. This deployment-owned configuration may reference environment variables only when their exact names are listed in GOVOPLAN_CONNECTOR_SECRET_ENV_ALLOWLIST; profile API responses expose only 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"] } }
    },
    {
      "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:

export GOVOPLAN_FILES_CONNECTOR_PROFILES_FILE=/mnt/DATA/git/govoplan-files/dev/connectors/profiles.local.json
export GOVOPLAN_CONNECTOR_SECRET_ENV_ALLOWLIST=SEAFILE_ADMIN_PASSWORD,NEXTCLOUD_ADMIN_PASSWORD,WEBDAV_PASSWORD,SMB_PASSWORD,MINIO_ROOT_PASSWORD
export GOVOPLAN_CONNECTOR_ALLOW_PRIVATE_NETWORKS=true

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 and seeds tiny WebDAV, Nextcloud, SMB, and MinIO fixtures. WebDAV and Nextcloud are browsed and imported through the pinned connector transport. SMB and S3 product access deliberately fails closed until their SDK transports support peer pinning, so their fixtures are retained for transport development and reported as expected optional skips. The --require-smb and --require-s3 switches are useful only while developing that transport support and currently make the smoke check fail by design.

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]

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

/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.