How Nextcloud primary object storage on Ceph RGW works
Nextcloud supports OpenStack Swift and S3 as primary object storage, and its documentation names the Ceph Object Gateway (RGW) as an example S3 implementation. If your organization runs Nextcloud or plans to, the first decision is whether file content should live in Ceph RGW from day one, because the switch is not something you can flip later on a busy instance without consequences. The object store holds only file content, addressed by a unique identifier. File names, directories, sharing rules and other metadata stay in the Nextcloud database, so that database remains on the critical path for every file read and write, and it must be backed up and restored together with the bucket.
This split changes what your backup and recovery plan must cover. A Ceph RGW backup alone cannot rebuild a usable Nextcloud, and a database backup alone points at content you may not have. Confirm with your Nextcloud and Ceph administrators how the bucket and the database will be snapshotted or dumped at matching points in time, and where that pairing is documented. The Nextcloud primary storage documentation, linked below, is the reference for the object store configuration itself, and your team should read it alongside the database and file-cache guidance before writing the runbook.
The most important point for planning is that configuring a primary object store on an existing Nextcloud instance makes all existing files on the instance inaccessible. Files already stored on the local data directory do not migrate automatically when you add the object store configuration, so an in-place switch on a live instance is effectively an outage for existing users. Plan the choice at installation, or plan a documented migration of existing content into the object store with a tested rollback, and confirm the exact procedure with Nextcloud and your Ceph team before any production change.
What you need before enabling Nextcloud on Ceph RGW
Enabling object storage as Nextcloud primary storage changes where file content lives, so the prerequisites cover the application stack, the Ceph release, the RGW endpoint and the backups taken before any change. Each card below is a check to complete and document before the cutover plan is approved.
Nextcloud 35 platform requirements
Confirm the database, PHP and web server versions against the Nextcloud 35 system requirements before planning the change. The recommended database is MariaDB 11.8 or PostgreSQL 18, with MariaDB 10.11 to 12.3, PostgreSQL 14 to 18, and MySQL 8.4 or 9.7 also supported. Use PHP 8.5, with 8.3 and 8.4 supported, and serve it through Apache 2.4 or nginx with php-fpm. Oracle Database requires an enterprise subscription, so confirm that before choosing it.
Supported Ceph release
Select Tentacle or Squid as the Ceph release for the RGW endpoint, since these are the actively maintained releases receiving backports and security fixes. Tentacle's estimated end of life is June 1, 2027, and Squid's is October 31, 2026, so a cluster on Squid will need an upgrade plan sooner. Record the chosen release and its end-of-life date in the change record.
Reachable RGW endpoint and S3 credentials
Confirm that the Nextcloud application servers can reach the Ceph Object Gateway endpoint on the required network path and that a dedicated RGW user holds S3 access keys scoped to the Nextcloud bucket. Test a basic S3 put, get and delete from each Nextcloud node with the same client settings Nextcloud will use. Ask who issues and rotates these keys and where they are stored.
Bucket and TLS certificate planning
Decide how many buckets Nextcloud will use, what each one holds, and how its name and region setting will be fixed before data arrives, since changing them later means moving objects. Plan the TLS certificate for the RGW endpoint, including its subject names and trust chain on every Nextcloud node, so that the connection does not fail after the switch. Confirm who owns certificate renewal.
Full database backup before any change
Take and verify a full database backup before enabling primary object storage, because the database holds the file names, directories and metadata that point to object content. Also back up the existing data directory and the config file. Confirm restore steps with a test restore to a separate host, since enabling primary storage on an existing instance makes existing files inaccessible until the storage layout is handled.
Upgrade and app compatibility check
Nextcloud does not allow skipping major releases, so confirm the current major version and upgrade one step at a time if needed. Back up before every upgrade and disable third-party apps until each one is confirmed compatible with the target release. Ask the application team to list installed apps and their maintainers, since app behavior with object storage should be checked before go-live.
What moves to the object store and what stays in the database
When primary object storage is enabled, Nextcloud writes the bytes of each uploaded file to the bucket as an object identified by a unique ID that Nextcloud generates. The object store holds only this file content, so the bulk of your capacity consumption moves to Ceph RGW. Nextcloud does not store the file name or its location in the bucket, so an object on its own is not meaningful to anyone outside the instance.
- Object keys: Each object is named by an internal identifier, not by the path a user sees in the web interface.
- Versions and previews: Confirm with your Nextcloud administrator how versions, trash and generated previews are stored in your configuration, since their growth affects bucket size.
- Growth pattern: Capacity follows the total size of stored content, plus any replication or erasure coding overhead configured in Ceph.
- Deletion: Removing a file in Nextcloud removes its reference, but the timing of object removal depends on trash and retention settings.
- Access path: Users never reach the bucket directly; all reads and writes pass through the Nextcloud server.
Before sizing, ask your Nextcloud partner to estimate the object volume from your current data, including versions and trash, and to confirm how deletions propagate to RGW.
File names, directory structure, shares, permissions, user accounts, group memberships, tags, activity records and app data remain in the Nextcloud database. Nextcloud needs this database to resolve any object in the bucket, so the database and the object store form one system and must be backed up and restored together. Metadata is small per file, but it grows with file count, sharing activity and audit logging, and it is queried constantly by the web interface and sync clients.
- File cache table: Every file and folder has a row that maps the user-visible path to its stored object.
- Shares and permissions: Share records and their expiry, password and access settings are stored here, not in RGW.
- Users and groups: Accounts from LDAP, OpenID Connect or SAML are represented here even when the directory is the source of truth.
- Activity and logs: Activity history and audit data grow over time and need their own retention decision.
- Database sizing: Plan the database around file count and concurrent users, not around total bytes stored.
Ask for the database engine version and the expected row growth per thousand files, and confirm which PostgreSQL or MariaDB version your Nextcloud release supports.
Primary object storage does not remove the need for local disk on the Nextcloud server. The application code, configuration, temporary files used during uploads and processing, caches and any data directory that Nextcloud still uses all live on the local filesystem. Treat the local volume as a separate sizing decision from the bucket, and plan it for the working set of the server rather than for the total stored data.
- Application and configuration: Program files and the config directory stay on local storage on each application node.
- Temporary space: Uploads and some processing steps need scratch space that is not written to the bucket.
- Caching: Redis and APCu caches, if deployed, use memory or local disk on the node or cache host.
- Shared state for clusters: If you run several Nextcloud nodes, confirm which paths must be shared and how they are provided.
- Backups of local data: Configuration and any remaining local data need their own backup job.
Confirm the exact local paths your version uses with your deployment method, and test that the server still starts and processes uploads after the object backend is enabled.
Splitting the data changes how you plan capacity. Ceph capacity planning and Nextcloud database planning become separate workstreams, and each has its own growth driver. A bucket that is full does not show the metadata side, and a database that is healthy does not show whether the bucket holds every object it should. Reviewing both together is what keeps the two in step.
- Ceph side: Size the RGW pool for stored content, replication or erasure coding overhead, and headroom for growth and recovery.
- Database side: Size for file count, share volume and concurrent sessions, and monitor table growth.
- Cross-check: Periodically compare database object references with bucket contents to catch orphaned or missing objects.
- Restore planning: A restore that brings back the database without the matching objects, or the reverse, leaves files unreadable.
- Cost drivers: Storage hardware, database hosting and staff time for reconciliation are the main components to quote separately.
Ask your implementation partner to show how they will verify that the bucket and database remain consistent after a restore.
How to move Nextcloud file storage to Ceph RGW
This sequence takes a Nextcloud instance from a planned Ceph RGW bucket to a verified primary object storage configuration, with the migration decision made before the setting is enabled. The output is a tested storage path that serves uploads, downloads and previews from the object store.
Create the RGW user and bucket
The Ceph administrator creates a dedicated RGW user for Nextcloud with S3 access keys, then creates a bucket that holds only Nextcloud file content. Keep the user separate from any other application, and confirm the bucket name, region value and endpoint URL in writing with the Nextcloud team before anything is configured. Done means the user's access key authenticates against the endpoint and the bucket is listed as empty and owned by that user.
Confirm the storage model with the team
Before editing any configuration, agree how the object store relates to the existing instance. Nextcloud keeps file names, directories and metadata in its database and places only file content in the object store, so the database and the object store must be treated as one unit for backup and restore. Record whether the instance is new or already holds files, because existing files become inaccessible once a primary object store is set. Done means a signed-off decision record names either a fresh instance or a planned data migration.
Test connectivity from every Nextcloud node
From each Nextcloud application node, and from any worker or cron host that runs Nextcloud PHP code, test that the endpoint resolves, that TLS validates against the trusted certificate chain, and that a put and get of a test object succeeds with the RGW credentials. Check clock synchronization too, because signed S3 requests fail when clocks drift. Done means every node completes the same test object round trip and the results are logged.
Choose a fresh instance or a planned migration
If the instance is new, proceed directly to configuration. If it already holds files, the team must plan how existing content reaches the object store and how the database references to file identifiers are preserved, because enabling the setting alone hides those files. Ask the Nextcloud and storage owners to agree the cutover window, a rollback path, and who runs and checks the migration. Done means the migration plan is written, reviewed and approved, and the rollback path has been stated.
Add the primary storage block to config.php
Only after the migration plan is agreed, the administrator adds an objectstore primary storage block to config.php, choosing the S3 or Swift class and setting the bucket, endpoint, region, path-style option, key and secret as documented for the Nextcloud release in use. Keep the secret out of shared configuration files where possible and restrict file permissions on config.php. Done means the configuration parses without errors and Nextcloud starts with the new block in place.
Run the migration and reconcile the database
Run the agreed migration against a snapshot or copy taken before the change, and reconcile the file identifiers in the database with the objects in the bucket. Take a full backup of the database and the data before this step, since the Nextcloud upgrade guidance treats backups as mandatory before any change of this kind. Done means a reconciliation report shows matching counts between database file entries and stored objects, with any exceptions listed and resolved.
Verify uploads, downloads and previews
Log in as test users on each Nextcloud node and verify that a new upload lands as an object in the bucket, that an existing migrated file downloads with the correct size and checksum, and that image and document previews generate and display. Repeat the checks through the web interface and the sync client. Done means every test case passes, the bucket contents match the test log, and the results are signed off before users are told the change is complete.
Why enabling it on an existing instance hides your files
Enabling primary object storage on a Nextcloud instance that already holds files makes those files inaccessible, because the existing content was written to local disk and the object store has no record of it. Nextcloud's primary storage documentation states that configuring a primary object store on an existing instance makes all existing files on the instance inaccessible. Nextcloud keeps file names, directories and metadata in its database and places only file content in the object store under unique identifiers. The database therefore still lists the files, but the content that the new configuration points to is not in the bucket. Treat the switch as a change to where new content lives, not as a configuration toggle you can reverse for live data.
Planners usually weigh three paths. The first is a new instance configured with object storage from the start, with file content and database data copied across in a controlled move. The second is a scheduled migration with a maintenance window, during which users are locked out while content is copied and the database is brought into line. The third is a fully reviewed restore path, in which a backup set is restored to a test environment, the object store configuration is applied there, and access is verified before anything changes in production. Each path needs a rehearsal and a rollback plan, and the duration of each depends on data volume, network throughput to the object store and how many file records must be reconciled. Ask for those estimates from the engagement scope rather than assuming them.
Before any work starts, confirm the exact copy, database and configuration steps for your Nextcloud version against the Nextcloud primary storage documentation, and confirm the upgrade and backup prerequisites in the Nextcloud upgrade manual, since the move must not coincide with a major version change. Agree in writing who owns the database snapshot, who validates file access for sample users and what evidence confirms that every file record resolves to stored content. If the documentation for your version does not describe a supported in-place conversion, assume that the safe path is a new instance and a copy.
Single bucket or multi-bucket layouts
Nextcloud's object storage backend writes file content to whichever bucket you configure, so bucket count is a design choice made before go-live. The cards below set out the trade-offs for isolation, quotas, operations and Ceph placement, and what to confirm in your Nextcloud version.
Isolation between groups or tenants
A single bucket keeps all Nextcloud file content in one namespace, with access controlled by the single RGW user that Nextcloud authenticates with. Separate buckets, each with its own credentials, let you separate departments, customers or sensitivity levels so one group's keys cannot read another's content. Confirm whether your Nextcloud version lets you assign a different bucket or credential to each group or instance before you design around it.
Per-bucket quotas and lifecycle
Quotas and lifecycle rules are set per bucket in RGW, so a bucket per group gives you a separate limit and retention policy for each. Since Nextcloud stores only opaque content identifiers in the object store, a lifecycle rule that removes objects directly would break file access, so any expiry logic must be tested against Nextcloud's own deletion behavior. Ask Nextcloud support and your RGW administrator to confirm how quotas interact with Nextcloud user quotas.
Operational overhead of more buckets
Each additional bucket adds a configuration entry, a credential to rotate, monitoring to watch and a backup scope to define. Mapping users to buckets is also a Nextcloud configuration task that must be repeated on upgrades and reviewed when groups change. Keep the bucket count to the number of isolation or policy boundaries you can name and maintain.
Credential sprawl and key handling
Every bucket needs its own RGW user and access key pair, stored in the Nextcloud configuration file. More buckets means more secrets to protect, rotate and audit, and a leaked key may expose a larger set of files if one bucket is shared across groups. Plan where the keys live, who can read the configuration, and how a rotation is applied without an outage.
Placement planning in Ceph
Bucket choice interacts with Ceph placement because RGW stores bucket data in pools mapped through its placement targets, and those pools follow the CRUSH rules and failure domains you set. A single high-volume bucket concentrates write load on one set of placement groups, while several buckets can be mapped to pools with different media or replication. Confirm with your Ceph design how RGW placement targets will be defined before creating buckets.
Nextcloud behavior to confirm
The multi-bucket behavior of Nextcloud is version dependent, and the primary storage documentation does not settle every case for you. Before committing, test in a non-production instance: create two buckets, confirm that files land in the expected bucket, check how users and groups map to storage, and verify that a restore from backup returns files to the correct location. Record the results against the Nextcloud version you plan to run.
Data and identity mapping between Nextcloud and RGW
This table maps each Nextcloud item to the system that stores it once primary object storage is enabled, so you can see what RGW holds and what the Nextcloud database still needs. Read it as a checklist for backup scope, access control and troubleshooting, since losing either side breaks file access.
| Item | Where it is stored | What it means for you |
|---|---|---|
| File content | Object in the RGW bucket, addressed by a unique identifier | Bucket loss or corruption removes file bytes, so RGW replication or backup must cover the bucket itself |
| File names and directory structure | Rows in the Nextcloud database | Database loss leaves objects present in RGW but unreachable by name, so the database backup is equally critical |
| File metadata and sharing rules | Nextcloud database tables | Share links, tags and permissions are not recoverable from the bucket alone |
| Bucket and access key settings | Keys in config.php | Changing bucket or key values without a plan can make existing files inaccessible, so record them in change control |
| User accounts and login | Nextcloud accounts, sourced from LDAP, OpenID Connect or SAML | Users sign in to Nextcloud, not to RGW, so disabling a directory account blocks Nextcloud access without touching RGW |
| Storage credentials | RGW users and their S3 access keys | These keys only let Nextcloud read and write objects; they do not map to individual Nextcloud users |
| Per-user storage visibility | Nextcloud, not RGW | RGW cannot show which Nextcloud user owns a given object, so audit trails for file access come from Nextcloud logs |
How backups change when file content leaves local disk
Once file content lives in Ceph RGW, a backup is no longer one copy of one data directory. The database, the configuration and the object store each hold part of the instance, and they must be captured as a consistent set. The cards below cover what each part holds, how to keep them aligned and what to confirm about your backup tooling.
Database holds the file map
The Nextcloud database keeps file names, directories, sharing rules and metadata, and it points each file at an object identifier in the store. Without the database, the object data is a pile of unnamed blobs. Confirm that your database backup runs on a schedule you can restore from and that you can restore it to a version matching the Nextcloud release in use.
Config holds the storage credentials
The object store endpoint, bucket and access keys are defined in the instance configuration file. A backup of the data without this file cannot tell Nextcloud where the objects are. Store the file in your backup set, and keep credentials in a secrets system if your policy requires it, so a restore does not depend on a file that only exists on one server.
Object store needs its own copy
Ceph RGW can be protected with its own replication or erasure coding, but that protects against drive and host loss, not against deletion or corruption that Nextcloud propagates. Decide whether bucket versioning, a separate backup target or Object Lock applies to your buckets, and confirm the RGW features your Ceph release supports before you rely on them.
Keep database and objects consistent
A database snapshot taken at one moment and an object copy taken at another can disagree about which files exist. Nextcloud can be placed in maintenance mode during a full backup, or you can take the database dump and the object snapshot in one defined window. Test a restore of both together, because a mismatch often only appears when a user opens a file.
Confirm how your tool handles external storage
Backup tools differ in whether they read the object store directly, copy the data directory or skip external storage altogether. Ask your vendor or check your tool's documentation for how it treats S3 primary storage, whether it captures object data at all, and how long a full restore takes. This is a decision for your team to confirm, not one this page can settle for you.
Back up before every upgrade
Nextcloud's upgrade guidance says to back up before every upgrade, and it allows only one major version at a time. Each upgrade therefore needs a fresh, verified set covering all three parts. Plan the backup into your upgrade runbook, and record the restore steps alongside the upgrade notes so a failed upgrade can be reversed.
Common failures when Nextcloud reads from RGW
This table pairs each common failure with its likely cause and a verifiable check, so you can narrow down problems between Nextcloud, the database and the RGW endpoint. Read it top to bottom when a rollout misbehaves, and treat each check as a pass or fail test before changing configuration. The main takeaway is that most failures trace to a small set of causes: a wrong assumption about existing files, addressing style, certificate trust, or a database and bucket that no longer agree.
| Failure | Likely cause | Verifiable check and fix |
|---|---|---|
| Existing files missing after enabling primary storage | Primary object storage was configured on an instance that already held files, so Nextcloud looks for content in the bucket where it does not exist | Confirm the instance was new when the store was set. If it was not, restore the original local storage configuration and plan a migration instead of switching in place |
| S3 authentication errors (403 or signature mismatch) | Access key or secret mismatch, a wrong region value, or a user without read and write rights on the bucket | Test the same key pair with an S3 client against the bucket from the Nextcloud host, then confirm the bucket policy grants the object actions Nextcloud needs |
| TLS trust failures on the RGW endpoint | The RGW certificate is issued by an internal CA that the PHP runtime does not trust, or the hostname does not match the endpoint | Run an HTTPS request from the Nextcloud host with the same CA bundle PHP uses, and confirm the certificate subject matches the configured endpoint hostname |
| Path-style versus virtual-host addressing mismatch | The client expects bucket names in the hostname, but the RGW endpoint or DNS only resolves path-style URLs, or the reverse | Set the addressing style to match your RGW DNS design, then list the bucket with a single test request before reopening user access |
| Timeouts on large uploads | Proxy or load balancer limits, short PHP or client timeouts, or multipart uploads interrupted by a single slow gateway | Compare timeout values in the reverse proxy, PHP and the S3 client, upload a file near your largest expected size, and check RGW logs for aborted requests |
| Database and object store drift after a partial migration | The database holds file identifiers that the bucket no longer has, usually after a failed copy or a rollback that did not clean up both sides | Compare file counts and a sample of identifiers between the Nextcloud database and the bucket, and run Nextcloud's file integrity checks before any further migration step |
Questions teams ask before enabling Ceph RGW for Nextcloud
How much effort and cost does moving Nextcloud to Ceph RGW involve?
Effort depends mostly on scope and the volume of file data already on the instance, not on the Ceph setup alone. The main cost components are the Ceph bucket and key work, the change to Nextcloud's primary storage configuration, the data move for existing files, testing, and the backup changes. Each of these is paid as project time, so the quote should break them out separately. One-time work covers the migration and validation. Recurring costs come from operating the Ceph cluster, running Nextcloud, and any support retainer you choose. Ask any partner to state which items are fixed in a written scope and which depend on measured data volume.
How long does a Nextcloud object storage migration take?
No duration can be given in general terms because it depends on how much file content exists, how fast your network and RGW gateways move objects, and how long your maintenance window allows. Plan the timeline from your own tests: copy a representative sample of files to a test bucket, measure transfer rates, then extrapolate to the full data set. Include time for verification, rollback rehearsal and the backup sign-off. Ask any partner to base the schedule on these measurements rather than on a generic estimate.
Can an internal team enable Ceph RGW for Nextcloud alone?
Yes, a capable internal team can do this, provided it has experience with Nextcloud administration, Ceph RGW and the database. The critical risk is the documented behavior that configuring a primary object store on an existing instance makes all existing files inaccessible, so the file content must be moved and the configuration switched in a controlled sequence. Teams without a tested rollback plan, or without staff who can run the Nextcloud upgrade path, often choose an external partner for the cutover. Decide based on your skills, your change-control rules and how many people can take the window.
What does the work need from our team?
The work needs access and decisions from several groups. Database access is required so the metadata in the Nextcloud database can be checked against the object store state. Your storage team must create the RGW bucket and access keys, and must confirm the endpoint, TLS setup and network path. Your operations team should agree a maintenance window with users, and your backup owner must review and sign off the backup approach before the cutover. Name one person who can approve changes during the window.
Does Nextcloud Enterprise change the picture for an RGW deployment?
Nextcloud Enterprise is a paid offering from Nextcloud GmbH alongside the open source community version, and it does not change the technical steps for enabling S3 primary storage with Ceph RGW. Its listed tiers are Standard, Premium and Ultimate, sold with a 100-user minimum, with list prices starting at 71.29, 104.99 and 204.75 euros per user per year respectively for 100 or more users, and lower rates from 200 users, according to Nextcloud's pricing page. Standard includes one year of maintenance, Premium adds a maintenance lifecycle of five or more years, and Ultimate adds support up to 24/7. Confirm current prices and terms directly with Nextcloud, since these are list prices.
How do Nextcloud upgrades interact with the storage configuration?
Upgrades must be planned together with the storage configuration because Nextcloud does not allow skipping major releases, so you must move through one major version at a time. Back up before every upgrade, and disable third-party apps until they are confirmed compatible. Check that the object store settings, the bucket access, and the RGW endpoint still work after each step, and test a restore from the object store backup. Keep the Ceph and Nextcloud upgrade schedules in one plan, since Nextcloud's own release cadence and Ceph's support windows differ. Follow the Nextcloud upgrade manual for each step.
Should we review our backups before changing primary storage?
Yes, review backups before any change, because the database and the object store now hold different parts of each file. The Nextcloud database keeps file names, directories and metadata, while the object store holds only file content by unique identifier. A backup must capture both sides at a consistent point, and a restore must be tested against both. Ask your backup owner to sign off on the restore procedure, the retention of the old local copy, and the RGW replication or backup approach before cutover.
How DeployOpen scopes and delivers this integration
DeployOpen approaches Ceph RGW as Nextcloud primary object storage as a planned change to a running service, not a configuration toggle. We agree the scope in writing first, then build and test the object store path alongside your existing Nextcloud instance, and hand over documentation and runbooks your team can operate.
How we scope
- Engagements are fixed-scope, with the written scope fixing deliverables and timelines before work starts.
- We record which Nextcloud instances, users and existing files move to the object store, and which stay put.
- We confirm the Nextcloud version, database and PHP versions, and whether any third-party apps need checks first.
- We document the target bucket layout, whether one or several buckets are planned, and the Ceph RGW endpoint details.
How we build
- We configure the S3 or Swift primary storage backend in a staging copy of your Nextcloud instance before production.
- We plan a migration path for existing files so they remain reachable before the object store is enabled.
- We test uploads, downloads, sharing, previews, and file versions against the Ceph RGW bucket in your environment.
- We set up backup changes so the database, configuration and object store are protected together and restore tests are run.
How we hand over
- You receive the written configuration, bucket and credential layout, and the migration steps used during the build.
- Runbooks cover adding buckets, rotating RGW access keys, and restoring from the paired database and object store backups.
- We document the upgrade sequence for future Nextcloud major releases, including backups and app compatibility checks.
- Handover includes a walkthrough with your administrators so they can operate and verify the integration after delivery.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers agreed separately from the build scope.
- A retainer can cover monitoring of the object store path, periodic restore tests, and Nextcloud patch releases.
- Support scope for Nextcloud Enterprise tiers, if you hold a subscription, should be confirmed with Nextcloud GmbH directly.
- Ask us to confirm the support hours and response commitments in writing before signing any retainer.
