> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up VARIOS AI server folder

> Docker volumes, network shares (SMB/NFS) and troubleshooting for the VARIOS AI server folder data source

<Tip>
  This page describes the technical setup of the **VARIOS AI server folder** data source.
  For a general description of source types, see
  [Knowledge Bases](./index#local-folder).
</Tip>

<Note>
  For setting up a VARIOS AI server folder which you are not hosting yourself, please refer to your hosting administrator.
</Note>

## How Does the Path Work?

Internally, VARIOS AI uses the base directory `/data/Data/KnowledgebaseDocuments` inside the container. The **share folder** you specify in the UI is a **relative subfolder** within this base directory. The actual path is composed as follows:

```
/data/Data/KnowledgebaseDocuments + <Share Folder>
```

Example: If you enter `/legal-texts` as the share folder, the application looks inside the container at:

```
/data/Data/KnowledgebaseDocuments/legal-texts
```

<Note>
  Hidden files (starting with `.` or `~`) and symlinks are automatically
  skipped. The path `..` (relative paths upward) is not allowed for security
  reasons.
</Note>

## Docker Compose Configuration

For the container to access your local files, a **volume** must be configured in the `docker-compose.yml`. In the on-premise configuration, the default setup looks like this:

```yaml theme={null}
services:
  php:
    volumes:
      # ... other volumes ...
      - "./KnowledgebaseDocuments:/data/Data/KnowledgebaseDocuments"
```

This means: The folder `./KnowledgebaseDocuments` on the **host** (relative to the `docker-compose.yml` directory) is mounted inside the container at `/data/Data/KnowledgebaseDocuments`.

<Steps>
  <Step title="Create the folder on the host">
    Create the folder that will be mounted as a volume and add subfolders as needed.

    ```bash theme={null}
    mkdir -p ./KnowledgebaseDocuments/legal-texts
    ```
  </Step>

  <Step title="Place documents">
    Copy or move the desired documents into the folder.

    ```bash theme={null}
    cp /path/to/document.pdf ./KnowledgebaseDocuments/legal-texts/
    ```
  </Step>

  <Step title="Configure the share folder in the UI">
    In the source configuration, enter the **subfolder** as the share folder, e.g. `/legal-texts`. Click **Test connection** to verify that the folder is reachable.
  </Step>

  <Step title="Set up synchronization">
    Choose an **interval** (Manual, every hour, every day, etc.) or click **Sync now** to read the documents immediately.
  </Step>
</Steps>

<Warning>
  **Check permissions:** The process inside the container must have read access
  to the mounted files. Pay attention to file permissions (especially on Linux
  systems).
</Warning>

## Mount Custom Folders as Volumes

You can also mount a **different host path** as a volume, e.g. a network share or any directory on the server:

```yaml theme={null}
services:
  php:
    volumes:
      # ... other volumes ...
      - "./KnowledgebaseDocuments:/data/Data/KnowledgebaseDocuments"
      # Mount a custom directory additionally:
      - "/srv/company-documents:/data/Data/KnowledgebaseDocuments/company-documents:ro"
```

In this example, `/srv/company-documents` on the host is made available inside the container at `/data/Data/KnowledgebaseDocuments/company-documents` (read-only `:ro`). In the UI, enter `/company-documents` as the share folder.

<Tip>
  If the source is read-only, it is recommended to mount the volume as
  **read-only** (`:ro`). This prevents accidental modifications by the
  container.
</Tip>

## Mount Network Shares (SMB / NFS)

Documents often need to be read from a **network drive** (e.g. Windows share or NAS). To do this, mount the network share on the **host** first, then bind it into the container via a volume.

<Tabs>
  <Tab title="SMB / CIFS (Windows Shares)">
    **1. Install package**

    ```bash theme={null}
    sudo apt update && sudo apt install -y cifs-utils
    ```

    **2. Create mount point**

    ```bash theme={null}
    sudo mkdir -p /mnt/smb-documents
    ```

    **3. Create credentials file** (recommended so that passwords are not stored in `/etc/fstab`)

    ```bash theme={null}
    sudo nano /etc/smbcredentials
    ```

    Contents:

    ```
    username=my-user
    password=my-password
    domain=WORKGROUP
    ```

    Restrict permissions:

    ```bash theme={null}
    sudo chmod 600 /etc/smbcredentials
    ```

    **4. Add permanent mount to `/etc/fstab`**

    ```bash theme={null}
    //192.168.1.100/Documents /mnt/smb-documents cifs credentials=/etc/smbcredentials,uid=1000,gid=1000,file_mode=0644,dir_mode=0755,iocharset=utf8 0 0
    ```

    **5. Mount and verify**

    ```bash theme={null}
    sudo mount -a
    ls /mnt/smb-documents
    ```

    **6. Add to `docker-compose.yml`**

    ```yaml theme={null}
    services:
      php:
        volumes:
          # ... other volumes ...
          - "./KnowledgebaseDocuments:/data/Data/KnowledgebaseDocuments"
          - "/mnt/smb-documents:/data/Data/KnowledgebaseDocuments/smb-documents:ro"
    ```

    In the UI, enter `/smb-documents` as the share folder.
  </Tab>

  <Tab title="NFS (Linux / NAS)">
    **1. Install package**

    ```bash theme={null}
    sudo apt update && sudo apt install -y nfs-common
    ```

    **2. Create mount point**

    ```bash theme={null}
    sudo mkdir -p /mnt/nfs-documents
    ```

    **3. Add permanent mount to `/etc/fstab`**

    ```bash theme={null}
    192.168.1.100:/export/documents /mnt/nfs-documents nfs defaults,_netdev 0 0
    ```

    **4. Mount and verify**

    ```bash theme={null}
    sudo mount -a
    ls /mnt/nfs-documents
    ```

    **5. Add to `docker-compose.yml`**

    ```yaml theme={null}
    services:
      php:
        volumes:
          # ... other volumes ...
          - "./KnowledgebaseDocuments:/data/Data/KnowledgebaseDocuments"
          - "/mnt/nfs-documents:/data/Data/KnowledgebaseDocuments/nfs-documents:ro"
    ```

    In the UI, enter `/nfs-documents` as the share folder.
  </Tab>
</Tabs>

<Warning>
  Make sure the network share is **mounted before starting the Docker
  containers**. Otherwise, an empty folder will be mounted into the container.
  With the entry in `/etc/fstab`, this happens automatically at system startup.
</Warning>

<Note>
  After mounting, always use **Test connection** in the UI to verify that the
  share folder is reachable and readable inside the container.
</Note>

## Common Errors and Solutions

| Error Message                       | Cause                                         | Solution                                                                                                       |
| ----------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| "Share folder could not be found"   | Folder does not exist in the container        | Check volume: Is the host path correct? Was the folder created? Does the share folder name match?              |
| "Share folder could not be read"    | Missing read permissions                      | Check file permissions on the host (`chmod`/`chown`). The container process typically runs as a specific user. |
| Path with `..` is rejected          | Security check prevents relative paths        | Use only simple subfolder names (e.g. `/docs`), no `../` constructs.                                           |
| SMB share not mounted after restart | Entry in `/etc/fstab` is missing or incorrect | Check `/etc/fstab` and test with `sudo mount -a`.                                                              |
| NFS mount hangs during boot         | Network is not ready when mount is attempted  | Ensure the `_netdev` option is set in `/etc/fstab` so the mount only occurs after network initialization.      |