DOC: more about installing, maintaining

Author: slivingston

doc/install.rst

@@ -8,22 +8,27 @@ The details vary depending upon the hardware that you want to share. These
 instructions are work in progress, and contributions and feedback are welcome.
 Please open a ticket at https://github.com/rerobots/hardshare/issues
 
-Main concepts, components
--------------------------
+Installation instructions are provided for modern GNU/Linux distributions, such
+as Ubuntu_. We are working to support other kinds of hosts, including Windows,
+macOS, and FreeBSD.
+
+
+Main aspects
+------------
 
 There are 3 main aspects to an operational ``hardshare`` installation:
 
 1. API token for a rerobots_ user account,
-2. a container provider (also known as cprovider),
+2. a container provider (also known as *cprovider*),
 3. ``hardshare`` client.
 
 Instructions about getting an API token are `in the rerobots Web Guide
 <https://help.rerobots.net/webui.html#making-and-revoking-api-tokens>`_.
 
 Hardshare shares hardware among remote users through containers. The term
-"container" in the context of hardshare includes Linux containers. Supporting
-software that facilitates containers in hardshare are known cproviders. For new
-users, Docker is a good first cprovider to try and is indeed the default in a
+*container* in the context of hardshare includes Linux containers. Supporting
+software that facilitates containers in hardshare are known *cproviders*. For new
+users, Docker is a good first cprovider to try and is the default in a
 newly installed ``hardshare`` client configuration.
 
 Finally, the primary client is implemented in Python and `available via PyPI
@@ -41,14 +46,12 @@ In most cases, Docker images are available via Docker Hub. For example, ::
 
 which pulls the image from `Docker Hub <https://hub.docker.com/r/rerobots/hs-generic>`_.
 
-In the directory ``robots`` of the sourcetree, there are Dockerfiles that can be
-used to create images for containers that are known to work on some robot
-hardware, as described in the respective subdirectories. These can be `browsed
-on GitHub <https://github.com/rerobots/hardshare/tree/master/robots>`_.
-
-::
+This image and others are defined by Dockerfiles in the directory ``robots`` of
+the sourcetree. These can be `browsed on GitHub
+<https://github.com/rerobots/hardshare/tree/master/robots>`_. To build the image from source files::
 
   docker build -t hs.rerobots.net/generic:latest -f Dockerfile .
 
 
 .. _rerobots: https://rerobots.net/
+.. _Ubuntu: https://ubuntu.com/download/desktop

doc/maint.rst

@@ -3,3 +3,59 @@ Maintenance
 
 This page describes common routines for maintaining hardshare configurations and
 shared devices. Another page provides detailed discussion about :doc:`bestpractices`.
+
+
+.. highlight:: none
+
+Listing local configurations
+----------------------------
+
+::
+
+   hardshare --format=yaml config -l
+
+::
+
+  local:
+    err_keys: {}
+    keys:
+    - /home/scott/.rerobots/keys/jwt.txt
+    ssh_key: /home/scott/.ssh/unodist
+    version: 0
+    wdeployments:
+    - cargs: []
+      container_name: rrc
+      cprovider: podman
+      id: b47cd57c-833b-47c1-964d-79e5e6f00dba
+      image: hs-generic
+      init_inside: []
+      owner: scott
+      terminate: []
+  remote:
+    deployments:
+    - date_created: 2020-05-25 06:27 UTC
+      id: b47cd57c-833b-47c1-964d-79e5e6f00dba
+      origin: null
+    owner: scott
+
+
+Start, check, and stop daemons
+------------------------------
+
+::
+
+   hardshare ad -d
+   hardshare status
+   hardshare terminate
+
+
+Updating API tokens
+-------------------
+
+Remove any expired API tokens::
+
+  hardshare config -p
+
+Then, `get a new API token <https://rerobots.net/tokens>`_, and add it::
+
+  hardshare config --add-key path/to/your/jwt.txt