Nextcloud

Keep files, calendars, and contacts on your own server.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Nextcloud

Start locally with an editable Nextcloud container. Add a dedicated or shared database when needed.

Choose the single Docker image or AIO deployment method.
For the single image, use generated admin credentials and configure trusted domains for the public URL.

selfhost app --directory ./nextcloud init nextcloud --method docker

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./nextcloud start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd nextcloud
docker compose -f compose.yaml up -d

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose Nextcloud Docker, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "nextcloud",
  "name": "Nextcloud",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Actions for a linked container

Nextcloud status

Read version, installation and maintenance status.

selfhost existing action EXISTING_ID status

Installed apps

List enabled and disabled Nextcloud apps.

selfhost existing action EXISTING_ID apps

Update Nextcloud apps

Update installed Nextcloud apps after making a backup.

Enable this action explicitly in management permissions on a writable server. Running it also requires the exact saved app name.

selfhost existing action EXISTING_ID update-apps --confirm "EXACT_APP_NAME"

Before configuring integrations

For the single-image deployment, native settings are read and written through occ. Application updates, maintenance commands and supported OIDC setup use reviewed actions.
An existing AIO can be connected without transferring its storage or lifecycle to Selfhost.
Single-image database placement includes PostgreSQL, MySQL and MariaDB using app-specific connection settings. Select a fresh or already migrated database before first start; changing the engine does not convert existing data.
AIO retains control of its child containers, backups and updates.
Nextcloud OIDC setup does not automatically grant the admin group to an IdP user.
MySQL and MariaDB source bindings currently require TLS mode disable and a private network. Sources requiring TLS are rejected by these bindings; certificate-aware custom deployments remain manual. PostgreSQL retains its native TLS modes.

Nextcloud integrations

Compose service: nextcloud. These operations use the profile saved when this deployment is created.

Native settings

Changes use the app’s configuration commands. Unrelated settings are preserved.

Supported fields (7)

Trusted domains trusted-domains: Hostnames allowed to access this Nextcloud instance. string_list
Default phone region default-phone-region: string
Default language default-language: string
Maintenance window (UTC hour) maintenance-window: integer · advancedRange: 0 to 23
Public protocol overwrite-protocol: string · advancedChoices: http, https
Public URL public-url: string · advanced
Maintenance mode maintenance: boolean · advanced

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./nextcloud config nextcloud
selfhost app --directory ./nextcloud plan nextcloud changes.json
selfhost app --directory ./nextcloud apply nextcloud changes.json --revision REVIEWED_REVISION

Identity provider login

Selfhost can register a client with a supported provider and configure this app. Callback path: /index.php/apps/user_oidc/code.

No administrator role is assigned by Selfhost. Check the app’s first-login policy and retain a local recovery account.

Save connection.json and replace the URLs. Supply SELFHOST_IDP_TOKEN privately in your shell.

{
  "provider": "zitadel",
  "issuer": "https://identity.example.com",
  "app_url": "https://app.example.com",
  "name": "Nextcloud"
}

selfhost app --directory ./nextcloud connect-account nextcloud connection.json
selfhost app --directory ./nextcloud connect-plan nextcloud connection.json
selfhost app --directory ./nextcloud connect nextcloud connection.json --revision REVIEWED_REVISION

Test sign-in in a separate browser session. HTTPS domains and HTTP loopback development origins are supported by Selfhost; the chosen app and provider must also accept the resulting callback. Provider permissions, localhost and recovery.

Database placement

This recipe supports postgres, mysql, mariadb. Workspace projects can choose a dedicated database, a shared source with a separate database and account, or an existing external database before their first start.

postgres adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.
mysql adapter TLS modes: disable. Use a private network for connections with TLS disabled.
mariadb adapter TLS modes: disable. Use a private network for connections with TLS disabled.

Standalone directories use the generated Compose and environment files directly. Configure the database there before first start. Selfhost’s source provisioning commands belong to workspace projects and are optional.

Database setup, CLI commands and backups

App actions

Check installation

Read Nextcloud installation status.

selfhost app --directory ./nextcloud action nextcloud status

Installed apps

List enabled and disabled apps.

selfhost app --directory ./nextcloud action nextcloud list-apps

Update all apps · schedulable

Update installed Nextcloud apps. Back up app data before upgrading.

selfhost app --directory ./nextcloud action nextcloud update-apps

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

Install an app

Download and enable a Nextcloud app by its app-store ID.

App ID app-id: string

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./nextcloud action nextcloud install-app --inputs action-inputs.json

Scan files

Scan storage and update the file index for all users.

selfhost app --directory ./nextcloud action nextcloud scan-files

Repair installation

Run Nextcloud maintenance repair operations.

selfhost app --directory ./nextcloud action nextcloud repair

Run background jobs

Run due Nextcloud background jobs now.

selfhost app --directory ./nextcloud action nextcloud run-cron

Run occ command

Run advanced occ arguments as the web-server user. Enter a JSON array of arguments; commands can change or delete app data.

Arguments (JSON array) arguments: arguments

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./nextcloud action nextcloud occ --inputs action-inputs.json

Connect identity provider

Install OIDC support and configure sign-in. Keep local administrator login available until a browser login succeeds.

Login provider name provider: stringDefault: "selfhost"
Client ID client-id: string
Client secret client-secret: secret
Discovery URL discovery-url: string

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./nextcloud action nextcloud connect-oidc --inputs action-inputs.json

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

nextcloud: nextcloud:stable-apache

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Nextcloud documentation