Nextcloud

From Organic Design wiki

Nextcloud is a kind of personal Dropbox solution which is completely free and open source. There are many add-on applications available such as calendar, tasks, chat and collaborative file editing.

Installation

LOOL.jpg

This is our procedure for installing Nextcloud and LibreOffice Online on a Debian-based server. LibreOffice has included a component to allow it to be served over HTTP since version 5.3 but to use it you need to integrate it with a cloud file system that supports it. Nextcloud which is a brilliant groupware suite in its own right supports LibreOffice Online and integrates perfectly with it.

I'm following the instructions created by Collabora and Nextcloud from here, and more specifically the Nginx variation here. I'm documenting here my specific configuration to include the LetsEncrypt and other specific configuration aspects that are out of the scope of those instructions so that we have a more easily reproducible procedure.

I'm using the office.organicdesign.host domain here which you'll need to change for your own purposes.

Set up the server

Bring the machine up to date and install the following dependencies.

apt install git net-tools apt-transport-https locales-all letsencrypt \
            mariadb-server redis-server nginx python3-certbot-nginx \
            php-fpm php-mysql php-redis php-zip php-gmp php-curl php-mbstring \
            php-xml php-apcu php-imagick php-gd php-intl php-bcmath

Configure the web-server and SSL certificates

In the Nginx configuration for this site, add a basic block for handling non-HTTP requests as follows. This will allow the LetsEncrypt domain validation requests to pass, but all other requests will be bounced to their respective HTTPS counterparts.

server {
	listen 80;
	listen [::]:80;
	server_name ~^;
	rewrite ^/\.well-known $uri last;
	return 301 https://$server_name$request_uri;
}


We can now install LetsEncrypt.

cd /var/www
git clone https://github.com/certbot/certbot.git letsencrypt


And then run it to make our certificates, after it has successfully created them add the command to be called from crontab daily.

letsencrypt/letsencrypt-auto certonly -q --keep --renew-with-new-domains --expand --webroot -w /var/www --agree-tos \
    --email "admin@organicdesign.host" -d office.organicdesign.host


Now create /var/www/nginx.ssl.conf with the following content that will be included from all SSL blocks. You'll need to replace the certificate paths with the ones that LetsEncrypt created for you. This block uses a set of secure cyphers suggested by SSLlabs, see SSL for more details.

ssl on;
ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers EECDH+ECDSA+AESGCM:EECDH+aRSA+AESGCM:EECDH+ECDSA+SHA256:EDH+aRSA:EECDH:!RC4:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS; # SSLlabs
ssl_prefer_server_ciphers on;
ssl_session_timeout 5m;
ssl_session_cache shared:SSL:10m;
ssl_dhparam /var/www/dhparams.pem;
ssl_certificate /etc/letsencrypt/live/office.organicdesign.host/fullchain.pem;
ssl_client_certificate /etc/letsencrypt/live/office.organicdesign.host/chain.pem;
ssl_certificate_key /etc/letsencrypt/live/office.organicdesign.host/privkey.pem;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;


Don't forget to create the strong Diffi-Hellman parameters which we referred to in nginx.ssl.conf.

openssl dhparam -out /var/www/dhparams.pem 2048

Install and configure Nextcloud

Nextcloud is a "drop-box" style web-application which is completely open-source so you can install it on your own server, and it has built-in integration for working with LibreOffice Online. Nextcloud is PHP so first download the source and unpack it into /var/www/nextcloud, ensure it's accessible by www-data, and then add the Nginx configuration recommended here. In this configuration we need to adjust the domain names and delete the port 80 block since we have an existing one described above to handle LetsEncrypt domain validation requests. Also remove the SSL lines and replace them with an include of the nginx.ssl.conf we made above.

A database and user will need to be created and then you can run through the install by going to the files.organicdesign.host domain. After you've successfully installed Nextcloud, go to the admin updater to check for any problems or optimisations and upgrade to the latest stable version.

  • I changed the URL in config/config.php to https
  • I noticed the install had used the wrong DB user once so may need editing in config.php
  • I removed the upstream block and used unix:/run/php/php7.0-fpm.sock directly for the fastcgi_pass parameter

Install LibreOffice Online

We now need to add a reverse-proxy block into our Nginx configuration, you can use the block from the instructions here (see below for Docker instructions). Adjust the server_name parameter to the domain you're using and replace the SSL directives with an include of the nginx.ssl.conf we created above.

Note: If you're using the same domain for both Nextcloud and LOOL, you need to put the LOOL Nginx server block contents inside the Nextcloud block, see this for example.

From the Docker image

By far the simplest method is to use Docker. Run through the Docker installation for details, which basically involves simply pulling and running it with the following syntax.

docker pull collabora/code
docker run -t -d -p 127.0.0.1:9980:9980 -e 'aliasgroup1=https://office.organicdesign.nz:443' --restart unless-stopped --cap-add MKNOD collabora/code

Using the Debian package

Although using Docker is by far the simplest method, Docker is heavy and you may prefer to install loolwsd from a native Debian package to reduce dependencies and have it running in the native environment. Most of this is just taken directly from the start script in the Docker image source.

echo "deb https://collaboraoffice.com/repos/CollaboraOnline/CODE /" >> /etc/apt/sources.list.d/collabora.list
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 6CCEA47B2281732DF5D504D00C54D189F4BA284D
apt update
apt install loolwsd code-brand


If you want to add dictionaries for various languages

apt install collaboraoffice5.3-dict* collaboraofficebasis5.3*
mkdir -p /usr/share/hunspell
mkdir -p /usr/share/hyphen
mkdir -p /usr/share/mythes
mkdir -p /opt/lool/systemplate/usr/share/hyphen
for i in `find /opt/collaboraoffice5.3/share/extensions/ -name hyph*.dic`;do cp $i /opt/lool/systemplate/usr/share/hyphen;done
for i in `find /opt/collaboraoffice5.3/share/extensions/ -name hyph*.dic`;do cp $i /usr/share/hyphen;done
cp /opt/collaboraoffice5.3/share/extensions/dict-en/en_US.* /usr/share/hunspell
cp /opt/collaboraoffice5.3/share/extensions/dict-en/en_GB.* /usr/share/hunspell
cp /opt/collaboraoffice5.3/share/extensions/dict-pt-BR/pt_BR.* /usr/share/hunspell
apt remove --purge collaboraoffice5.3-dict*
rm -rf /var/lib/apt/lists/*


This is needed to fix a domain resolving bug:

rm /opt/lool/systemplate/etc/resolv.conf
ln -s /etc/resolv.conf /opt/lool/systemplate/etc/resolv.conf


Copy the LetsEncrypt certs (replace with your own cert path):

cp /etc/letsencrypt/live/office.organicdesign.host/privkey.pem /etc/loolwsd/key.pem
cp /etc/letsencrypt/live/office.organicdesign.host/cert.pem /etc/loolwsd/cert.pem
cp /etc/letsencrypt/live/office.organicdesign.host/chain.pem /etc/loolwsd/ca-chain.cert.pem
chown lool:lool /etc/loolwsd/*.pem


Change the host configuration settings from localhost to your Nextcloud domain (you can just edit loolwsd.xml directly if you prefer):

perl -pi -e "s/localhost<\/host>/files.organicdesign.host<\/host>/g" /etc/loolwsd/loolwsd.xml


Then finally run the daemon as the lool user in the background (you may also like to make a @reboot crontab entry for it as well).

sudo -u lool loolwsd --version --o:sys_template_path=/opt/lool/systemplate --o:lo_template_path=/opt/collaboraoffice5.3 \
    --o:child_root_path=/opt/lool/child-roots --o:file_server_root_path=/usr/share/loolwsd &

Finishing up

Now you can enable the Collabora Online application in your Nextcloud from settings/apps and then go to Collabora Online in the administration section of settings and set the URL of your application to https://office.organicdesign.host. Now you should be ready to testing out creating and editing some office documents in our files!

Mail: You can configure and test you site's mailout settings from settings/administration/additional settings. Set your email to something external to the server first so that the test messages will be a proper test, since sometimes you may have settings that work for local addresses but not for external ones. For example, our server setup does work for external addresses if the encrypted and authenticated SMTP is used since that only works for connections coming in from the outside, since the Nextcloud is on the same host, unencrypted SMTP connections on port 25 should be used.

Registration: After that, you may want to install the registration add-on so that users can register themselves, you can configure it from the same place as the mail and define a default group and whether the accounts need admin approval - if so, the account is initially disabled and needs to be enabled by an admin.

Upgrading

Upgrading NextCloud can be easily done by simply following the instructions in the site when an upgrade is due. But it can be a good idea to opt to use the CLI updater when prompted. To do this open a shell and navigate to the Nextcloud installation location, the check for upgrades:

sudo -u www-data php occ update:check


If there are any updates to do, run the updater as follows, and select "Y" when it asks if you'd also like to run occ update.

sudo -u www-data php updater/updater.phar

You should repeat the process of checking for upgrades after this as sometimes, if the installation is quite old, upgrading leads to new potential upgrades.


If there are any problems, try running it again, it may have removed a problem extension and succeed on the second run. After successfully running the upgrade, turn the maintenance mode off:

sudo -u www-data php occ maintenance:mode --off

To upgrade Colabora, simply stop the Docker container (and be sure to stop any other containers using port 9980), pull the collabora/code repo, and if a new image version was retrieved, delete the old container and image, and start the new one with the docker run command shown above in the installation. For some reason it sometimes takes an hour or so before you can start editing documents with it in Nextcloud, so if its not working after upgrade, come back to it after a couple of hours and check then.

Changing domain name

To change the domain name of a Nextcloud installation which is running Collabora there are five places that need to be updated:

  • The sites SSL certificates
  • The web-server configuration
  • Nextcloud's config.php file
  • Remove the collabora/code container and run a new one using the new domain parameter
  • Set the new Collabora URL in the Nextcloud site configuration.

Developing a custom add-on

I'd like to make an add-on which caters for some of the things we need to do but that we've not found available within the current selection of addons. The idea is to be able to create custom record types and instances of those records. Creating a new record type would involve defining a list of fields and their data-types (which in turn requires a list of such types and their input/output contexts) and the design of a form for creating or modifying instances of those records.

  • The ability for the public to create and edit their own instances if records would allow for information gathering like google forms
  • Searching and reporting would be necessary and they could be exported to CSV or spreadsheet
  • Deck might be a good existing addon to base it on since it already has boards, stacks and cards, this could map for example to record-types, record-instances and fields

Troubleshooting

Check in the "office" item in the "administration" sidebar of your Nextcloud's "settings". It tells you there if the server-side Collabora is accessible. You can also manually check the info response from /hosting/capabilities.

Tips & Tricks

  • Always leave a document by closing it, rather than just closing the browser or tab as ghost users can cause problems
  • Only add registered people as participants in calendar events, an edit won't save if there's unregistered participants being added
  • It seems that it's best to use cron for background maintenance rather than Ajax updates (just run php -f .../cron.php as the web server user every 15min)
  • You can get user's email addresses from the accounts table which contains a JSON string of all the account into with original display name in the key column
  • Maintenance can be done from shell, use sudo -u www-data php occ to see all the commands and options

Changing default preferences

The online version of Libre Office has a very simplified user interface with very few adjustable options, but since it's using the actual Libre Office code internally those options can still be set from within the server configuration (this method does not work if you're running LOOL from the Docker image).

The configuration file containing the preferences is /etc/coolwsd/coolkitconfig.xcu which is a very simplified version of the desktop Libre Office configuration file usually found in ~/.config/libreoffice/4/user/registrymodifications.xcu. We can find the preferences we want to adjust in the desktop version of the file and copy those same entries across to the LOOL version.

Note that if you're running the docker container rather than a native installation, you can edit files in the container using the docker cp command, e.g.

docker cp <CONTAINER_ID>:/etc/coolwsd/coolkitconfig.xcu coolkitconfig.xcu
nano coolkitconfig.xcu
docker cp coolkitconfig.xcu <CONTAINER_ID>:/etc/coolwsd/coolkitconfig.xcu

For example, I wanted to disable the auto-correct functionality that fixed capitalisation of the first two letters of words. In the desktop version when I disable this functionality from the interface the following entry in the configuration is updated:

<item oor:path="/org.openoffice.Office.Common/AutoCorrect"><prop oor:name="TwoCapitalsAtStart" oor:op="fuse"><value>false</value></prop></item>

I then added this rows into the /etc/coolwsd/coolkitconfig.xcu file and after restarting the service, LOOL recognised the new preference and disabled the functionality properly.

Using cell protection

You may have noticed in the spreadsheet that the "cell protection" tab is still available in the "format cells" dialog box, but you can use it because the "protect sheet" option is not available in the "tools" menu.

You can however download your sheet, and enable the cell protection using the offline version of Libre Office, and then upload it again and then you'll find that the cell protection works as it should. To modify or un-protect a a protected cell, you'll need to go back to the offline version though.

Custom CSS

I like to enable the "Custom CSS" app which gives you the ability to add your own CSS rules in the theming section of settings. Here's my custom rules:

/* Highlight the background of the current day in the calendar */
#fullcalendar td.fc-today {
  background-color: #FFFFDE;
}

/* Make the notifications more obvious */
div#notification {
  background-color: #FFFFDE;
  font-size: 200%;
  padding: 20px 40px;
  font-weight: bold;
  margin-top: 100px;
  border-radius: 10px;
  border: 1px solid black;
}

Sharing a Nextcloud calendar with Google calendar

The intuitive way of sharing a Nextcloud calendar using the Webdav link does not work with Google calendar (or Thunderbird for that matter). But generating an export link using the following procedure works in both cases, although Google is extremely slow to synchronise external calendars, taking 1-2 days.

  • Click the share link of one of your calendars (e.g. the OD one) that you want to share
  • This opens a share link option, click the + to the right of it
  • Then you'll see a ... menu
  • Go into that and click copy "subscription link"
Nextcloud calendar sharing.png

The link will now be in the clipboard ready for pasting. This link is not the usual Dav link and the data that is returned by it is acceptable to Google and Thunderbird calendars.


To use the link to retrieve your calendar into a Google calendar:

  • In the side menu go to "other calendars"
  • Click +
  • Select "from URL"
  • And paste your link in

Errors and issues

Memcache \OC\Memcache\APCu not available

This error started showing up for the execution of cron.php. It can be mitigated by enabling the APCu for the call by adding --define apc.enable_cli=1 to php command in the crontab.

See also