How to Interact with OCC in a Docker Container for Nextcloud Installs

This article explains how to run occ commands in a Nextcloud All-in-One (AIO) Docker container as deployed on noiz.cloud and equivalent Noiz-managed installs. occ is Nextcloud’s command-line management tool, a holdover from its ownCloud origins, used for maintenance, repairs, app management, user administration, and configuration. It is intended for intermediate to advanced Linux users with sudo or root access to the Docker host.

Last reviewed: 1 August 2026, against the current Nextcloud AIO Docker deployment. It complements the official Nextcloud occ documentation; the container names and docker exec pattern are what differ from a bare-metal install.

Official Documentation Reference

Using the occ command: the full command reference, including what is unavailable in maintenance mode.
Nextcloud AIO: how to run occ commands: the AIO docker exec pattern.
Nextcloud AIO: how to update the containers: how AIO handles Nextcloud upgrades.

Prerequisites

Linux command line knowledge.
sudo or root SSH access to the Docker host.
Nextcloud AIO installed and running.
Confirm the Nextcloud container is up using docker ps: it is named nextcloud-aio-nextcloud.

Method 1: Run occ Directly from the Host (Recommended)

This is the cleanest and most reliable approach. The Nextcloud documentation recommends running occ as the www-data user, which is how the web server owns the application files. Running as www-data avoids file ownership issues that can arise when occ creates or writes files as root.

docker exec --user www-data nextcloud-aio-nextcloud php /var/www/html/occ <command>

For example, to check the current Nextcloud status:

docker exec --user www-data nextcloud-aio-nextcloud php /var/www/html/occ status

Do not switch to --user root when a command fails. Nextcloud only runs occ as the user that owns config/config.php, which on AIO is www-data, so running it as root stops with a message that the console has to be executed with the owner of config.php.

Method 2: Enter the Container Interactively

Useful when exploring the container, running multiple commands in sequence, or troubleshooting paths.

SSH into your Docker host.
Enter the container as www-data: docker exec -it --user www-data nextcloud-aio-nextcloud bash
Navigate to the Nextcloud directory: cd /var/www/html
Run any occ command: php occ <command>
Exit the container when finished: exit

Common occ Commands

The following are the commands you will reach for most often. All can be run via Method 1 by replacing <command>.

Maintenance and Repair

maintenance:repair --include-expensive: repair core data integrity issues (recommended after major upgrades).
maintenance:mode --on: put Nextcloud into maintenance mode (users see a maintenance page). In maintenance mode no apps are loaded, so commands provided by apps, such as files:scan and versions:cleanup, are unavailable. Only use it when a command’s documentation asks for it.
maintenance:mode --off: bring Nextcloud back online.

Database Migrations

db:add-missing-indices: add any indices required by recent Nextcloud or app updates.
db:add-missing-columns: add missing columns introduced by updates.
db:add-missing-primary-keys: add missing primary keys.

These three are idempotent and safe to run regularly; they output Done. when complete or nothing when there is no work to do.

App Management

app:list: list installed and disabled apps with versions.
app:enable <appname>: enable an app.
app:disable <appname>: disable an app.

Configuration

config:system:get <key>: read a system configuration value (e.g. version, trusted_domains).
config:system:set <key> --value=<value>: set a system configuration value.

User Management

user:list: list all Nextcloud users.
user:resetpassword <user>: reset a user’s password (prompts interactively, so use Method 2 for this one).

Encryption

encryption:status: show current encryption status and active module.
encryption:recover-user <user>: recover encrypted files for a user using the recovery key.

Storage Maintenance

files:scan --all: rescan the file index for all users (use when files have been added or changed on disk outside Nextcloud).
versions:cleanup: purge old file versions to reclaim storage.
trashbin:cleanup: empty the trash bin for all users.

Upgrades

upgrade: run pending upgrade routines from the command line. On AIO, upgrades are managed from the AIO interface (Stop containers, back up, then Start and update containers), so do not use this to upgrade an AIO install unless Noiz support or the AIO documentation directs you to.

Long-running Commands

Some occ commands can take a long time to complete on large installs, notably encryption:encrypt-all, files:scan --all, and versions:cleanup against many users. Do not wrap files:scan or versions:cleanup in maintenance mode: they are app commands, and the Nextcloud documentation notes that apps are not loaded in maintenance mode, so the commands are unavailable. Run them directly, ideally outside working hours:

docker exec --user www-data nextcloud-aio-nextcloud php /var/www/html/occ files:scan --all

For any other long-running command, check its entry in the occ documentation before deciding whether maintenance mode is needed.

Troubleshooting

Console has to be executed with the user that owns the file config/config.php: the command ran as the wrong user. Run it with --user www-data, and do not change the ownership of config.php to suit root.
Permission Denied while running as www-data: check the ownership of config/config.php and the Nextcloud files inside the container; they should belong to www-data. If they have been changed, open a support ticket with Noiz rather than running occ as root.
Command Not Found: confirm the container name (docker ps) and the occ path (/var/www/html/occ in the official image). A wrong container name or a path from a non-Docker install is the usual cause.

[noiz] | disrupt the signal