Configuring Nextcloud Trusted Domains: A Complete Guide

Introduction

When setting up Nextcloud behind a reverse proxy like Nginx Proxy Manager, you’ll inevitably encounter the “Trusted Domain” error. This security feature prevents unauthorized access by restricting which domains can access your Nextcloud instance. In this guide, I’ll walk through how to properly configure trusted domains for a Nextcloud instance running in Docker, including the complete setup from Docker Compose to reverse proxy configuration.

Understanding the Problem

When you try to access Nextcloud through a domain that isn’t in the trusted domains list, you’ll see an error like:

Access through untrusted domain
Please contact your administrator. If you are an administrator, edit the "trusted_domains" setting in config/config.php like the example in config/config.php.dist.

This is Nextcloud’s security mechanism preventing access from unauthorized domains. It’s a good thing, but it requires proper configuration.

The Complete Setup

Docker Compose Configuration

Here’s the complete Docker Compose setup for Nextcloud with MariaDB:

version: "3.8"

services:
  db:
    image: mariadb:10.11
    container_name: nextcloud-db
    restart: unless-stopped
    command: --transaction-isolation=READ-COMMITTED --binlog-format=ROW
    volumes:
      - ./db:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: strongrootpassword
      MYSQL_DATABASE: nextcloud
      MYSQL_USER: nextcloud
      MYSQL_PASSWORD: nextcloudpass

  app:
    image: nextcloud:apache
    container_name: nextcloud-app
    restart: unless-stopped
    depends_on:
      - db
    volumes:
      - ./nextcloud:/var/www/html

    # IMPORTANT PART 👇
    ports:
      - "100.89.58.49:5008:80"

    environment:
      MYSQL_HOST: db
      MYSQL_DATABASE: nextcloud
      MYSQL_USER: nextcloud
      MYSQL_PASSWORD: nextcloudpass

Key points about this configuration:

Port binding: The port mapping 100.89.58.49:5008:80 binds the container’s port 80 to the host IP 100.89.58.49 on port 5008. This allows external access while keeping the service on a non-standard port.
Volume persistence: The ./nextcloud:/var/www/html volume ensures your Nextcloud data and configuration persist across container restarts.
Database setup: MariaDB 10.11 provides a stable database backend with proper transaction isolation settings for Nextcloud.

Nginx Proxy Manager Configuration

When forwarding from Nginx Proxy Manager to this Nextcloud instance, configure it as follows:

Proxy Host Settings:

Domain Names: cloud.tekonline.com.au (or your domain)
Forward Hostname/IP: 100.89.58.49 (the host IP where Nextcloud is running)
Forward Port: 5008 (the port mapped in Docker Compose)
Forward Scheme: http
Cache Assets: Enabled (optional, for better performance)
Block Common Exploits: Enabled (recommended)
Websockets Support: Enabled (required for Nextcloud features like notifications)

SSL Settings:

Enable SSL certificate (Let’s Encrypt recommended)
Force SSL: Enabled
HTTP/2 Support: Enabled

Adding Trusted Domains: Step-by-Step Guide

Method 1: Using the `occ` Command (Recommended)

The occ (ownCloud Console) command is the official and recommended way to manage Nextcloud configuration. It’s safe, validated, and handles the configuration properly.

Step 1: Check Current Trusted Domains

First, let’s see what domains are currently configured:

ssh ubuntuserver "docker exec nextcloud-app php occ config:system:get trusted_domains"

Output example:

100.89.58.49:5008

Step 2: Add Your Domain

Add your new domain using the occ command. You need to specify an index for the array:

ssh ubuntuserver "docker exec nextcloud-app php occ config:system:set trusted_domains 1 --value=cloud.tekonline.com.au"

Output:

System config value trusted_domains => 1 set to string cloud.tekonline.com.au

Step 3: Verify the Configuration

Confirm that your domain was added successfully:

ssh ubuntuserver "docker exec nextcloud-app php occ config:system:get trusted_domains"

Expected output:

100.89.58.49:5008
cloud.tekonline.com.au

Step 4: Verify in config.php (Optional)

You can also check the raw configuration file to see the changes:

ssh ubuntuserver "docker exec nextcloud-app cat /var/www/html/config/config.php | grep -A 5 'trusted_domains'"

Expected output:

  'trusted_domains' => 
  array (
    0 => '100.89.58.49:5008',
    1 => 'cloud.tekonline.com.au',
  ),

Method 2: Through the Web UI

Some Nextcloud versions allow you to add trusted domains through the web interface:

Log into Nextcloud as an administrator
Navigate to Settings → Administration → Basic settings
Look for the “Trusted domains” section
Click “Add domain” and enter your domain
Save the changes

Note: The UI method may not always be available depending on your Nextcloud version. Some versions hide this option for security reasons, requiring command-line configuration instead.

Method 3: Direct config.php Editing (Not Recommended)

While you can edit /var/www/html/config/config.php directly, this method is not recommended because:

❌ No validation of the configuration
❌ Risk of syntax errors breaking Nextcloud
❌ Manual array index management
❌ Potential for configuration corruption

If you must edit directly (not recommended), the format is:

'trusted_domains' => 
array (
  0 => '100.89.58.49:5008',
  1 => 'cloud.tekonline.com.au',
),

Managing Multiple Trusted Domains

Adding Additional Domains

To add more domains, continue with the next available index:

# Add third domain
docker exec nextcloud-app php occ config:system:set trusted_domains 2 --value=cloud2.example.com

# Add fourth domain
docker exec nextcloud-app php occ config:system:set trusted_domains 3 --value=cloud3.example.com

Removing a Trusted Domain

To remove a trusted domain:

docker exec nextcloud-app php occ config:system:delete trusted_domains 1

Note: After deleting, you may need to re-index the remaining domains to avoid gaps in the array.

Listing All Trusted Domains

View all configured trusted domains:

docker exec nextcloud-app php occ config:system:get trusted_domains

Best Practices

1. Use the `occ` Command

✅ Always prefer the occ command over direct file editing. It’s:

Validated by Nextcloud
Safe and reliable
The official method
Easy to automate

2. Include Both IP and Domain

When configuring trusted domains, consider including:

The direct IP:port access (for troubleshooting)
The domain name (for production access)

This gives you flexibility to access Nextcloud both ways if needed.

3. Use HTTPS Domains

When adding domains, use the domain name that matches your SSL certificate. If you’re using cloud.tekonline.com.au with SSL, add exactly that domain (not www.cloud.tekonline.com.au unless you have a certificate for that too).

4. Test After Changes

After adding a trusted domain:

Clear your browser cache
Try accessing Nextcloud via the new domain
Verify SSL is working correctly
Test key features (login, file upload, etc.)

5. Document Your Configuration

Keep track of:

Which domains are configured
Why each domain was added
When changes were made

This helps with troubleshooting and future maintenance.

Troubleshooting

Domain Still Not Working

If you’ve added a domain but still get the “untrusted domain” error:

Verify the domain was added:docker exec nextcloud-app php occ config:system:get trusted_domains
Check for typos: Ensure the domain matches exactly (case-sensitive in some cases)
Clear Nextcloud cache:docker exec nextcloud-app php occ files:scan --all
Restart the container:docker restart nextcloud-app

Port Issues

If you’re accessing via a port (like cloud.example.com:5008), make sure to include the port in the trusted domain:

docker exec nextcloud-app php occ config:system:set trusted_domains 1 --value=cloud.example.com:5008

Reverse Proxy Headers

Ensure your Nginx Proxy Manager is sending the correct headers. In the Advanced tab of your proxy host, you may need:

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Nginx Proxy Manager usually handles these automatically, but verify if you’re having issues.

Complete Example: Full Setup Workflow

Here’s a complete workflow from zero to working Nextcloud:

1. Create Docker Compose File

Save the Docker Compose configuration above as docker-compose.yml.

2. Start the Services

docker-compose up -d

3. Wait for Initialization

Wait a few minutes for Nextcloud to initialize. Check logs:

docker logs -f nextcloud-app

4. Configure Nginx Proxy Manager

Set up your proxy host pointing to 100.89.58.49:5008.

5. Add Trusted Domain

docker exec nextcloud-app php occ config:system:set trusted_domains 1 --value=cloud.tekonline.com.au

6. Access via Domain

Navigate to https://cloud.tekonline.com.au and complete the Nextcloud setup wizard.

Security Considerations

Why Trusted Domains Exist

Trusted domains prevent:

Host header injection attacks
Unauthorized domain access
DNS rebinding attacks
Phishing attempts

What to Include

✅ Include:

Your production domain
Any subdomains you use
The direct IP:port (for emergency access)

❌ Don’t include:

Wildcard domains (not supported)
Domains you don’t control
Test domains you no longer use

Regular Maintenance

Periodically review your trusted domains:

Remove unused domains
Update domains if you change your infrastructure
Verify all domains are still necessary

Conclusion

Configuring trusted domains in Nextcloud is straightforward when you use the right tools. The occ command is your best friend for managing this configuration safely and reliably. Combined with proper Docker Compose setup and Nginx Proxy Manager configuration, you’ll have a secure, accessible Nextcloud instance.

Remember:

✅ Use occ command for configuration
✅ Include both IP and domain for flexibility
✅ Test after making changes
✅ Document your setup
✅ Keep trusted domains list clean and current

With these practices, managing Nextcloud trusted domains becomes a simple, routine task rather than a troubleshooting nightmare.