Introduction to nc-env

nc-env is a project that enables you to provision isolated Nextcloud test environments in your machine. It is built on vagrant and LXD.

⚡ This project is a personal initiative, without any official support by Nextcloud GmbH

⚡ The templates in this repository are designed and developed for testing and development environments, not for production

Features

You can leverage this project to:

• Quickly setup and run an isolated Nextcloud instance in your machine
• Try features or troubleshoot issues without any manual installation
• Learn and explore the integration of Nextcloud with common enterprise systems, such as LDAP, Single Sign On or an Office Editing Service

Setup the environment

Install and configure LXD

The initial configuration guide is here and applies to many Linux distributions.

If you are interested in understanding the difference between application and system containers, this is a good short article that explains it.

Configure the host to resolve container hostnames

While container hostnames can be defined in /etc/hosts, you can avoid this additional manual step by defining a systemd service that instructs the resolver to query the built-in DNS service for domains ending with dns.domain.

To do that, follow these instructions (reference documentation here)

Get the network interface used by LXD (by default lxdbr0, and assumed as such in the following) and the IP of the built-in DNS (in this output 10.23.46.1):

$ lxc network list

+--------+----------+---------+---------------+-------------------------+-------------+---------+
|  NAME  |   TYPE   | MANAGED |     IPV4      |          IPV6           | DESCRIPTION | USED BY |
+--------+----------+---------+---------------+-------------------------+-------------+---------+
| lxdbr0 | bridge   | YES     | 10.23.46.1/24 | fd42:fa6c:5eee:12::1/64 |             | 25      |
+--------+----------+---------+---------------+-------------------------+-------------+---------+

Set the configuration variables dns.domain (this is optional, the default is lxd) and dns.mode:

$ lxc network set lxdbr0 dns.domain 'localenv.com'

$ lxc network set lxdbr0 dns.mode managed

Create a systemd unit file called lxd-dns-lxdbr0.service that allows this setup to be persistent across machine reboots.

$ sudo cat /etc/systemd/system/lxd-dns-lxdbr0.service
[Unit]
Description=LXD per-link DNS configuration for lxdbr0
BindsTo=sys-subsystem-net-devices-lxdbr0.device
After=sys-subsystem-net-devices-lxdbr0.device

[Service]
Type=oneshot
ExecStart=/usr/bin/resolvectl dns lxdbr0 10.23.46.1
ExecStart=/usr/bin/resolvectl domain lxdbr0 '~localenv.com'

[Install]
WantedBy=sys-subsystem-net-devices-lxdbr0.device

Enable it and start it:

$ sudo systemctl daemon-reload

$ sudo systemctl enable lxd-dns-lxdbr0.service

$ sudo systemctl start lxd-dns-lxdbr0.service

$ sudo systemctl status lxd-dns-lxdbr0.service
? lxd-dns-lxdbr0.service - LXD per-link DNS configuration for lxdbr0
     Loaded: loaded (/etc/systemd/system/lxd-dns-lxdbr0.service; enabled; vendor preset: enabled)
     Active: inactive (dead) since Tue 2022-01-04 12:32:09 CET; 1h 26min ago
    Process: 1916 ExecStart=/usr/bin/resolvectl dns lxdbr0 10.23.46.1 (code=exited, status=0/SUCCESS)
    Process: 1917 ExecStart=/usr/bin/resolvectl domain lxdbr0 ~localenv.com (code=exited, status=0/SUCCESS)
   Main PID: 1917 (code=exited, status=0/SUCCESS)
        CPU: 8ms

ene 04 12:32:09 my-host systemd[1]: Starting LXD per-link DNS configuration for lxdbr0...
ene 04 12:32:09 my-host systemd[1]: lxd-dns-lxdbr0.service: Deactivated successfully.
ene 04 12:32:09 my-host systemd[1]: Finished LXD per-link DNS configuration for lxdbr0.

$ sudo resolvectl status lxdbr0
Link 4 (lxdbr0)
    Current Scopes: DNS
         Protocols: -DefaultRoute +LLMNR -mDNS -DNSOverTLS DNSSEC=no/unsupported
Current DNS Server: 10.23.46.1
       DNS Servers: 10.23.46.1
        DNS Domain: ~localenv.com

Install and configure vagrant

You can learn about installation here. For Ubuntu-based systems, it is as simple as sudo apt install vagrant

Install LXD plugin vagrant-lxd

This plugin adds the ability to manage containers with LXD. See here for installation instructions.

Install mkcert

Download it here) and run mkcert --install. This command installs a local certificate for the Certificate Authority along with its key. This is handy as it avoids many warnings and errors when dealing with self-trusted certificates.

Get the latest release

Download the latest release of nc-env from the repository Releases section.

Provision a container

Once the environment is ready, an instance of the container template that you want to work with can be created and started.

Copy it in the target folder and make sure that the artifacts folder contains all the artifacts documented in the Readme.md file, located in the template root folder.

If some additional configuration step is needed, it will be also documented there.

After running the provisioning step, make sure your host system is able to resolve the domain name that you specified for the container, for example by adding an entry in /etc/hosts.

Afterwards, the environment is ready to be used.

Available Templates

Template	Description
template00-clean-server	Clean server
template01-nextcloud-standalone	Nextcloud standalone server
template02-collabora-code	Collabora (CODE) server
template03-keycloak	Keycloak standalone server
template04-ldap	OpenLDAP server
template05-elasticsearch	Elastic Search server
template06-nextcloud-db-standalone	Database node (to be used in a cluster)
template07-glusterfs-server	GlusterFS node (to be used in a cluster)
template08-haproxy-server	Haproxy (to be used in a cluster)
template09-web-server-node	Web Server Node (to be used in a cluster)
template10-redis-server	Redis server(to be used in a cluster)
template11-minio-storage-server	MinIO Storage Server
template13-talk-hpb	Talk High Performance Backend
template14-self-hosted-appstore	Nextcloud Self-Hosted Appstore