Nextcloud Administration - occ, Users, Apps, Upgrades, and Background Jobs

Status: Active
Last Updated: 2026-08-26
Category: Cloud - Nextcloud Operations
Prerequisites: nextcloud-setup, docker-basics
Time: 2-3 hours
Tags: nextcloud, occ, administration, users, upgrades, cron

Summary

Day-two operations for the fogserv.cloud Nextcloud instance: the occ command-line tool, user and group administration, app lifecycle management, safe upgrade procedure, background job configuration with cron, and log triage. Setup itself is covered by nextcloud-setup; this article assumes a running instance in Docker.

🎯 What You'll Learn

By the end of this article, you'll be able to:

• ✅ Run any occ command against the containerized instance
• ✅ Manage users, groups, and quotas from the CLI
• ✅ Install, update, and disable apps safely
• ✅ Perform zero-surprise major upgrades
• ✅ Configure and verify background jobs via cron
• ✅ Read and filter Nextcloud logs effectively

---

Table of Contents

1. occ: The Admin Swiss-Army Knife
2. User & Group Administration
3. App Management
4. Upgrades
5. Background Jobs (Cron)
6. Logs
7. Practical Examples

---

Context / Why This Matters

Most Nextcloud problems reported by users — "sharing is broken", "files don't appear", "my quota didn't reset" — are fixable in one occ command, but only if you know it exists. The web UI exposes maybe 20% of administrative control; occ is the other 80%. Because our instance runs in Docker per nextcloud-setup, every command goes through docker exec.

Implementation / Core Content

occ: The Admin Swiss-Army Knife

All examples assume the container is named nextcloud and you are root on the host.

alias ncc='docker exec --user www-data nextcloud php occ'
ncc status
ncc check

The critical part is --user www-data: running occ as root creates cache/log files owned by root that later break the web interface. If you ever did that:

docker exec nextcloud chown -R www-data:root /var/www/html

Essential diagnostic commands:

ncc status                    # version, maintenance mode
ncc db:add-missing-indices    # after upgrades; silences DB warnings
ncc files:scan --all          # rescan filesystem for out-of-band changes
ncc files:scan-app-data       # fix broken appdata
ncc security:certificates     # manage trusted certs (self-signed LDAP etc.)

User & Group Administration

ncc user:add alice                       # interactive password prompt
ncc user:add --group="family" bob        # create + add to group
ncc user:list                            # list users (add -i to show IDs)
ncc user:info alice
ncc user:resetpassword alice             # generate or set new password
ncc user:setting alice settings email "alice@example.com"
ncc user:disable alice && ncc user:enable alice
ncc user:delete alice                    # deletes their files!

Groups and quotas:

ncc group:add family
ncc group:adduser family carol
ncc group:list
ncc group:delete old-team

# Quotas: none | 5 GB | unlimited, or arbitrary like 250 GB
ncc user:setting alice files quota "25 GB"

Quota enforcement happens during background file scans, so changes may take until the next cron run to display.

App Management

ncc app:list                             # enabled / disabled sections
ncc app:install calendar
ncc app:update calendar                  # single app
ncc app:update --all                     # everything updatable
ncc app:disable activity
ncc app:remove deadapp

Rules of thumb:

• Update apps after, not before, a core upgrade.
• Before a core upgrade, disable third-party apps — an incompatible app is the most common cause of failed upgrades.
• Apps that ship with core (activity, dashboard) can be disabled but not removed safely.

Upgrades

Our deployment uses the official image with a pinned major tag (e.g., nextcloud:30). The safe sequence:

cd /opt/nextcloud

# 1. Put the instance into maintenance mode
docker exec --user www-data nextcloud php occ maintenance:mode --on

# 2. Take a backup FIRST (see restic-backups)
restic backup /srv/nextcloud --tag pre-upgrade

# 3. Bump the image ONE MAJOR at a time in docker-compose.yml
#    nextcloud:30 -> nextcloud:31   (never skip majors)
docker compose pull && docker compose up -d

# 4. Watch the migration
docker logs -f nextcloud

# 5. Post-upgrade housekeeping
docker exec --user www-data nextcloud php occ maintenance:mode --off
docker exec --user www-data nextcloud php occ upgrade
docker exec --user www-data nextcloud php occ db:add-missing-indices
docker exec --user www-data nextcloud php occ files:scan --all

Notes:

• Skipping majors breaks the database migrator; always step through each major release.
• Keep the previous image tag in your shell history for instant rollback (docker compose down → restore tag → restore backup).
• After upgrading, re-enable third-party apps one at a time via ncc app:update <app> && ncc app:enable <app>.

Background Jobs (Cron)

Nextcloud defers work — photo previews, trash cleanup, activity emails, federation syncs — to background jobs. Options are AJAX, webcron, or cron (recommended). We use a host-side crontab hitting the container:

# /etc/cron.d/nextcloud  (run as www-data equivalent inside container)
*/5 * * * * docker exec --user www-data nextcloud php cron.php

Verify:

ncc background:cron                      # set mode to cron
ncc background:job                       # manual single-job run
grep cron.php /var/www/html/data/nextcloud.log | tail   # confirm runs

Admin UI check: Administration → Basic settings → Background jobs should show "Last job ran X minutes ago" under 5 minutes. If jobs pile up ("Last job ran days ago"), shares stop expiring, versions accumulate, and preview generation lags — treat a stalled queue as an incident.

Tuning for large instances:

ncc config:system:set maintenance_window_start --type=integer --value=1
docker exec --user www-data nextcloud php occ background:jobs:list

Logs

Default log location inside the container: /var/www/html/data/nextcloud.log (JSON lines).

# Tail from the host
docker exec nextcloud tail -f /var/www/html/data/nextcloud.log

# Pretty-print last error
docker exec nextcloud tail -50 /var/www/html/data/nextcloud.log \
  | jq -r 'select(.level==3) | "\(.time) \(.message)"'

# occ wrapper
ncc log:tail
ncc log:file                     # show/set log file
ncc log:manage --level=warning   # reduce noise in normal operation

Log levels: 0 debug, 1 info, 2 warning, 3 error, 4 fatal. Keep level 1–2 normally; drop to 0 temporarily when chasing a bug.

Also check the web UI's Administration → Logging — it renders the same entries with stack traces expanded, which is often faster to read than raw JSON.

Practical Examples

Example 1: Onboard a new family member end-to-end

ncc user:add --group="family" dave        # sets password interactively
ncc user:setting dave settings email "dave@example.com"
ncc user:setting dave files quota "100 GB"
ncc group:adduser photos-viewers dave     # shared album access

Then have Dave install the client (covered in nextcloud-clients) and enable 2FA (../security/two-factor-authentication.md).

Example 2: Diagnose "my files disappeared"

ncc files:scan --path="/dave/files"       # rebuild index for that user
ncc user:info dave                        # check quota exceeded?
docker exec nextcloud df -h /var/www/html/data
docker logs nextcloud --since 1h | grep -i -E 'error|exception'

Most frequent causes found in this order: quota full, disk full, scan drift after bulk upload over SMB.

Example 3: Safe minor-version patch

cd /opt/nextcloud
docker compose pull && docker compose up -d
sleep 60 && ncc status
ncc check

Minor patches within the same major do not need maintenance mode, but keep the pre-patch restic snapshot habit regardless.

Troubleshooting & Common Pitfalls

Problem	Cause	Fix
Web UI 500s after running commands as root	Root-owned cache files in data dir	chown -R www-data:root /var/www/html
Upgrade fails midway	Skipped a major version, or third-party app incompatible	Restore backup, step majors individually, disable non-core apps first
"Background jobs not executing"	Host cron entry missing or wrong container name	Verify /etc/cron.d/nextcloud; test docker exec --user www-data nextcloud php cron.php manually
Files uploaded via SMB invisible	Index drift; external storage not scanned	ncc files:scan --all or path-scoped scan
occ hangs on db:add-missing-indices	Large tables, live traffic	Run during maintenance window; indices build online but slowly
Users locked out after upgrade	Maintenance mode left on	occ maintenance:mode --off

Next Steps / Ops Actions

• Add db:add-missing-indices to your post-upgrade checklist permanently
• Confirm cron background jobs are active and alert if stale (see ../observability/simple-alerts.md)
• Fold the upgrade sequence into backup-automation so snapshots precede every bump
• Review TLS termination in front of Nextcloud: tls-configuration

Sources & Related Articles

External references consulted:

• https://docs.nextcloud.com/server/latest/admin_manual/occ_command.html
• https://docs.nextcloud.com/server/latest/admin_manual/maintenance/upgrade.html
• https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/background_jobs_configuration.html

Related knowledge-base articles:

• nextcloud-setup
• nextcloud-clients
• nextcloud-collaboration
• backup-automation

Change Log

2026-08-26

• Initial creation by KB writing session.