Develop and contribute
Welcome! We're a pretty friendly community and we're thrilled that you want to help make this snap even better. However, we do ask that you follow some general guidelines while doing so, just so we can keep things organized around here.
-
Make sure an issue is created for the bug you're about to fix, or feature you're about to add. Keep them as small as possible.
-
We use a forking, feature-based workflow.
Make a fork of this repository, and create a branch based on
developnamed specifically for the feature on which you'd like to work. Make your changes there. Commit often. -
Squash commits into one, well-formatted commit. Mention the issue being resolved in the commit message on a line all by itself like
Fixes #<bug>(refer to closing issues via commit messages for more keywords you can use).If you really feel like there should be more than one commit in your branch, then you're probably trying to introduce more than one feature and you should make another branch (and issue) for it.
-
Submit a pull request to get changes from your branch into
develop(no merge requests should be made intomaster). Mention which bug is being resolved in the description.
The snap is by definition read-only, but some times it's useful to poke at the contents of it to see what's going on. If we want to do that, there are some hoops we can jump through to get there. Note that this is not recommended for production use. The snap won't be as secure and will no longer update if you do this. This is handy for development/experimentation, nothing more.
I'm runnning these commands on a fully up-to-date Ubuntu 18.04, they are untested elsewhere. I know from experience that this does not work with home disk encryption (ecryptfs), but full disk encryption is fine.
This will download both the snap and the store assertion (store signature for the snap). You can optionally specify the channel, it will default to using stable:
snap download nextcloud [--channel=14/candidate]
We're doing this so that we can modify it (otherwise we wouldn't be able to write to the squashfs image):
unsquashfs nextcloud_10079.snap
That unpacks by default to a directory named "squashfs-root".
We can use snap try to install the snap in read/write mode now that we've unpacked it:
sudo snap try squashfs-root
The snap will fire up after the snap try command and start listening on port 80, so you can just visit http://localhost in your browser to create an admin user and get up and running. The Nextcloud sources are in squashfs-root/htdocs/, although note that the config being used is not in there, but in /var/snap/nextcloud/current/nextcloud/config/.
When you're satisfied with your tinkering, you can uninstall the Nextcloud snap like normal, getting rid of the config and all data:
sudo snap remove nextcloud
You want to help evaluate a pull request? That's awesome, we'd love your help!
Whenever someone creates (or pushes an update to) a pull request, a snap is automatically built and released into an ephemeral channel unique to that pull request. You can see that happening as part of the status checks for that pull request. Note: This is done for amd64 only. If you would like to test another architecture that's excellent, it's just not automated-- please simply ask in the PR and one will be built for you.
You can test out the changes you see in the pull request by installing the snap from that channel:
sudo snap install nextcloud --channel=beta/pr-<number>
or
sudo snap install nextcloud --channel=latest/beta
Create your testing environment on a dedicated machine, VM or container. Example LXD/LXC guide and specs.
You may want to automate installation for testing, thus maintaining a reproducible environment. No need to do repetitive stuff if you can automate it.
Assuming you're running your tests behind a reverse proxy
- install nextcloud snap latest/beta on testing host see installation.
- complete nextcloud initialisation see first start. this should be done manually and test if "upstream" issues are resolved.
- run automated configuration script (see example below).
- check logs or run the debugging script.
Example script:
#!/bin/bash
#################################################################################
# Script description -scubamuc- https://scubamuc.github.io/ #
#################################################################################
# Setup Nextcloud snap testing environment
# This script assumes you are running your test instance behind a reverse proxy
# managing encryption
#################################################################################
## Setup admin account
## sudo nextcloud.manual-install adminuser yousecretpassword
#################################################################################
# backup working config.php
sudo cp /var/snap/nextcloud/current/nextcloud/config/config.php /var/snap/nextcloud/current/ ;
# set default phone region
sudo nextcloud.occ config:system:set default_phone_region --value="GB" ;
# set http compression (optional)
sudo snap set nextcloud http.compression=true ;
# set trusted proxies (if reverse proxy is present)
sudo nextcloud.occ config:system:set trusted_proxies 0 --value="reverse.proxy.ip" ;
# set trusted domains
sudo nextcloud.occ config:system:set trusted_domains 0 --value="cloud.my.domain.xyz" ;
# set overwritehostprotocol (optional)
sudo nextcloud.occ config:system:set overwriteprotocol --value="https" ;
# set email for admin user (optional)
sudo nextcloud.occ config:system:set mail_from_address --value="cloud.admin" ;
sudo nextcloud.occ config:system:set mail_smtpmode --value="smtp" ;
sudo nextcloud.occ config:system:set mail_sendmailmode --value="smtp" ;
sudo nextcloud.occ config:system:set mail_domain --value="your.domain.com" ;
sudo nextcloud.occ config:system:set mail_smtpauth --value="1" ;
sudo nextcloud.occ config:system:set mail_smtphost --value="your.smpt.host" ;
sudo nextcloud.occ config:system:set mail_smtpport --value="port" ;
sudo nextcloud.occ config:system:set mail_smtpname --value="smtpusername" ;
sudo nextcloud.occ config:system:set mail_smtppassword --value="smtppassword" ;
sudo nextcloud.occ config:system:set mail_smtpsecure --value="ssl" ;
#################################################################################
# This section is optional for recommended apps and may be completely omitted! #
#################################################################################
## CODE & Office settings
# install required packages on host
sudo apt install fontconfig glibc-source ;
# Set overwrite-cli
sudo nextcloud.occ config:system:set overwrite.cli.url --value="https://cloud.my.domain.xyz" ;
# 1. Disable CODE
sudo nextcloud.occ app:disable richdocumentscode ;
# 2. Disable Nextcloud office
sudo nextcloud.occ app:disable richdocuments ;
# 3. Delete public_wopi configuration
sudo nextcloud.occ config:app:delete richdocuments public_wopi_url ;
# 4. Delete wopi_url configuration
sudo nextcloud.occ config:app:delete richdocuments wopi_url ;
# 5. Enable Nextcloud office
sudo nextcloud.occ app:enable richdocuments ;
# 6. Enable CODE
sudo nextcloud.occ app:enable richdocumentscode ;
exitOnce you're done testing, you can completely remove the snap:
sudo snap remove --purge nextcloud
It's not recommended to test half-baked pull requests on productive instances. Although snap is robust and the revert process stable, don't swap channels on a productive instance. Prefer to stay on stable channel.
-
Managing Nextcloud snap managing Nextcloud snap with snap
-
Backup or migrate your productive instance see Backup, Restore & Migrate
If you wish to disregard this warning, you can update an existing instance with:
sudo snap refresh nextcloud --channel=latest/beta/pr-<number>
Make sure to revert back to where you were once you've completed your testing:
sudo snap revert nextcloud