Nextcloud

Cristal 0.9+ 

 This backend exists since 0.9

Table of Content

• Nextcloud deployment
• CORS Configuration
• Authentication Setup
  • Create an app password
  • Configure authentication server
• Other configurations
  • Set the root location

Nextcloud deployment

An easy way to deploy Nextcloud locally is to use docker compose, you can for instance use the docker-compose.yml file below.
Once the nextcloud server started, you can access it on http://localhost:9292/.
Use mariadb for the database, with db:3306 for the host, nextcloud for the user, nextcloud for the database and ADMINPASSWORD for the password.

version: '2'

volumes:
  nextcloud:
  db:

services:
  db:
    image: mariadb:10.6
    restart: always
    command: --transaction-isolation=READ-COMMITTED --log-bin=binlog --binlog-format=ROW
    volumes:
      - db:/var/lib/mysql
    environment:
      - MARIADB_ROOT_PASSWORD=ROOTPASSWORD
      - MARIADB_PASSWORD=ADMINPASSWORD
      - MARIADB_DATABASE=nextcloud
      - MARIADB_USER=nextcloud

  app:
    image: nextcloud
    restart: always
    ports:
      - 9292:80
    links:
      - db
    volumes:
      - ./html:/var/www/html
    environment:
      - MARIADB_PASSWORD=ADMINPASSWORD
      - MARIADB_DATABASE=nextcloud
      - MARIADB_USER=nextcloud
      - MARIADB_HOST=db

CORS Configuration

Using the Nextcloud backend without any additional configuration will lead to CORS errors when Cristal is running on a different domain.
To allow Cristal to access a remote Nextcloud instance, follow the instructions below:

1. Install https://apps.nextcloud.com/apps/webapppassword
2. Go to the WebAppPassword section of the administration
3. In the Allowed origins for webdav field, add the domain of the Cristal instance

Authentication Setup

Cristal 0.16+ 

Authentication is supported since 0.16

The Nextcloud backend comes with two different instances of AuthenticationManager:

• Nextcloud/basic, using basic authentication with a login and a password (which can be an app password)
• Nextcloud/oauth2, relying on a OAuth2 client (which requires a working authentication server)

You need to choose which one to use for your configuration by setting the key "authenticationManager". E.g.,

{
  "NextcloudOAuth2": {
    "authenticationManager": "Nextcloud/oauth2"
  },
  "NextcloudBasic": {
    "authenticationManager": "Nextcloud/basic"
  }
}

Create an app password

When using basic authentication, it is recommended to use a revocable app password instead of your actual password. To do so, you can generate one on a Nextcloud instance by going to your personal settings, in the "Security" category:

Under "Devices & sessions", you will see the prompt to create a new app password:

You can then use this password to login in Cristal, and revoke it when you no longer use it or want to renew it.

Configure authentication server

If you want to use OAuth2 authentication, you will need to first create a OAuth2 client on your Nextcloud instance. As an administrator, go to the "Security" category:

Under "OAuth 2.0 clients", you will see the prompt to create a new client:

You will then need to set-up an authentication server.

Cristal provides an authentication server for Nextcloud through the module authentication-server. You need to input the Client ID and the Client Secret of your OAuth2 client in its configuration file (authentication-server/src/config.ts):

const config = {
  nextcloud: {
    OAUTH2_AUTHORIZE_PATH: "/index.php/apps/oauth2/authorize",
    OAUTH2_CLIENT_ID: "<Enter your Client ID here>",
    OAUTH2_CLIENT_SECRET: "<Enter your Client Secret here>",
    OAUTH2_TOKEN_PATH: "/index.php/apps/oauth2/api/v1/token",
  },
};

By default, when running Cristal in dev mode with pnpm, or the Electron build, the server is started on http://localhost:15682. If you start Cristal in another way, you will need to start the server yourself:

nx dev @xwiki/cristal-authentication-server

Make sure that your Cristal configuration for your Nextcloud instance includes the key authenticationBaseURL and that it points to your running server.

Other configurations

Set the root location

The root location can be set through the configuration key "storageRoot". It will be appended directly to the configured "baseRestURL". The defaults are:

{
  "Nextcloud": {
    "baseRestURL": "http://localhost:9292/remote.php/dav",
    "storageRoot": "/files/${username}/.cristal"
  }
}

Where ${username} gets replaced automatically by the user's username after it logged in. This ensures that they will access their personal space, but you can omit it if you want your configuration to, e.g., target a public space instead.