Skip to content

Commit

Permalink
Merge pull request #94 from pdsinterop/revisit-install-instructions
Browse files Browse the repository at this point in the history 
Revisit install instructions
  • Loading branch information
@ylebre
ylebre authored Sep 30, 2022
2 parents 9809f47 + 6ea869b commit 59e9dda
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 131 deletions.
132 changes: 21 additions & 111 deletions INSTALL.md
View file
Original file line number Diff line number Diff line change
@@ -1,115 +1,24 @@
# Installing this app to your Nextcloud

## Set up /.well-known/openid-configuration
After installing and enabling the app, take the JSON from e.g.

`https://cloud.pondersource.org/index.php/apps/solid/openid` (depending on your hostname and whether you have the `index.php/` part in there)

and put that into e.g. `/var/www/html/.well-known/openid-configuration` (depending on your webroot being e.g. `/var/www/html`)
Check that it works: `https://cloud.pondersource.org/.well-known/openid-configuration`
Then add this section to your apache site.conf:
```
<Directory /var/www/html/.well-known/>
Header always set Access-Control-Allow-Origin: *
</Directory>
```
Then restart Apache.

In earlier versions of this app (e.g. the one in the Dockerfile we use for running the Solid test suite) we
used a redirect from /.well-known/openid-configuration to /index.php/apps/solid/openid but it's difficult
to add CORS headers to a redirect, so that's why just copying the file into a folder like that is preferable.

## If your Nextcloud was installed using Snap

Steps you probably already took:
* Point a DNS A record to the server that will run Nextcloud, for instance "A test-nextcloud-snap 188.166.99.179"
* Install Nextcloud using Snap:
> root@ubuntu-s-4vcpu-8gb-amd-ams3-01:~# snap install nextcloud
> nextcloud 22.2.0snap2 from Nextcloud✓ installed
* Browse to it over http and complete the setup:

<img width="960" alt="Screenshot 1" src="https://user-images.githubusercontent.com/408412/140734318-2872d19c-8a2d-40a5-8e89-e0474c705840.png">

It's important that you have a public DNS A record pointing to the server, since you'll need it to enable https, which is a requirement for Solid:

* Run this on your server to add a LetsEncrypt cert to your Nextcloud:

```sh
root@ubuntu-s-4vcpu-8gb-amd-ams3-01:~# nextcloud.enable-https lets-encryptIn order for Let's Encrypt to verify that you actually own the
domain(s) for which you're requesting a certificate, there are a
number of requirements of which you need to be aware:
1. In order to register with the Let's Encrypt ACME server, you must
   agree to the currently-in-effect Subscriber Agreement located
   here:

       https://letsencrypt.org/repository/

   By continuing to use this tool you agree to these terms. Please
   cancel now if otherwise.

2. You must have the domain name(s) for which you want certificates
   pointing at the external IP address of this machine.

3. Both ports 80 and 443 on the external IP address of this machine
   must point to this machine (e.g. port forwarding might need to be
   setup on your router).

Have you met these requirements? (y/n)
Please answer yes or no.
Have you met these requirements? (y/n) yes
Please enter an email address (for urgent notices or key recovery): [email protected]

Please enter your domain name(s) (space-separated): test-nextcloud-snap.michielbdejong.com
Attempting to obtain certificates... done

Restarting apache... done
root@ubuntu-s-4vcpu-8gb-amd-ams3-01:~# 
```
* Now you can visit your Nextcloud over https:
<img width="960" alt="Screenshot 2" src="https://user-images.githubusercontent.com/408412/140734389-b3d30abd-8568-415f-a3b9-38d8d4249018.png">
* Go to the 'Apps' menu:
<img width="960" alt="Screenshot 3" src="https://user-images.githubusercontent.com/408412/140734411-49661501-43ab-4821-b8a2-60dbc442f964.png">
* Search for 'solid':
<img width="1270" alt="Screenshot 4" src="https://user-images.githubusercontent.com/408412/140734420-6bb1ac6f-b4ee-4df5-b88d-544cdb82f174.png">
* Download and install:
<img width="1152" alt="Screenshot 5" src="https://user-images.githubusercontent.com/408412/140734504-5cdc4837-9e35-4b47-b091-69b9ff913081.png">
* If you can't find v0.0.3 in through the search function, you can also download it explicitly:
> `root@ubuntu-s-4vcpu-8gb-amd-ams3-01:/var/snap/nextcloud/current/nextcloud/extra-apps# wget https://github.com/pdsinterop/solid-nextcloud/releases/download/v0.0.3/solid.tar.gz`
* In all cases, make sure you click 'Enable' for the Solid app on https://test-nextcloud-snap.michielbdejong.com/index.php/settings/apps
* Now test with your browser: `https://test-nextcloud-snap.michielbdejong.com/index.php/apps/solid/openid`
* It should be a JSON document, something like `{"id_token_signing_alg_values_supported":["RS256"],"subject_types_supported":["public"],"response_types_supported":[...`
* The following [is a bit tricky](https://github.com/nextcloud-snap/nextcloud-snap/issues/412#issuecomment-930878692) but it seems to work:
```sh
sudo cp -r /snap/nextcloud/current/htdocs /var/snap/nextcloud/current/nextcloud/config/
cd /var/snap/nextcloud/current/nextcloud/config/htdocs
sudo mount /var/snap/nextcloud/current/nextcloud/config/htdocs /snap/nextcloud/current/htdocs/ -o bind
```
Now make the change described in the "Set up /.well-known/openid-configuration" section above, but using
`/var/snap/nextcloud/current/nextcloud/config/htdocs/.well-known/openid-configuration` as the directory.
FIXME: How can you edit the Apache site.conf if installed via Snap? Maybe see if the Header directive
can live in `/var/snap/nextcloud/current/nextcloud/config/htdocs/.well-known/.htaccess` instead?
Restart Apache using:
```sh
sudo snap restart nextcloud.apache
```
* Now test that `https://test-nextcloud-snap.michielbdejong.com/.well-known/openid-configuration` redirects to `https://test-nextcloud-snap.michielbdejong.com/index.php/apps/solid/openid`
* Add this to your /etc/fstabs and restart the server:
```
/var/snap/nextcloud/current/nextcloud/config/htdocs /snap/nextcloud/current/htdocs none auto,bind,x-systemd.before=snap.nextcloud.apache.service,x-systemd.requires-mounts-for=/snap/nextcloud/current/,x-systemd.required-by=snap.nextcloud.apache.service 0 0
If you have installed Nextcloud [using snap](https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-nextcloud-on-ubuntu-22-04)
you should be able to run the latest version of this app.

## Building from source
In the future you will be able to install the app just from the app store, or by running `sudo nextcloud.occ app:install solid`.
But currently (September 2022) that still installs version 0.0.3, which means you need to install from source. To switch the version of your Solid app from the "store-bought" version to the latest unreleased version, you will need to build from source:
```
sudo /bin/bash
cd /var/snap/nextcloud/current/nextcloud/extra-apps/
rm -r solid
git clone https://github.com/pdsinterop/solid-nextcloud
ln -s solid-nextcloud/solid
cd solid
apt update
apt install -y php git php-curl php-gd php-opcache php-xml php-gd \
php-curl php-zip php-json libxml2 libxml2-dev php-xml php-mbstring \
build-essential curl php-sqlite3 php-xdebug php-mbstring php-zip \
php-imagick imagemagick php-intl
make
```

## Troubleshooting
Expand Down Expand Up @@ -137,4 +46,5 @@ sudo snap restart nextcloud.apache
</Directory>
```
(notice, importantly, the `AllowOverride All` that makes apache read your .htaccess in the first place) and then run `systemctl restart apache2`.
* find a way to enable CORS headers (not sure exactly how to do this, see https://github.com/pdsinterop/solid-nextcloud/issues/57)
* if installed through snap, the logs you want to check server-side are in `/var/snap/nextcloud/current/logs/`
* if installed the old way with Apache, check `/var/log/apache2/error.log` and `/var/www/html/data/nextcloud.log`
24 changes: 4 additions & 20 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,7 @@
A plugin to make Nextcloud compatible with Solid.

You can download it via the Nextcloud app store: https://apps.nextcloud.com/apps/solid
IMPORTANT: Follow the [additional install instructions!](https://github.com/pdsinterop/solid-nextcloud/blob/main/INSTALL.md).


## Unattended install
To programmatically build a Nextcloud server that has this plugin working,
you can look at the [nextcloud-server image in the Solid test-suite](https://github.com/solid/test-suite/blob/main/servers/nextcloud-server/Dockerfile),
combined with [how it's initialized](https://github.com/solid/test-suite/blob/665824a/runTests.sh#L52-L53) in the runTests.sh script.
IMPORTANT: Follow the [install instructions!](https://github.com/pdsinterop/solid-nextcloud/blob/main/INSTALL.md).

## Development install
Clone https://github.com/pdsinterop/test-suites, cd into it, and run:
Expand All @@ -27,23 +21,13 @@ docker exec -u root -it server service apache2 reload
Now visit https://localhost and log in as alice / alice123.

## Manual install
If you enable this app in your Nextcloud instance, you should
[edit your .htaccess file](https://github.com/solid/test-suite/blob/665824af763ddd5dd7242cbc8b18faad4ac304e3/servers/nextcloud-server/init.sh#L5)
and then test whether https://your-nextcloud-server.com/.well-known/openid-configuration redirects to https://your-nextcloud-server.com/apps/solid/openid.

Also, take the CORS instructions from site.conf and add them to your own webserver configuration.
Pleas follow the [install instructions](https://github.com/pdsinterop/solid-nextcloud/blob/main/INSTALL.md).

## Unattended testing
To test whether your server is install correctly, you can run Solid's [webid-provider-tests](https://github.com/solid/webid-provider-tests#against-production) against it.
There is a [GitHub Action](https://github.com/pdsinterop/solid-nextcloud/actions/workflows/ci.yml) that runs a [Docker-based test script](https://github.com/pdsinterop/solid-nextcloud/blob/585b968/.github/workflows/ci.yml#L29).

## Manual testing
Go to https://solidcommunity.net and create a Solid pod.
Go to https://generator.inrupt.com/text-editor and log in with https://solidcommunity.net. Tick all 4 boxes in the consent dialog.
Click 'Load', type something, click 'Save'.
Grant access to co-editor https://your-nextcloud-server.com/apps/solid/@your-username/profile/card#me.
For instance if you're using the [development install](#development-install), that would be https://localhost/apps/solid/@alice/profile/card#me
Now in a separate browser window, log in to https://generator.inrupt.com/text-editor with https://your-nextcloud-server.com.
You should be able to edit the file as a co-author now, using your Nextcloud account as a webid identity provider.
You can try out the various Solid apps that show up in the Solid App GUI inside the Nextcloud GUI on first use.

# Publishing to the Nextcloud app store

Expand Down

0 comments on commit 59e9dda

Please sign in to comment.