Documentation/v1.0.0 rc1 doc update

docs/source/code.rst

@@ -11,12 +11,16 @@ Python Modules
 
     swift_browser_ui._convenience
     swift_browser_ui.api
+    swift_browser_ui.discover
     swift_browser_ui.exceptions
     swift_browser_ui.front
     swift_browser_ui.login
+    swift_browser_ui.middlewares
+    swift_browser_ui.misc_handlers
     swift_browser_ui.server
     swift_browser_ui.settings
     swift_browser_ui.shell
+    swift_browser_ui.signature
 
 
 :ref:`genindex` | :ref:`modindex`

docs/source/deploy.rst

@@ -21,12 +21,88 @@ Using vanilla docker in order to build the image - the tag can be customised:
                  -e BROWSER_START_AUTH_ENDPOINT_URL=https://pouta.csc.fi:5001/v3 \
                  cscfi/swift-ui
 
+Database for sharing functionality
+----------------------------------
+Both ``swift-x-account-sharing`` and ``swift-sharing-request`` services need
+access to a PostgreSQL database in order to work. In a usual deployment this
+is done within a containerized stack. Necessary files to build a database
+container for testing can be found in the `deployment example repository. <https://github.com/CSCfi/swift-ui-deployment/>`_
+The file ``init-project-db.sh`` contains the necessary input to build the DB
+schema, and the same commands can be used to build the schema into an existing
+database server (as is the case when running on openshift using a base image
+for the database)
 
+Sharing functionality back-end
+------------------------------
+Sharing functionality should be run by running it in a container. Easiest
+way to do this is to use the docker-compose fiels provided in the 
+`deployment example repository. <https://github.com/CSCfi/swift-ui-deployment/>`_
+The sharing functionality requires the following environment variables to be
+present in order to work:
+
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| Environment variable     | Default      | Required | Description                                                                         |
++==========================+==============+==========+=====================================================================================+
+| SWIFT_UI_API_AUTH_TOKENS |              | True     | Comma separated list of master tokens that can be used for signing the API requests |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| SHARING_DB_NAME          | swiftsharing |          | Name for the sharing functionality database                                         |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| SHARING_DB_USER          | sharing      |          | User used in connecting to the sharing functionality database                       |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| SHARING_DB_HOST          |              | True     | Sharing functionality database address/hostname                                     |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| SHARING_DB_PASSWORD      |              | True     | Sharing functionality database password                                             |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+
+Shared access request back-end
+------------------------------
+Shared access request functionality should be run by running it in a
+container. Easiest way to do this is to use the docker-compose files provided
+in the `deployment example repository. <https://github.com/CSCfi/swift-ui-deployment/>`_
+The shared access request functionality requires the following environment variables
+to be present in order to work:
+
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| Environment variable     | Default      | Required | Description                                                                         |
++==========================+==============+==========+=====================================================================================+
+| SWIFT_UI_API_AUTH_TOKENS |              | True     | Comma separated list of master tokens that can be used for signing the API requests |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| REQUEST_DB_NAME          | swiftrequest |          | Name for the shared access request functionality database                           |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| REQUEST_DB_USER          | request      |          | User used in connecting to the shared access request functionality database         |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| REQUEST_DB_HOST          |              | True     | Shared access request functionality database address/hostname                       |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+| REQUEST_DB_PASSWORD      |              | True     | Shared access request functionality database password                               |
++--------------------------+--------------+----------+-------------------------------------------------------------------------------------+
+
+Upload runner back-end
+----------------------
+SwiftUI upload runner should be run by running it in a container. Easiest way
+to do this is to use the docker-compose files provided in the 
+`deployment example repository. <https://github.com/CSCfi/swift-ui-deployment/>`_
+The upload runner requires the following environment variables to be present
+in order to work:
+
++---------------------------------+---------+----------+-------------------------------------------------------------------------------------------------------------+
+| Environment variable            | Default | Required | Description                                                                                                 |
++=================================+=========+==========+=============================================================================================================+
+| SWIFT_UI_API_AUTH_TOKENS        |         | True     | Comma separated list of master tokens that can be used for signing the API requests                         |
++---------------------------------+---------+----------+-------------------------------------------------------------------------------------------------------------+
+| BROWSER_START_AUTH_ENDPOINT_URL |         |          | Openstack keystone endpoint for authentication – can also be specified with OS_AUTH_URL                     |
++---------------------------------+---------+----------+-------------------------------------------------------------------------------------------------------------+
+| OS_AUTH_URL                     |         |          | Openstack keystone endpoint for authentication – can also be specified with BROWSER_START_AUTH_ENDPOINT_URL |
++---------------------------------+---------+----------+-------------------------------------------------------------------------------------------------------------+
+
+The authentication information can also be gotten through sourcing any
+Openstack credential v3 file, the password is not necessary as only the
+authentication endpoint information will be used.
 
 Kubernetes Integration
 ----------------------
 
-For use with Kubernetes we provide ``YAML`` configuration.
+For use with Kubernetes we provide ``YAML`` configuration. Further
+configuration files are provided in `deployment example repository <https://github.com/CSCfi/swift-ui-deployment/>`_
 
 .. code-block:: yaml
 

docs/source/index.rst

@@ -14,6 +14,7 @@ endpoints provided by `OpenStack Keystone <https://docs.openstack.org/keystone/l
 Out of the box the ``swift-browser-ui`` offers:
 
 * UI for browsing `SWIFT objects <https://docs.openstack.org/swift/latest/>`_;
+* support for additional features like uploading files >5GiB in size;
 * support for federated authentication of an user with their HAKA credentials
   using OpenStack Keystone;
 * UI based on `Vue.js <https://vuejs.org/>`_ with `Buefy framework <https://buefy.org/documentation>`_;
@@ -24,14 +25,17 @@ Out of the box the ``swift-browser-ui`` offers:
    :maxdepth: 2
    :caption: Contents:
 
-    Setup Instructions       <instructions>
-    Usage & Examples         <usage>
-    Deployment               <deploy>
-    Architecture             <tech>
-    User Interface           <ui>
-    Python Modules           <code>
-    Testing                  <testing>
-    Tools / Miscellaneous    <tools>
+    Setup Instructions         <instructions>
+    Usage & Examples           <usage>
+    Deployment                 <deploy>
+    Architecture               <tech>
+    User Interface             <ui>
+    Sharing Backend            <sharing>
+    Access Request Backend     <request>
+    Upload, Download and Copy  <runner>
+    Python Modules             <code>
+    Testing                    <testing>
+    Tools / Miscellaneous      <tools>
 
 
 .. note:: ``swift-browser-ui`` and all it sources are released under *MIT License*.

docs/source/instructions.rst

@@ -10,8 +10,20 @@ The program can be installed with pip from the git repository:
 
     # Requires python >= 3.6
     git clone git@github.com:CSCfi/swift-browser-ui.git
+    # Frontend files need to be separately built
+    cd swift_browser_ui_frontend && npm run build && cd ..
     pip install .
 
+.. note:: The program uses external services that need to be present in order
+          to enable all functionality, like sharing. These additional services
+          can be found from the git repositories. The instructions for getting
+          the services up and running can be found in their respective
+          repositories, and partly under the *Deployment* section.
+
+          * https://github.com/cscfi/swift-x-account-sharing
+          * https://github.com/cscfi/swift-sharing-request
+          * https://github.com/cscfi/swiftui-upload-runner
+
 
 Environment Setup
 -----------------
@@ -26,15 +38,23 @@ Environment Setup
 
 Variables are depicted in the table below:
 
-+--------------------------------------+----------+-------------------------------------------------------------------------+
-| ENV                                  | Default  | Description                                                             |
-+--------------------------------------+----------+-------------------------------------------------------------------------+
-| ``BROWSER_START_AUTH_ENDPOINT_URL``  |          | Authentication endpoint. Address for OpenStack keystone API ``v3``.     |
-+--------------------------------------+----------+-------------------------------------------------------------------------+
-| ``BROWSER_START_PORT``               | ``8080`` |                                                                         |
-+--------------------------------------+----------+-------------------------------------------------------------------------+
-| ``BROWSER_START_SET_ORIGIN_ADDRESS`` |          | Authentication return address, to which the ``WebSSO`` redirects.       |
-+--------------------------------------+----------+-------------------------------------------------------------------------+
++----------------------------------------+---------+---------------------------------------------------------------+--+--+
+| Environment variable                   | Default | Description                                                   |  |  |
++========================================+=========+===============================================================+==+==+
+| ``BROWSER_START_AUTH_ENDPOINT_URL``    |         | URL to use as the authentication backend                      |  |  |
++----------------------------------------+---------+---------------------------------------------------------------+--+--+
+| ``BROWSER_START_PORT``                 | 8080    | Port that the service will listen                             |  |  |
++----------------------------------------+---------+---------------------------------------------------------------+--+--+
+| ``BROWSER_START_SET_ORIGIN_ADDRESS``   |         | Authentication return address to which WebSSO should redirect |  |  |
++----------------------------------------+---------+---------------------------------------------------------------+--+--+
+| ``BROWSER_START_SHARING_ENDPOINT_URL`` |         | URL for the container sharing backend                         |  |  |
++----------------------------------------+---------+---------------------------------------------------------------+--+--+
+| ``BROWSER_START_REQUEST_ENDPOINT_URL`` |         | URL for the shared access request backend                     |  |  |
++----------------------------------------+---------+---------------------------------------------------------------+--+--+
+| ``BROWSER_START_RUNNER_ENDPOINT``      |         | URL for the upload, copy, download runner                     |  |  |
++----------------------------------------+---------+---------------------------------------------------------------+--+--+
+| ``SWIFT_UI_SHARING_REQUEST_TOKEN``     |         | Token for signing the internal API requests                   |  |  |
++----------------------------------------+---------+---------------------------------------------------------------+--+--+
 
 .. hint:: Authentication endpoint can also be specified with any openrc file,
           which can be usually downloaded from Openstack. The setup script

docs/source/request.rst

@@ -0,0 +1,12 @@
+Shared access requests
+======================
+The UI provides the possibility to request access to a container from a known
+project, which can be done via the shared access request page. This can be
+found under the "Shared" page in the navbar.
+
+.. figure:: ./_static/images/sharing-request-view.png
+    :scale: 50%
+    :alt: Picture of the container access request page
+    :align: center
+
+    Image of the container access request page

docs/source/runner.rst

@@ -0,0 +1,83 @@
+Upload runnner
+==============
+The UI provides an improved upload proxy / runner, that provides a possibility
+for more complicated operations not normally present on the object storage Web
+interface – these operations include e.g. uploading files into an object
+storage container, and downloading a whole container with API call.
+
+
+File Upload
+-----------
+Files can be uploaded to an automatically generated container by drag'n'drop
+from the container listing page, or by using the upload button on top of the
+table. There's no limit on how large the files uploaded can be, but browser
+performance puts a practical limit somewhere in the neighborhood of 10GiB.
+
+Uploading files to a specific container can be done by opening the container,
+and uploading while the container is open. This can again be done either by
+drag'n'drop or using the upload button.
+
+.. hint:: If complete relative file paths or folder structure is to be
+          preserved, the only option for uploading is drag'n'drop. Only
+          files can be uploaded using the upload button
+
+.. hint:: Chrome is recommended as the browser of choice when uploading large
+          files, as the File API on Chrome is better implemented. Firefox tends
+          to have issues on files >5GiB, especially with multiple files. Safari
+          is not supported, but should work without problems – same issues
+          present with Firefox apply.
+
+.. hint:: Mobile devices are not supported for file uploads, but can work.
+          This is, however, not guaranteed.
+
+
+File Download
+-------------
+The upload runner is used to provide file downloads form shared containers in
+a similar manner to the way the downloads work from containers owned by the
+project that is currently active. To the user the download continues to be
+a simple download link
+
+
+Container Download
+------------------
+Full containers can be downloaded from the UI using the download button either
+on the table row in the container listing, or a download button on the top of
+the table when viewing an open container. Downloading whole containers works
+the same in both owned and shared containers. The runner archives the
+container while the download is taking place, in order to prevent aditional
+waiting for an archiving operation to finish. This has the added benefit of
+not requiring any intermediary storage for the archiving operation on the
+server side.
+
+.. hint:: Due to the fact that the archive size can't be precisely calculated
+          when archiving on the fly, the server is unable to provide a progress
+          bar for a container download. A rough estimate can be generated by
+          calculating the time value from the container size visible in the
+          container listing using the available speed of the connection.
+
+Copying a container
+-------------------
+Containers can be copied using the copy button, either on the row of the
+container in the container listing view, or on top of the table when viewing
+a specific container. The copy operation can only be performed to a fresh
+container, to prevent accidental data loss in case of an incomplete copy
+operation on an object. User can also copy a shared container to the
+currently activated project.
+
+.. hint:: The copy operation takes a long time, and is run in the background.
+          The UI navigates back to the normal view after copying is initiated.
+          Thus, the copy operation is eventually consistent.
+
+.. hint:: The runner validates every copied object against the file checksum
+          present in the object storage backend – thus, if the object is
+          present in the newly created container, it's guaranteed to have been
+          successfully copied over.
+
+.. figure:: ./_static/images/replication-view.png
+    :scale: 50%
+    :alt: Picture of the container replication view, when trying to replicate to an existing container
+    :align: center
+
+    Image of the container replication page when trying to copy over
+    an existing container