Decision: Nextcloud sharing

Status: Problem Clear
Assignee: Peter Mrkonjic
Date: 24.04.2026

Problem

When creating maps, users can select a base layer image from a predefined set. They can also upload their own base layer images and additional images to Nextcloud. Map collaborators should be able to access these images and upload their own.
Additionally, the PermaplanT team requires a dedicated Nextcloud structure for sharing internal files and documents that should not be accessible to other users.

Currently, the base layer images folder (incl. the base template files) is automatically created for each new user via the skeleton folder. However, this approach is not ideal, as it results in the duplication of the same folder structure and files for each newly created user. Additionally, any changes made to the skeleton folder (e.g. adding a new base layer image) will not be updated for existing users. Uploaded images are not shared among map collaborators, which leads to inconsistent access and unnecessary duplication of data.
The PermaplanT team currently uses a nextcloud circle to share documents internally, which appears to sometimes not be working as intended (e.g. some users need special rights to even see the folder).

Constraints

Users do not need to interact with Nextcloud manually.
Every user needs to have access to the default baselayer images.
Updates to the base layer images folder should be visible to all users.
Base layer images must be separated from other pictures/icons.
Shared images must only be available to other map collaborators.
Removed collaborators need their folder access removed.
Shared folders need specific subfolders.
- Needed to cleanly differentiate between different types of files.
- For example Map1/BaseLayerImages and Map1/Icons.
Skeleton folder only contains what is strictly needed.
The PermaplanT team requires a dedicated private folder for internal file sharing.
Needs to support 30.000 maps/users/folders.

Assumptions

The Nextcloud Team Folders (Group Folders) app is available, stable, and can be used in production.
Base layer images are relatively static and can be managed centrally.
Users may upload additional images that should remain scoped to map collaborators only.
Folder permissions (read/write) can be enforced reliably by Nextcloud.

Solutions

Alternative A: Team Folders App

Description
For this approach we will use the Team Folders (former Group Folders) app from Nextcloud. Everything described below can only be done by an account with admin rights.
To handle the public file sharing a new team called Public will be created. Every existing and newly created user will be automatically added to the Public team via Keycloak configuration.
Team members will have read-only access to a new folder called Public. The folder will appear in a users root directory and will contain a subfolder called BaseLayerImages, that contains the template baselayer images. Other subfolders can be added as needed.

We will use the Team Folders (former Group Folders) app from Nextcloud to handle the dev team file sharing. A new team called Developer will be created. Every existing and future team member will be automatically added to the Developer team via Keycloak configuration.
Team members will have access to a new folder called PermaDev in their root directory.

We will use the Team Folders (former Group Folders) app from Nextcloud to handle the file sharing between map collaborators.
We will create a folder called Maps (or All Maps), that the Public team will have read-only access to. For each map a sub folder will be created. The name of the sub folder will be the same as the map name.
If a map is public it will simply appear as a read-only sub folder for the Public team (all users). By enabling the "advanced permissions" (ACLs) setting on the Maps folder we can, however, give the map creator full access to the sub folder.
If a map is private or shared between a group of users we will, aside from creating the sub folder, also create a new team with the same name as the map. Map collaborators can then just get added/removed from the team. By enabling the "advanced permissions" (ACLs) setting on the Maps folder we can give the newly formed team full access to the sub folder, while removing all rights from the Public team.

Additional Information

When 30,000 users are constantly opening and viewing map images, Nextcloud has to create millions of temporary "file locks" to keep data safe from corruption. By default, the main database (MySQL or MariaDB) handles all that on the hard drive, which can cause severe performance issues.
Redis, a completely free, open-source tool can be used to solve this problem. It handles all these temporary locks and permission checks directly inside the server's RAM, which takes the heavy load off MariaDB. It should not be too hard to set up in our environment and would need 2GB–4GB server memory to work.

Pros

Access is centrally managed.
No file duplication.
Supports 30.000 teams/folders.
- Tested locally with 10.000 users and 30.000 team folders.
Folders stay, even if owner gets deleted.
Permissions can be set.

Cons

Needs admin rights.
Team creation takes longer with each team.
- Locally team creation jumped from 468.8 ms (5 teams) to 4391.49 ms (30.000 teams)
Maintaining such a huge and complex team folder structure will almost certainly slow the system down with our current server setup.
Anything uploaded counts towards folder quota and not user quota.
- Folder has a set amount of available space (e.g. 5 MB).
- Anything uploaded inside the folder counts toward that space.
- It does not matter who uploads, the folder size will cap at the set limit.
Folder appears in root folder.

Description

For this approach we will use the direct share feature on Nextcloud. The Team Folders (former Group Folders) app from Nextcloud will still be needed for this approach.
By default, every directly shared folder will be placed inside a users root directory. By adding the line 'share_folder' => '/Shared', inside the config.php file, every file directly shared with this user will be placed inside a folder called Shared. The folder will be automatically created if something is shared with the user.
To handle the public file sharing a new team called Public will be created. Every existing and newly created user will be automatically added to the Public team via Keycloak configuration.
An admin account will create and direct share a Public folder with the Public team. Team members will have read-only access to the new folder. The folder will appear inside a users Shared folder and will contain a subfolder called BaseLayerImages, that contains the template baselayer images. Other subfolders can be added as needed.

We will use the direct share feature on Nextcloud to handle the dev team file sharing. A new team called Developer will be created. Every existing and future team member will be automatically added to the Developer team via Keycloak configuration.
An admin account will create and direct share a PermaDev folder with the Developer team. The folder will appear inside a users Shared folder.

We will use the direct share feature on Nextcloud to handle the file sharing between map collaborators.
We will add a folder called MyMaps to Nextclouds skeleton directory. This way every newly created user will have a folder called MyMaps inside his root directory.
For each map a sub folder will be created inside MyMaps. The name of the sub folder will be the same as the map name. If a map is public we will create a public link for the sub folder. Anyone, even outsiders, will be able to see the folder via this public link. The folder will not appear inside the Shared folder for other users. It can only be seen and accessed via this link. To make everything work in the backend the token of the link needs to be saved in our database.
If a map is private or shared between a group of users we will simply direct share with the users of the group. For other users it will appear inside their Shared folder. Map collaborators can then just get added/removed from the direct share.

Additional Information

It is important to note that with standard user-to-group sharing, users can accidentally click "Unshare" or remove the folder from their personal file list. So they could accidentally remove themselves from having access to the Public folder. This can be fixed by manually removing the block/exclusion rows from the Nextcloud database. Nextcloud also allows administrators to inject custom CSS directly into the web interface using the free Custom CSS App (found in the Nextcloud App Store). By finding the specific HTML class of that button, we could simply hide this button for everyone.

Instead of direct sharing the Public folder with all users via the Public team, we could also use the public link feature here. If we don't need the Public folder to appear in users directories, we could simply create a public link to it, which would save database performance. We could then put the link inside a README file, which we add via skeleton directory.

Pros

Less admin overhead (all done by user).
No file duplication.
Supports 30.000 users/folders.
- Tested locally with 10.000 users and 30.000 shared folders
More flexible/lightweight.
- No need to create and manage teams or groups.
- Sharing can be configured directly per folder.
- Easier to add/remove collaborators dynamically.
Permissions can be set.
Anything uploaded counts towards owners quota.
Allows "Public Link" to share with outsiders.

Cons

No central management.
- No place to overview all map folders.
- Admin won't have access to folders, unless explicitly shared by users.
Folders get deleted, if owner gets deleted. (Note: Hannes didn't see it as con: If the owner gets deleted, their maps get deleted. And since image uploads to these maps only exist within the map, the collaborator isn't really impacted by this because the maps are only a part of a specific map.)
Folders can be reshared by other users (can be disabled in settings).
Users can remove themselves from shared folders and it can require admin effort to get their access back.

Alternative C: Combined Approach

A combined approach can be created by using specific parts of both alternative A and alternative B.

Decision

Rationale

Redis

Notes

Hannes wrote: I prefer B because it is much more privacy-focused (admin can't see uploaded images) and the pros vastly outweigh the cons. And since I as a user would hate to give admins access to my privately uploaded images, the con of "no place to overview all map folders" isn't a disadvantage at all - it gives users much more privacy.

The restrictions of A make a public base layer image folder unusable for users.

Peter wrote: I prefer B, since it seems to be the more performant and overall easier to implement approach.