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.

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

If a command fails with permission errors (rare but possible for certain low-level operations), substitute --user root:

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

Method 2: Enter the Container Interactively

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

1. SSH into your Docker host.
2. Enter the container as root:

   docker exec -it --user root nextcloud-aio-nextcloud bash

3. Navigate to the Nextcloud directory:

   cd /var/www/html

4. Run any occ command:

   php occ <command>

5. 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).
• 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 (useful when the web upgrader times out).

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. Put Nextcloud into maintenance mode before running these to prevent users from hitting the instance mid-operation:

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

Troubleshooting

• Permission Denied: try --user root instead of --user www-data. Some low-level commands require 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.