How to Set Up Nextcloud with External Storage Integration: A Complete Guide

You can integrate external storage into Nextcloud by enabling the External storage app and configuring connections to S3, SMB, WebDAV, or other backends through either the web UI or config/config.php, allowing remote storage to appear as local folders to users.

Nextcloud is an open-source, on-premises collaboration platform that stores, syncs, and shares files. According to the mikeroyal/Self-Hosting-Guide repository, you can extend your Nextcloud instance beyond local storage by mounting external backends like Amazon S3, MinIO, or NAS devices via SMB/CIFS. This setup lets users access remote data as if it were stored locally while keeping sensitive credentials secure through environment variables or Docker secrets.

How External Storage Integration Works in Nextcloud

The External storage integration functions through a modular adapter system within Nextcloud's architecture. When you enable the files_external app, it registers storage adapters that translate Nextcloud file operations into API calls for remote services like S3, WebDAV, or FTP.

When a user accesses a mounted folder, Nextcloud forwards the operation to the remote backend using configured credentials. Metadata and file lists are cached in Nextcloud's database to improve browsing performance, while large files stream directly between the client and remote storage without passing through the Nextcloud data directory.

Supported External Storage Backends

Nextcloud supports multiple storage protocols through the External storage app. You can mount:

• S3-compatible storage (Amazon S3, MinIO, DigitalOcean Spaces)
• SMB/CIFS (Windows share or NAS devices)
• WebDAV (remote Nextcloud instances or other WebDAV servers)
• FTP/FTPS (traditional file transfer servers)
• OpenStack Swift (OpenStack object storage)
• Google Drive and Dropbox (via OAuth integration)

Each backend supports authentication via API keys, OAuth tokens, or username/password pairs, with permissions that can be mapped to Nextcloud groups or restricted to read-only access.

Method 1: Deploy Nextcloud with Docker Compose

The mikeroyal/Self-Hosting-Guide provides a Docker Compose configuration that pre-installs the External storage app. This approach ensures the files_external app is available immediately upon container startup.

Create a docker-compose.yml file with the following configuration:

version: '3.7'

services:
  db:
    image: mariadb:10.11
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=example
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=example
    volumes:
      - db:/var/lib/mysql

  app:
    image: nextcloud:29-apache
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - 8080:80
    environment:
      - MYSQL_PASSWORD=example
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_HOST=db
    volumes:
      - nextcloud:/var/www/html
    # Pre-install the External storage app

    entrypoint: |
      sh -c "apt-get update && apt-get install -y \
        php-redis php-gd && \
        occ app:install files_external && \
        occ app:enable files_external && \
        exec apache2-foreground"

volumes:
  db:
  nextcloud:

Run docker-compose up -d to start the stack. The entrypoint script automatically installs and enables the External storage app using the occ command-line tool before starting Apache.

Method 2: Configure S3 or MinIO as Primary Storage

For production environments using object storage as the primary data backend, configure the objectstore section in config/config.php. This setup routes all file storage to your S3-compatible provider rather than the local filesystem.

Edit config/config.php to include the S3 configuration:

<?php
$CONFIG = array (
  'trusted_domains' => 
  array (
    0 => 'localhost',
    1 => 'nextcloud.example.com',
  ),
  'default_language' => 'en',
  'default_locale' => 'en_US',
  'default_phone_region' => 'US',
  // External storage configuration
  'objectstore' => array(
    'class' => 'OC\\Files\\ObjectStore\\S3',
    'arguments' => array(
      'bucket' => 'my-nextcloud-bucket',
      'hostname' => 's3.minio.local',
      'port' => 9000,
      'use_ssl' => false,
      'use_path_style' => true,
      'key' => getenv('MINIO_ACCESS_KEY'),
      'secret' => getenv('MINIO_SECRET_KEY'),
      'region' => '',
    ),
  ),
);

Store credentials securely using environment variables (MINIO_ACCESS_KEY and MINIO_SECRET_KEY) rather than hardcoding them in the configuration file. The OC\\Files\\ObjectStore\\S3 class handles the integration with S3-compatible APIs.

Method 3: Add External Storage via the Web UI

For non-primary storage or specific folders, use the graphical interface to mount external resources. This method stores configuration in the apps/files_external/ directory and database.

1. Navigate to Settings → Administration → External storages in your Nextcloud web interface.

2. Select your storage type from the dropdown (e.g., WebDAV).

3. Enter the connection details:

   • URL: The remote WebDAV endpoint
   • Username and Password: Authentication credentials

4. Assign the mount to specific users or groups under the Applicable column.

5. Check Read only if you want to prevent modifications to the remote storage.

6. Click the checkmark to save the configuration.

The External storage app stores these settings in the database and creates the appropriate mount points in the user's file view.

Security and Performance Considerations

When configuring external storage in Nextcloud, follow these security patterns from the mikeroyal/Self-Hosting-Guide:

• Store secrets in environment variables: Use getenv() in config.php or Docker secrets rather than committing credentials to version control.
• Use HTTPS for remote connections: Enable use_ssl for S3 backends and ensure WebDAV/FTP endpoints use TLS encryption.
• Limit mount scope: Assign external storage to specific groups rather than all users to minimize attack surface.
• Enable caching: The External storage app caches metadata in Nextcloud's database, reducing API calls to remote storage and improving directory listing performance.

Direct streaming ensures large files transfer between the client and remote storage without consuming disk space on the Nextcloud server, allowing you to scale storage independently of your Nextcloud instance.

Summary

• Enable the External storage app (files_external) through Docker entrypoint scripts or the Nextcloud App Store to unlock S3, SMB, WebDAV, and other backends.
• Configure primary storage in config/config.php using the objectstore array with the OC\\Files\\ObjectStore\\S3 class for S3-compatible services.
• Use the Web UI at Settings → Administration → External storages to add secondary mounts for specific users or groups without modifying configuration files.
• Secure credentials using environment variables or Docker secrets rather than storing API keys directly in config.php.
• Leverage direct streaming to avoid copying large files through the Nextcloud server, optimizing bandwidth and storage scalability.

Frequently Asked Questions

How do I enable the External storage app in Nextcloud?

You can enable the External storage app by running occ app:enable files_external from the command line or by navigating to Apps → Integration in the Nextcloud web interface and clicking Enable on the External storage support app. For Docker deployments, add this command to your container's entrypoint script to ensure it activates on startup.

Can I use multiple external storage backends simultaneously?

Yes, Nextcloud supports mixing multiple storage types within the same instance. You can configure S3 as your primary storage via config/config.php while mounting additional SMB shares or WebDAV endpoints through the web UI. Each mount point operates independently with its own authentication credentials and permission settings.

Where does Nextcloud store external storage configuration?

Configuration entered through the web UI is stored in the Nextcloud database and the apps/files_external/ application directory. Primary storage settings (S3 configuration) reside in config/config.php. The External storage app caches file metadata locally to improve performance, but the actual file contents remain on the remote backend.

Is external storage slower than local storage?

External storage introduces network latency for file operations, though Nextcloud mitigates this through metadata caching. Large files often stream directly between the client and remote storage, minimizing performance impact on the Nextcloud server. For optimal performance, ensure your Nextcloud server has low-latency connectivity to the external storage endpoint and sufficient database resources for caching.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}