26 documentation on how to use (#31)

* Issue 26, draft update of Readme.md

* Corrections

* Corrections

* Update README.md

* Update README.md

* Update README.md

* Add files via upload

* Update README.md

* Update README.md

Co-authored-by: Ron <>

README.md

@@ -1,54 +1,109 @@
 # Nextcloud Swarm Plugin
 
-This is a plugin for bridging [Nextcloud](https://nextcloud.com) and [Swarm](https://www.ethswarm.org/). The goal with the plugin is to have a way to interact with Swarm storage directly in Nextcloud Files using the external storage feature in Nextcloud.
+*Decentralized Sovereign cloud-storage comes to Nextcloud!*
 
-<img width="1045" alt="Desired view when enabling the plugin" src="https://user-images.githubusercontent.com/3958329/136574298-d87d320f-b3c3-46e8-95f0-2a17974d48f7.png">
-<em>Desired file view when using the plugin in Nextcloud</em>
+This plugin brings [Swarm](https://www.ethswarm.org/) to [Nextcloud](https://nextcloud.com) - decentralized file-storage, connected to the blockchain.
+
+<img alt="View file and action menu" src="/assets/images/swarm_Files.png">
+<em>File view when using the plugin in Nextcloud</em>
+
+## Table of Contents
+
+- [General Architecture](#general-architecture)
+- [External storage](#external-storage)
+- [Settings](#settings)
+- [Setup and Installation](#setup-and-installation)
+- [Using the Swarm](#using-the-swarm)
+- [Limitations](#limitations)
+- [License](#license)
 
 ## General Architecture
 
-The whole system needed for the plugin consists of three parts, A Nextcloud instance, a Swarm node and the plugin itself. The plugin itself will contain two distinct parts, the external storage portion and the settings portion.
+The whole system for the plugin consists of three parts: A Nextcloud instance, a Swarm node and the plugin itself.
+The plugin itself contains two distinct parts, the External Storage portion and the Settings portion.
 
 ### External storage
 
-The external storage portion of the plugin will be written in PHP and will handle the actual file operations. As Nextcloud can't directly interact with the Swarm network, everything has to go through a Swarm node. The Swarm node communicates over HTTP, so the individual file system operations will primarily consist of HTTP requests made to the Swarm node using cURL.
+File handling operations involving the swarm node are integrated in the External Storage ("Files") section of Nextcloud.
 
-The actual file system will be based on a common storage backend class available in Nextcloud, which is intended as an abstraction layer to allow for easier implementation of many different storage backends for Nextcloud. The storage backend class provides the functions Nextcloud expects, and we then need to overwrite those function with an implementation that works with Swarm.
+<img alt="View file and action menu" src="/assets/images/swarm_Files_Intro.png">
+<em>View, download, and file view actions in Nextcloud</em>
 
-The class can be found here:
 
-https://github.com/nextcloud/server/blob/master/lib/private/Files/Storage/Common.php
+Using our plugin, the main file operations that are available in Nextcloud are:
 
-and it implements the following interfaces:
+- Upload file(s) to a swarm node
+- Download and view files
+- Copy/Move files from any External Storage to a swarm node
+- Copy files from a swarm node to any External Storage
 
--   https://github.com/nextcloud/server/blob/master/lib/public/Files/Storage/IStorage.php
--   https://github.com/nextcloud/server/blob/master/lib/public/Files/Storage/IWriteStreamStorage.php
--   https://github.com/nextcloud/server/blob/master/lib/public/Files/Storage/ILockingStorage.php
+File metadata, like with all files in Nextcloud, are stored in the Nextcloud database, such as the swarm reference that is used to uniquely identify each file and its mimetype, file size etc. The rest of the metadata is stored in the normal filecache table which is common to all External File storages.
 
-File metadata, like with all files in Nextcloud, should be stored in the database. This includes any extra information, for example the swarm encryption key that is used for each encrypted file. A new database table will be needed for any data that can't be discovered anew through the Swarm node, like the before mentioned encryption keys. The rest of the metadata should be stored in the normal filecache table.
-
-The external storage should accept configuration options from two places, the normal external storage settings, as well as the plugin settings. Configuration options that are unique to Swarm should be handled through the settings view and stored in plugin settings, where more common external storage settings should be handled through the external storage settings.
-
-The best documentation we have for how to implement external storage in Nextcloud, is the files_external app included with Nextcloud server:
-
-https://github.com/nextcloud/server/tree/master/apps/files_external
+The backend of the plugin is written in PHP which essentially allows communication over HTTP in the form of HTTP requests made to the Swarm node using [cURL](https://github.com/curl/curl).
 
 ### Settings
 
-The settings portion will be a new section available in the admin settings in Nextcloud. It will utilise the Swarm TypeScript library for handling communication with the Swarm node and use Vue.js for the UI. The goal for the settings page is to allow configuration of the Swarm node directly in Nextcloud, as well as seeing the current status of the Swarm node. The primary reason why this is necessary is to try and create a convenient way of handling the payment system in Swarm directly in Nextcloud. Every operation in Swarm costs money, so we need some way to view how much money is available to the Swarm node, as well as configuring how the external storage portion should deal with creating files in the Swarm network.
+Available to users with administrative credentials, the external storage accepts configuration options from two places, the normal External Storage settings, which allows a user to configure the basic connection properties of a Swarm node:
 
-A more detailed list of what should be available in the UI can be seen in this issue:
+<img alt="Setup Swarm External Storage" src="/assets/images/swarm_Setup_ExtStorage.png">
+<em>Basic Swarm setup in External Storage in Nextcloud administration</em>
 
-https://github.com/MetaProvide/nextcloud-swarm-plugin/issues/4
 
-The preferred way of storing the settings configured in the settings view is to use the Nextcloud settings API. But if a more advanced settings structure is needed, creating a new database table will be an option.
+Since every operation in Swarm costs money, it is important to view how much money is available to the Swarm node directly and also provide a convenient way of handling the payment system in Swarm - all managed directly in Nextcloud. This is in a specific section with more advanced configuration for the Swarm node, where the following settings can be viewed and edited:
 
-## Goals for v0.1.0
+- Configure which Swarm node to manage
+- View current status of the Swarm node
+- Option to toggle encryption on and off
+- How much BZZ is available to the node
+- Any purchased stamp batches and the remaining balances
+- Have the option to purchase a new batch of stamps
+- Toggle the batch used for uploading files active/inactive 
 
--   Figure out what is needed for a bare-bones file system in Nextcloud and implement read and write file system operations through external storage in Nextcloud.
--   Create settings view that allows you to see the status of the Swarm node and configure it.
--   Support for toggling the Swarm encryption on and off (Should be on by default).
--   Only support for one Swarm node per instance (only allow configuration by admins). Mounting Swarm storage should also only be allowed through the admin settings.
+<img alt="Setup Swarm External Storage" src="/assets/images/swarm_Setup_Ethswarm_buyStamp1.png">
+<em>Advanced configuration of Swarm in Nextcloud administration</em>
+
+It utilises the [ethersphere bee-js](https://github.com/ethersphere/bee-js) Javascript client library for handling communication with the Swarm decentralized storage and uses Vue.js for the UI.
+
+## Setup and Installation
+
+First it is necessary to have a Swarm node running.
+For Swarm installation instructions, follow the offical [ethswarm documentation](https://www.ethswarm.org/build#run)
+
+The following steps explain how to configure a Swarm node in NextCloud.
+
+- Install the "External Storage: Swarm" app from the Nextcloud App store
+- Navigate to External Storage Administration (Profile menu -> Settings -> External Storage)
+- Add the connection settings for a new Swarm node
+- Navigate to Ethswarm Storage Administration (Profile menu -> Settings -> Ethswarm Storage)
+- Configure the Swarm node - by default, encryption is active
+- To use a swarm node, it is necessary to [Purchase a Batch of new stamps](https://docs.ethswarm.org/docs/access-the-swarm/keep-your-data-alive) from the funds in the chequebook
+
+- Once the new batch is purchased, a unique batchId is generated. Once your batch has been purchased, it will take a few minutes for other Bee nodes in the Swarm to catch up and register your batch. Allow some time for your batch to propagate in the network before proceeding to the next step. This is indicated by the checkbox "Usable".
+- Uploading files to the swarm costs Bzz, so it is necessary to select a Batch as "Active". Only 1 batch is allowed to be Active for a given swarm node. Then click "Save Settings".
+
+## Using the Swarm
+
+Once setup and configured, the swarm node is ready to use.
+- Navigate to "Files" option on the menu -> "External Storage" and then the name of the Swarm node.
+- Click to Upload file(s):
+
+<img alt="Upload file" src="/assets/images/swarm_Files_UploadFile.png">
+<em>Upload file to swarm in Nextcloud</em>
+
+- Once uploaded, it can be viewed internally or downloaded. It can also be copied to another storage.
+
+<img alt="View file and action menu" src="/assets/images/swarm_Files_ViewFile.png">
+<em>View, download, and file view actions in Nextcloud</em>
+
+
+- Files from another Nextcloud storage can also be copied/moved to the Swarm node. Choose the Swarm node as the target Folder
+
+<img alt="Upload file" src="/assets/images/swarm_CopyMove.png">
+<em>Upload file to swarm in Nextcloud</em>
+
+## Limitations
+
+Not all adminstrative operations are available in the plugin. For an up-to-date list of available apps, please consult the [documentation](https://www.ethswarm.org/build#run)
 
 ## License