Collectives app documentation re-write

User Documentation - Getting Started

This tutorial will walk you through the collectives app in less than 10
It assumes you already have a user account on a nextcloud installation
with the collectives app enabled.

:sparkles: Create a new collective

Visit the collectives app by clicking its icon in the toolbar at the top
of the screen:


On the left of the screen you will find a list of all of your
It’s probably empty if you have not been added to any yet.
Click “Create new collective” and type a name for your collective.
You can also pick an emoji to easily find your collective later:

Screencast of clicking the "Create new collective" button

:seedling: Bring life to your collective

Create pages and share the knowledge that really matters.

Click the “Create a Page” button in the upper left
and a new page will appear.

You can type in a title right away or add some content first
and settle on a title later.

:couch_and_lamp: Edit the landing page to feel like home

When you create a new collective, it will start with some initial content.
Push the pencil button on the top left of the start page :arrow_upper_right:
to adjust it to your collectives needs.

:paw_prints: Add your comrades to the collective

Follow the “manage members” link that you find in the action menu inside
the collectives list on the left to manage members.

If your Nextcloud instance is configured to allow groups in circles
you can even add entire groups to your collectives.

Also good to know

  • Multiple people can edit the same page simultaneously.
  • Link local pages by selecting text and choosing “link file”.
    Drag & drop from page list into the editor also works.
  • Add templates for future subpages (“Show templates” → “Add template for subpages”)
  • Ask the community for help in case of questions.

Administrator Documentation

Runtime Dependencies

This app requires the following apps to be enabled:

Install Nextcloud Collectives

The Collectives app can be installed from the Nextcloud App Store.

In your Nextcloud instance, simply navigate to »Apps«, find the
»Collectives« app and enable it.


Initial Content for new collectives

It’s possible to create custom content for new collectives by putting files
in the app skeleton directory at data/app_<INSTANCE_ID>/collectives/skeleton.
New collectives start with the contents of this directory.

Create a to change the landing page that is opened automatically
when entering a collective.

If the skeleton directory doesn’t contain a, the default landing
page from apps/collectives/skeleton/ will be copied into the
collectives directory instead.

Allow for groups in your collectives

You can configure the circles app to allow adding groups to circles.
Since the collectives app relies on the circles app for user management
this also allows adding entire groups to collectives.

Keep in mind thought that in contrast to circles
groups can only be managed by server admins.

Developer Documentation

Build-time Dependencies

The following tools are required for app development:

  • make: to run the Makefile targets
  • curl: to fetch some build tools from the web
  • npm: to install NodeJS dependencies and compile JS assets
  • g++: to compile some NodeJS dependencies
  • gettext: to generate pot/translation files
  • rsync and openssl: for generating release tarballs
  • composer for installing php dependencies
  • nextcloud server: for running php tests
  • circles app: for passing some php tests that depend on it.

Developer installation

To install the app manually:

  1. Install a development setup of nextcloud.
  2. Clone this into the apps folder of your Nextcloud
  3. Install build tools and dependencies by running make setup-dev
  4. Compile NodeJS assets by running make build
  5. Install the circles app in Nextcloud.

Afterwards, you can enable the app from the Nextcloud app management menu.

Running tests

With the app available in the Nextcloud app management
you should be able to run the unit tests with

make test-php-unit

In order to run the integration tests you either need to configure your
nextcloud to run with https and be availabe at https://nextcloud.local
or you need to change the default config for behat in
to use a different baseUrl.

Then you can run them with

make test-php-integration

The integration tests rely test data installed to the server.
This is available on our docker image or in the
nextcloud-docker-dev repo.

Development environment

Development environments often do not use proper hostnames and are not
using ssl. In order to make the Circles API work in such environments,
a few configuration settings need to be adjusted.

You can do so by running the following commands on the nextcloud server:

./occ config:system:set --type bool --value true -- allow_local_remote_servers
./occ config:app:set --value 1 -- circles self_signed_cert
./occ config:app:set --value 1 -- circles allow_non_ssl_links
./occ config:app:set --value 1 -- circles local_is_non_ssl

Important developer links

Development Background: Collective ownership

Usually, in Nextcloud every file/folder is owned by a user. Even when shared,
the ultimate power over this object remains at the owner user. In collective
workflows, this leads to several problems. Instead of individual users,
we want the collective pages to be owned and maintained by the collective.

That’s why the Collectives app implements an own storage and uses mountpoints
to mount the collective folders to members home directories.

Development Background: Circles integration

Every collective is bound to a circle. Currently, the app automatically creates
a new secret circle with every new collective.

Prepare a release

Dependencies for building a new release:

  • Nextcloud OCC at ../../occ and required PHP dependencies
  • App certificate+key for signing the app at ~/.nextcloud/certificates

Releasing a new version contains the following steps:

  • Update
  • Bump version in appinfo/info.xml
  • Make sure the Gitlab CI passes
  • Build the JS assets from a clean state:
    npm ci
    make clean
    make build-js-production
  • Copy files to release directory, sign files and pack them in a release tarball:
    make release
  • Upload release tarball to Gitlab, add release tag and publish releas on Gitlab
  • Publish new app version in Nextcloud App Store

Backport changes to stable21 branch

App development happens in the main branch. Since the circles integration
changed between Nextcloud 21 and 22, he currently maintain a stable21 branch
for Nextcloud 20+21 and backport all changes to this branch before doing a new

The last backported commit is tagged as backported. In order to backport all
subsequent commits and prepare the stable21 branch for a new release, do the

  1. Backport commits since backported:
    git checkout origin/main -b backport/stable21
    git rebase --onto stable21 backported -i
    git push origin backport/stable21
    git tag -d backported
    git push origin --delete backported
    git tag backported origin/main
    git push origin --tags
  2. Create a merge request from backport/stable21 to stable21. Merge after
    pipeline succeeds.
  3. Remove temporary branches:
    git branch -D backport/stable21
    git push origin --delete backport/stable21

Update javascript dependencies

Update all dependencies right after a release
so they will be tested for a while before the next release.

After installing npm-check-updates with

npm install npm-check-updates --no-save

List all outdated packages with npm run npm-check-updates
and then update all of them with the -u option.

Roll back updates that break the build with

npm install package@^1.2.3

Note in the commit message why packages rolled back to an earlier version.
This information makes the next version update easier.

1 Like

Collectives team would like our community help in updating the app documentation so it can migrate from their Gitlab to (afaik). Your help is appreciated! It needs love.



Content from is located at GitHub - nextcloud/documentation: 📘 Nextcloud documentation

Correct, but that isn’t what we are talking about.

The idea is to collaboratively edit this documentation here on the forum, before it is pushed to github as a pull request on that repository.

Ok, maybe I think to technically.
This forum uses topics written in kind of a markdown style.
The docs at GitHub are based on Welcome — Sphinx documentation and so it is not possible to transfer the work by creating a PR.

Formatting here is effectively the exact same as they already have on their Gitlab. If you want to contribute on the re-write, please do!

Hi y’all,

Thanks a lot for looking into this.

I think there are two issues here and it might be helpful to separate them:

  1. The docs are outdated and do not reflect the current state.
  2. We currently host our docs on gitlab pages which we want to migrate away from.

I think 1. is what this post is trying to solve. Any help with this would be highly appreciated.

With respect to 2. we have not completely settled on where we want to migrate and how best to handle this. seems like a natural fit - at the same time collectives is not part of the default installation and it’s not clear to me if is a good place for documenting featured apps. However it does have translations which is awesome.

Got any hints on which parts to re-write or add / remove?

1 Like

I think it would be good to focus on the user documentation first. I just reread it and it’s still accurate - it just has not been updated since 0.11 releases. So I think going through the features since 0.12 and adding documentation for those that seem relevant would be great.

This would probably be easiest looking at the release notes for versions on Nextcloud 22 as that had all releases from before 0.12 to 1.5.0. From 1.0.0 on features were only added in the minor release versions (1.1.0) not in the patch versions (1.1.1).

Documentation for the app users (#100) · Issues · collectivecloud / Collectives · GitLab also lists a few things we originally wanted to add to the user docs.

Developer docs are also very much outdated i think - but it might be best for developers to tackle those.

1 Like