Nextcloud Core Config

nextcloud-core-config

Quick Reference

Configuration File Location

The main server configuration file lives at config/config.php in the Nextcloud installation root. Nextcloud auto-generates this file during installation. Additional config files can be placed in config/ with the naming pattern *.config.php -- they are merged alphabetically.

Critical config.php Keys

| Key | Type | Description | |-----|------|-------------| | trusted_domains | array | Allowed hostnames for login -- MUST be set | | datadirectory | string | Absolute path to user data storage | | dbtype | string | Database backend: mysql, pgsql, sqlite3 | | dbhost | string | Database host (use localhost:/path/to/socket for Unix sockets) | | dbname | string | Database name | | dbuser / dbpassword | string | Database credentials | | overwrite.cli.url | string | Base URL for CLI-generated links (e.g., https://cloud.example.com) | | overwriteprotocol | string | Force protocol behind reverse proxy: https | | overwritehost | string | Force hostname behind reverse proxy | | overwritecondaddr | string | Regex for proxy IP to conditionally apply overwrites | | trusted_proxies | array | IP addresses of trusted reverse proxies | | default_phone_region | string | ISO 3166-1 country code (e.g., NL, DE, US) | | maintenance | bool | Enable/disable maintenance mode | | maintenance_window_start | int | Hour (UTC, 0-23) when heavy background jobs may run (NC 28+) |

Critical Warnings

NEVER store config.php in version control -- it contains database passwords, instance secrets, and the passwordsalt.

NEVER forget to set trusted_domains after installation -- this is the most common post-install issue. Users will see "Access through untrusted domain" errors.

NEVER set loglevel to 0 (debug) in production -- it generates massive log output and degrades performance.

NEVER edit config.php while Nextcloud is under heavy load without enabling maintenance mode first for critical changes.

ALWAYS set overwrite.cli.url when running behind a reverse proxy -- without it, CLI-generated URLs (cron, occ commands, email links) will be incorrect.

ALWAYS set default_phone_region -- Nextcloud shows a persistent admin warning until this is configured.

ALWAYS run occ commands as the web server user: sudo -u www-data php occ ...

---

Caching Configuration

Nextcloud supports multiple caching backends. ALWAYS configure caching for production deployments.

APCu (Local Cache)

'memcache.local' => '\OC\Memcache\APCu',

APCu provides per-server in-memory caching. ALWAYS use for memcache.local on single-server setups.

Redis (Distributed Cache + Locking)

'memcache.distributed' => '\OC\Memcache\Redis',
'memcache.locking' => '\OC\Memcache\Redis',
'redis' => [
    'host' => '/var/run/redis/redis-server.sock',
    'port' => 0,
    'dbindex' => 0,
    'timeout' => 1.5,
],

For TCP connections, use 'host' => '127.0.0.1' and 'port' => 6379.

Caching Rules

• ALWAYS set memcache.local for production -- APCu is the standard choice
• ALWAYS set memcache.locking to Redis when using Redis -- prevents file locking race conditions
• ALWAYS use Unix sockets for Redis when on the same server -- lower latency than TCP
• NEVER use APCu for memcache.distributed on multi-server setups -- APCu is process-local only
• NEVER omit memcache.locking when using Redis -- transactional file locking requires it

---

Proxy Configuration

When running Nextcloud behind a reverse proxy (nginx, Apache, Traefik, Caddy):

'trusted_proxies' => ['10.0.0.1', '172.16.0.0/12'],
'overwriteprotocol' => 'https',
'overwrite.cli.url' => 'https://cloud.example.com',
'overwritehost' => 'cloud.example.com',

• ALWAYS set trusted_proxies -- without it, Nextcloud ignores X-Forwarded-For headers and all requests appear to come from the proxy IP
• ALWAYS set overwriteprotocol to https when TLS terminates at the proxy
• NEVER add 0.0.0.0/0 to trusted_proxies -- this trusts ALL IPs and allows header spoofing

---

Mail Configuration

'mail_smtpmode' => 'smtp',
'mail_smtpsecure' => 'tls',
'mail_sendmailmode' => 'smtp',
'mail_from_address' => 'nextcloud',
'mail_domain' => 'example.com',
'mail_smtphost' => 'smtp.example.com',
'mail_smtpport' => 587,
'mail_smtpauth' => true,
'mail_smtpname' => 'user@example.com',
'mail_smtppassword' => 'password',

• ALWAYS use tls (STARTTLS on port 587) or ssl (implicit TLS on port 465)
• NEVER leave mail_smtpmode as sendmail on containerized deployments -- use smtp

---

Logging Configuration

'log_type' => 'file',
'logfile' => '/var/log/nextcloud/nextcloud.log',
'loglevel' => 2,
'log_type_audit' => 'file',
'logfile_audit' => '/var/log/nextcloud/audit.log',

| Level | Name | Use | |-------|------|-----| | 0 | Debug | Development only | | 1 | Info | Verbose production logging | | 2 | Warn | Recommended for production | | 3 | Error | Errors only | | 4 | Fatal | Critical failures only |

• ALWAYS set loglevel to 2 (Warn) for production
• ALWAYS configure logfile_audit separately when compliance logging is required
• NEVER set log_type to syslog without confirming syslog is configured to handle the volume

---

Programmatic Configuration Access

IConfig Interface (System + App + User Config)

use OCP\IConfig;

class MyService {
    public function __construct(private IConfig $config) {}

    public function example(): void {
        // System config (config.php values)
        $maintenance = $this->config->getSystemValue('maintenance', false);
        $this->config->setSystemValue('maintenance', true);

        // App config (per-app key-value store)
        $apiKey = $this->config->getAppValue('myapp', 'api_key', '');
        $this->config->setAppValue('myapp', 'api_key', 'new-key');
        $this->config->deleteAppValue('myapp', 'api_key');

        // User preferences (per-user per-app)
        $pref = $this->config->getUserValue('john', 'myapp', 'theme', 'light');
        $this->config->setUserValue('john', 'myapp', 'theme', 'dark');
        $this->config->deleteUserValue('john', 'myapp', 'theme');
    }
}

IAppConfig Interface (NC 28+ Typed App Config)

use OCP\IAppConfig;

class MyService {
    public function __construct(private IAppConfig $appConfig) {}

    public function example(): void {
        // Typed getters (NC 28+)
        $limit = $this->appConfig->getValueInt('myapp', 'max_items', 100);
        $enabled = $this->appConfig->getValueBool('myapp', 'feature_flag', false);
        $ratio = $this->appConfig->getValueFloat('myapp', 'threshold', 0.75);
        $name = $this->appConfig->getValueString('myapp', 'instance_name', 'default');

        // Typed setters
        $this->appConfig->setValueInt('myapp', 'max_items', 200);
        $this->appConfig->setValueBool('myapp', 'feature_flag', true);

        // Sensitive values (stored encrypted)
        $secret = $this->appConfig->getValueString('myapp', 'api_secret', '', sensitive: true);
        $this->appConfig->setValueString('myapp', 'api_secret', 'xyz', sensitive: true);

        // Check existence
        $exists = $this->appConfig->hasKey('myapp', 'api_key');

        // Get all keys for an app
        $keys = $this->appConfig->getKeys('myapp');
    }
}

Configuration Access Rules

• ALWAYS use constructor injection for IConfig and IAppConfig -- NEVER use \OCP\Server::get()
• ALWAYS use IAppConfig typed methods (NC 28+) over IConfig::getAppValue() for new code -- they provide type safety
• ALWAYS mark sensitive values with sensitive: true -- they are stored encrypted in the database
• ALWAYS provide sensible default values in getters -- NEVER assume a config key exists
• NEVER use setSystemValue() in app code to modify core Nextcloud settings -- only modify your own app's config
• NEVER store large data blobs in config -- use the database or file storage instead

---

Maintenance Mode

// Enable via config.php
'maintenance' => true,

// Or via occ
// sudo -u www-data php occ maintenance:mode --on
// sudo -u www-data php occ maintenance:mode --off

Maintenance Window (NC 28+)

'maintenance_window_start' => 1,  // 1:00 UTC

This tells Nextcloud to schedule heavy background tasks (like cleanup, expiry) during a 4-hour window starting at the specified hour. ALWAYS set this in production to avoid performance impact during business hours.

---

occ Config Commands

# Read system config
sudo -u www-data php occ config:system:get trusted_domains

# Set system config (string)
sudo -u www-data php occ config:system:set trusted_domains 1 --value=cloud.example.com

# Set system config (typed)
sudo -u www-data php occ config:system:set debug --value=true --type=boolean
sudo -u www-data php occ config:system:set loglevel --value=2 --type=integer

# Delete system config
sudo -u www-data php occ config:system:delete debug

# Read app config
sudo -u www-data php occ config:app:get myapp api_key

# Set app config
sudo -u www-data php occ config:app:set myapp api_key --value=new-key

# Delete app config
sudo -u www-data php occ config:app:delete myapp api_key

# List all config
sudo -u www-data php occ config:list
sudo -u www-data php occ config:list --private  # includes sensitive values

• ALWAYS use --type flag when setting non-string system values -- without it, booleans and integers are stored as strings
• NEVER use config:list --private in scripts that log output -- it exposes passwords and secrets

---

Decision Tree

Which config interface to use?

Need to read/write config.php values?
  YES --> Use IConfig::getSystemValue() / setSystemValue()
  NO --> Is it app-specific configuration?
    YES --> Is it NC 28+?
      YES --> Use IAppConfig (typed methods)
      NO  --> Use IConfig::getAppValue() / setAppValue()
    NO --> Is it per-user preference?
      YES --> Use IConfig::getUserValue() / setUserValue()
      NO  --> Re-evaluate: config might belong in database table

Which caching backend?

Single server?
  YES --> memcache.local = APCu
          Need file locking? --> Add Redis for memcache.locking
  NO  --> memcache.distributed = Redis
          memcache.locking = Redis
          memcache.local = APCu (still per-server)

---

Reference Links

• [references/methods.md](references/methods.md) -- Complete config.php key reference, IConfig methods, IAppConfig methods
• [references/examples.md](references/examples.md) -- Configuration patterns and occ command examples
• [references/anti-patterns.md](references/anti-patterns.md) -- Common configuration mistakes and how to avoid them

Official Sources

• https://docs.nextcloud.com/server/latest/adminmanual/configurationserver/configsamplephp_parameters.html
• https://docs.nextcloud.com/server/latest/adminmanual/configurationserver/occ_command.html
• https://docs.nextcloud.com/server/latest/adminmanual/configurationserver/caching_configuration.html
• https://docs.nextcloud.com/server/latest/adminmanual/configurationserver/reverseproxyconfiguration.html
• https://docs.nextcloud.com/server/latest/developer_manual/basics/storage/configuration.html

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Nextcloud-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.