nextcloud-dev-docker-compose

A docker based Nextcloud development environment that is easy to setup and use.

⚠ DO NOT USE THIS IN PRODUCTION

Various settings in this setup are considered insecure and default passwords and secrets are used all over the place

Features

• ☁ Nextcloud
• 🔒 Nginx proxy with SSL termination
• 💾 MySQL
• 💡 Redis
• 👥 LDAP with example user data
• ✉ Mailhog
• 🚀 Blackfire
• 📄 Collabora

Getting started

Installation requirements on Ubuntu

1. Install docker and git

   sudo apt install docker.io git
   

Continue with the installation instructions below.

Installation requirements on macOS

1. Install the Xcode command line utils: xcode-select --install
2. Install Docker https://www.docker.com/products/docker-desktop/

Continue with the installation instructions below.

Installation requirements on Windows

This development environment can be used under Windows using WSL2 and Docker. This step by step guide is using VS Code as an editor as it allows to easily work within the Linux environment on the remote WSL instance. You may follow https://code.visualstudio.com/blogs/2020/03/02/docker-in-wsl2 in order setup everything required, but in short the steps are the following:

1. Install Windows 10, version 1903 or higher or Windows 11.
2. Enable WSL 2 feature on Windows. For detailed instructions, refer to the Microsoft documentation.
3. Install the Ubuntu distribution for WSL https://docs.microsoft.com/en-us/windows/wsl/install
4. Download and install the Linux kernel update package.
5. Install Docker Desktop for Windows.
6. Open the Ubuntu terminal and run the installation command below

Continue with the installation instructions below.

To get the setup running:

curl -L https://yeeeha.org/nc-dev | bash

This will:

• Clone the Nextcloud server source code
• Ask for your sudo password to add the hostnames for your local environment to /etc/hosts

The command will end with some instructions on how to start your development environment:

• Start the docker container

## Manual setup

The above script will clone this repository and afterwards perform the setup of the development manual with the following steps:

To properly verify what is happening you might want to clone manually using the following commands, if you don't trust piping random URLs to the terminal:

```bash
git clone https://github.com/juliushaertl/nextcloud-docker-dev
cd nextcloud-docker-dev
./bootstrap.sh

Common tasks

Starting the containers

• Start full setup: docker-compose up
• Minimum: docker-compose up proxy nextcloud (nextcloud mysql redis mailhog)

Running stable versions

The main nextcloud service is ment for running the master branch checkout of the server and your apps. The docker-compose file provides individual containers for stable Nextcloud releases. In order to run those you will need a checkout of the stable version server branch to your workspace directory. Using git worktree makes it easy to have different branches checked out in parallel in separate directories.

During the bootstrap script an initial set of the last 3 stable releases will be checked out already at the workspace/ directory, however you may add newer or older ones manually using the following commands:

cd workspace/server
git worktree add ../stable23 stable23
cd ../stable23
git submodule update --init

After adding the worktree you can start the stable container using docker-compose up -d stable23. You can then add stable23.local 127.0.0.1 to your /etc/hosts file to access it.

Git worktrees can also be used to have a checkout of an apps stable brach within the server stable directory.

cd workspace/server/apps-extra/text
git worktree add ../../../stable23/apps-extra/text stable23

Running into errors

If your setup isn't working and you can not figure out the reason why, running docker-compose down -v will remove the relevant containers and volumes, allowing you to run docker-compose up again from a clean slate.

Configuration

Environment variables

This is automatically done by the bootstrap script.

A .env file should be created in the repository root, to keep configuration default on the dev setup:

cp example.env .env

Replace REPO_PATH_SERVER with the path from above.

Setting the PHP version to be used

The Nextcloud instance is setup to run with PHP 7.2 by default. If you wish to use a different version of PHP, set the PHP_VERSION .env variable.

The variable supports the following values:

1. PHP 7.1: 71
2. PHP 7.2: 72
3. PHP 7.3: 73
4. PHP 7.4: 74
5. PHP 8.0: 80

dnsmasq to resolve wildcard domains

Instead of adding the individual container domains to /etc/hosts a local dns server like dnsmasq can be used to resolve any domain ending with the configured DOMAIN_SUFFIX in .env to localhost.

For dnsmasq adding the following configuration would be sufficient for DOMAIN_SUFFIX=.local:

address=/.local/127.0.0.1

Use valid certificates trusted by your system

• Install mkcert https://github.com/FiloSottile/mkcert

• Go to data/ssl

• mkcert nextcloud.local

• mv nextcloud.local-key.pem nextcloud.local.key

• mv nextcloud.local.pem nextcloud.local.crt

• docker-compose restart proxy

Services

Each service can be started using docker-compose up -d <service>. Some services like LDAP come with autoconfiguration if the used Nextcloud service is installed from scratch, so you may want to destroy the existing containers before starting the service using docker-compose down -v, but this will also drop any data or configuration you may already have on the instances.

🔒 Reverse Proxy

Used for SSL termination. To setup SSL support provide a proper DOMAIN_SUFFIX environment variable and put the certificates to ./data/ssl/ named by the domain name.

You might need to add the domains to your /etc/hosts file:

127.0.0.1 nextcloud.local
127.0.0.1 collabora.local

This is assuming you have set DOMAIN_SUFFIX=.local

You can generate it through:

awk -v D=.local '/- [A-z0-9]+\${DOMAIN_SUFFIX}/ {sub("\\$\{DOMAIN_SUFFIX\}", D " 127.0.0.1", $2); print $2}' docker-compose.yml

You can generate selfsigned certificates using:

cd data/ssl
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout  nextcloud.local.key -out nextcloud.local.crt

✉ Mail

Sending/receiving mails can be tested with mailhog which is available on ports 1025 (SMTP).

To use the webui, add 127.0.0.1 mail.local to your /etc/hosts and open mail.local.

🚀 Blackfire

Blackfire needs to use a hostname/ip that is resolvable from within the blackfire container. Their free version is limited to local profiling so we need to browse Nextcloud though its local docker IP or add the hostname to /etc/hosts.

Using with curl

alias blackfire='docker-compose exec -e BLACKFIRE_CLIENT_ID=$BLACKFIRE_CLIENT_ID -e BLACKFIRE_CLIENT_TOKEN=$BLACKFIRE_CLIENT_TOKEN blackfire blackfire'
blackfire curl http://192.168.21.8/

👥 LDAP

The LDAP sample data is based on https://github.com/rroemhild/docker-test-openldap and extended with randomly generated users/groups. For details see data/ldap-generator/. LDAP will be configured automatically if the ldap container is available during installation.

Example users are: leela fry bender zoidberg hermes professor. The password is the same as the uid.

Useful commands:

docker-compose exec ldap ldapsearch -H 'ldap://localhost' -D "cn=admin,dc=planetexpress,dc=com" -w admin -b "dc=planetexpress,dc=com" "(&(objectclass=inetOrgPerson)(description=*use*))"

Collabora

• Make sure to have the collabora hostname setup in your /etc/hosts file: 127.0.0.1 collabora.local
• Automatically enable for one of your containers (e.g. the main nextcloud one):
  • Run ./scripts/enable-collabora nextcloud
• Manual setup
  • Start the Collabora Online server in addition to your other containers docker-compose up -d collabora
  • Make sure you have the richdocuments app cloned to your apps-extra directory and built the frontend code of the app with npm ci && npm run build
  • Enable the app and configure collabora.local in the Collabora settings inside of Nextcloud

ONLYOFFICE

• Make sure to have the collabora hostname setup in your /etc/hosts file: 127.0.0.1 onlyoffice.local
• Automatically enable for one of your containers (e.g. the main nextcloud one):
  • Run ./scripts/enable-onlyoffice nextcloud
• Manual setup
  • Start the ONLYOFFICE server in addition to your other containers docker-compose up -d onlyoffice
  • Clone https://github.com/ONLYOFFICE/onlyoffice-nextcloud into your apps directory
  • Enable the app and configure onlyoffice.local in the ONLYOFFICE settings inside of Nextcloud

Antivirus

docker-compose up -d proxy nextcloud av

The clanav antivirus will then be exposed as a deamon with host clam and port 3310.

SAML

docker-compose up -d proxy nextcloud saml

• uid mapping: urn:oid:0.9.2342.19200300.100.1.1
• idp entity id: https://sso.local.dev.bitgrid.net/simplesaml/saml2/idp/metadata.php
• single sign on service url: https://sso.local.dev.bitgrid.net/simplesaml/saml2/idp/SSOService.php
• single log out service url: https://sso.local.dev.bitgrid.net/simplesaml/saml2/idp/SingleLogoutService.php
• use certificate from docker/configs/var-simplesamlphp/cert/example.org.crt

  -----BEGIN CERTIFICATE-----
  MIICrDCCAhWgAwIBAgIUNtfnC2jE/rLdxHCs2th3WaYLryAwDQYJKoZIhvcNAQEL
  BQAwaDELMAkGA1UEBhMCREUxCzAJBgNVBAgMAkJZMRIwEAYDVQQHDAlXdWVyemJ1
  cmcxFDASBgNVBAoMC0V4YW1wbGUgb3JnMSIwIAYDVQQDDBlzc28ubG9jYWwuZGV2
  LmJpdGdyaWQubmV0MB4XDTE5MDcwMzE0MjkzOFoXDTI5MDcwMjE0MjkzOFowaDEL
  MAkGA1UEBhMCREUxCzAJBgNVBAgMAkJZMRIwEAYDVQQHDAlXdWVyemJ1cmcxFDAS
  BgNVBAoMC0V4YW1wbGUgb3JnMSIwIAYDVQQDDBlzc28ubG9jYWwuZGV2LmJpdGdy
  aWQubmV0MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHPZwU+dAc76yB6bOq
  0AkP1y9g7aAi1vRtJ9GD4AEAsA3zjW1P60BYs92mvZwNWK6NxlJYw51xPak9QMk5
  qRHaTdBkmq0a2mWYqh1AZNNgCII6/VnLcbEIgyoXB0CCfY+2vaavAmFsRwOMdeR9
  HmtQQPlbTA4m5Y8jWGVs1qPtDQIDAQABo1MwUTAdBgNVHQ4EFgQUeZSoGKeN5uu5
  K+n98o3wcitFYJ0wHwYDVR0jBBgwFoAUeZSoGKeN5uu5K+n98o3wcitFYJ0wDwYD
  VR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOBgQA25X/Ke+5dw7up8gcF2BNQ
  ggBcJs+SVKBmPwRcPQ8plgX4D/K8JJNT13HNlxTGDmb9elXEkzSjdJ+6Oa8n3IMe
  vUUejXDXUBvlmmm+ImJVwwCn27cSfIYb/RoZPeKtned4SCzpbEO9H/75z3XSqAZS
  Z1tiHzYOVtEs4UNGOtz1Jg==
  -----END CERTIFICATE-----
  

• cn urn:oid:2.5.4.3
• email urn:oid:0.9.2342.19200300.100.1.3

Environment based SSO

A simple approach to test environment based SSO with the user_saml app is to use apache basic auth with the following configuration:

<Location /login>
	AuthType Basic
	AuthName "SAML"
	AuthUserFile /var/www/html/.htpasswd
	Require valid-user
</Location>
<Location /index.php/login>
	AuthType Basic
	AuthName "SAML"
	AuthUserFile /var/www/html/.htpasswd
	Require valid-user
</Location>
<Location /index.php/apps/user_saml/saml/login>
	AuthType Basic
	AuthName "SAML"
	AuthUserFile /var/www/html/.htpasswd
	Require valid-user
</Location>
<Location /apps/user_saml/saml/login>
	AuthType Basic
	AuthName "SAML"
	AuthUserFile /var/www/html/.htpasswd
	Require valid-user
</Location>

Fulltextsearch

docker-compose up -d elasticsearch elasticsearch-ui

• Address for configuring in Nextcloud: http://elastic:elastic@elasticsearch:9200
• Adress to access elastic search from outside: http://elastic:elastic@elasticsearch.local
• Address for accessing the ui: http://elasticsearch-ui.local/

sudo sysctl -w vm.max_map_count=262144

Object storage

Primary object storage can be enabled by setting the PRIMARY=minio environment variable either in your .env file or in docker-compose.yml for individual containers.

docker-composer up proxy nextcloud minio

Development

OCC

Run inside of the Nextcloud container:

set XDEBUG_CONFIG=idekey=PHPSTORM
sudo -E -u www-data php -dxdebug.remote_host=192.168.21.1 occ

Useful commands

• Restart apache to reload php configuration without a full container restart: docker-compose kill -s USR1 nextcloud
• Access to mysql console: mysql -h $(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' nextcloud_database-mysql_1) -P 3306 -u nextcloud -pnextcloud
• Run an LDAP search: ldapsearch -x -H ldap://$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' nextcloud_ldap_1) -D "cn=admin,dc=planetexpress,dc=com" -w admin -b "dc=planetexpress,dc=com" -s subtree <filter> <attrs>

Keycloak

• Keycloak is using ldap as a user backend (make sure the ldap container is also running)
• occ user_oidc:provider Keycloak -c nextcloud -s 09e3c268-d8bc-42f1-b7c6-74d307ef5fde -d https://keycloak.local.dev.bitgrid.net/auth/realms/Example/.well-known/openid-configuration
• https://keycloak.local.dev.bitgrid.net/auth/realms/Example/.well-known/openid-configuration
• nextcloud
• 09e3c268-d8bc-42f1-b7c6-74d307ef5fde

Global scale

docker-compose up -d proxy portal gs1 gs2 lookup database-mysql

Users are named the same as the instance name, e.g. gs1, gs2

Imaginary

Enable the imaginary server for generating previews

docker-composer up proxy nextcloud previews_hpb
./scripts/enable-preview-imaginary.sh