How to enable Nextcloud maintenance mode

Maintenance mode gives a Nextcloud administrator a controlled stop point before backups, upgrades, restores, or storage work. It locks active browser sessions and blocks new logins so files, database rows, and app state do not keep changing while the server is being changed.

The supported server-side switch is the occ maintenance:mode command, run as the web-server user from the installed Nextcloud directory. On Debian and Ubuntu systems that user is commonly www-data, while other distributions or containers may use a different HTTP user.

Use maintenance mode only for work that requires a quiet instance or where the upstream command documentation asks for it. Apps are not loaded while maintenance mode is active, so app-provided occ commands can be unavailable even though built-in server commands still work.

1. Change to the Nextcloud installation directory.

   $ cd /var/www/nextcloud

   Use the directory that contains the occ file. Archive, package, and container installs may use paths such as /var/www/html, /usr/share/webapps/nextcloud, or a container-specific app directory.

2. Check the current Nextcloud status.

   $ sudo -E -u www-data php occ status
     - installed: true
     - version: 34.0.0.12
     - versionstring: 34.0.0
     - edition:
     - maintenance: false
     - needsDbUpgrade: false
     - productname: Nextcloud
     - extendedSupport: false

   -E preserves environment variables that some installations use for PHP or database access. Replace www-data with the HTTP user used by the server.

3. Notify affected users before enabling maintenance mode.

   Enabling maintenance mode interrupts active browser sessions and prevents new logins until maintenance mode is turned off.

4. Enable Nextcloud maintenance mode.

   $ sudo -E -u www-data php occ maintenance:mode --on
   Maintenance mode enabled

5. Verify that occ reports maintenance mode as enabled.

   $ sudo -E -u www-data php occ status
     - installed: true
     - version: 34.0.0.12
     - versionstring: 34.0.0
     - edition:
     - maintenance: true
     - needsDbUpgrade: false
     - productname: Nextcloud
     - extendedSupport: false

6. Request the Nextcloud web root and check for the maintenance response.

   $ curl -i https://cloud.example.com/
   HTTP/1.1 503 Service Unavailable
   Server: Apache/2.4.67 (Debian)
   X-Nextcloud-Maintenance-Mode: 1
   Retry-After: 120
   Content-Type: text/html; charset=UTF-8
   ##### snipped #####
   <h2>Maintenance mode</h2>
   ##### snipped #####

   The exact web server and header order can differ, but 503 Service Unavailable, X-Nextcloud-Maintenance-Mode: 1, or the visible maintenance screen confirms that users are seeing the maintenance state.