Software Lifecycle (#43)

docs/src/lifecycle/diagnosis.rst

@@ -3,4 +3,58 @@
 Diagnosing Issues
 =================
 
-Coming soon!
+Titan strives to present error messages in an easy-to-consume, readable
+fashion. But the reality is that we can't anticipate everything, and as a
+relatively new community there are plenty of rough edges. If something
+goes wrong and the error message doesn't help you, this section provides
+some additional tools for you to try and self-diagnose the issue prior to
+engaging with the `Community <https://titan-data.io/community>`_.
+
+Docker Logs
+-----------
+The most important tool in the diagnosis tool belt is to look at the
+docker logs, specifically ``docker logs titan-server``. This will show the
+output of the server that is responding to requests from the CLI.
+Example output::
+
+    2019-09-30 16:18:27.223 [DefaultDispatcher-worker-4] INFO  ktor.application - 200 OK: GET - /v1/repositories/hello-world/operations/1dfadd4f-a376-4ab7-9f88-c7f4c1249634
+    2019-09-30 16:18:28.530 [DefaultDispatcher-worker-6] DEBUG io.titandata.util.CommandExecutor - Success: zfs, list, -Hpo, io.titan-data:active, titan/repo/hello-world
+    2019-09-30 16:18:28.535 [DefaultDispatcher-worker-6] DEBUG io.titandata.util.CommandExecutor - Success: zfs, list, -Ho, io.titan-data:metadata, titan/repo/hello-world/2db7b743-d643-4861-82db-71682e2ada26/v0
+    2019-09-30 16:18:28.537 [DefaultDispatcher-worker-6] INFO  ktor.application - 200 OK: POST - /VolumeDriver.Get
+    2019-09-30 16:18:28.548 [DefaultDispatcher-worker-6] INFO  i.t.storage.zfs.ZfsStorageProvider - unmount volume v0 in hello-world
+    2019-09-30 16:18:28.561 [DefaultDispatcher-worker-6] DEBUG io.titandata.util.CommandExecutor - Success: zfs, list, -Hpo, io.titan-data:active, titan/repo/hello-world
+    2019-09-30 16:18:28.640 [DefaultDispatcher-worker-6] DEBUG io.titandata.util.CommandExecutor - Success: umount, /var/lib/titan/mnt/hello-world/v0
+
+In particular, every REST call from the client is logged, along with
+every invocation of the zfs command. Understanding the semantics of the
+behavior is beyond the scope of this section, but an important thing to note
+is that any unexpected error should result in a stack trace that is quiet
+visible in the log. If you start at the end of the log and work your way
+backwards, if you find an exception that matches the behavior you're seeing,
+then it may contain more information that helps diagnose the problem.
+
+Docker State
+------------
+Sometimes the issue is not with titan, but with docker itself. For example,
+if you try to start a container that has a port mapping conflict with another
+container, it will fail to start. The CLI should display both the command
+and the output from docker, but if you're still not sure what is going
+on, you can try to run the command yourself and tweak some of the options
+to see if you can get it to work.
+
+Installation Issues
+-------------------
+When you're running ``titan install``, the server container may or may not
+be running successfully. In these cases, you can use ``docker logs titan-launch``
+to see what may be going on within the process. The lines denoted ``TITAN` are
+designed to be more user-readable, while the other error messages may be
+internal.
+
+Local Client Errors
+-------------------
+It's possible that there are errors in the client that don't manifest as calls
+to the container server. If this happens, and the problem is cannot be
+discerned from the error message, you'll need to reach out to the community
+for help. Once we have a better understanding of the problems that can
+occur client-side, we will look into building local debugging facilities
+within the command.

docs/src/lifecycle/supported.rst

@@ -3,4 +3,77 @@
 Supported Operating Systems
 ===========================
 
-Coming soon!
+Titan is designed to run on any system that supported docker, but there are
+some dependencies that limit the set of supported operation systems,
+especially on Linux.
+
+To help understand why this is necessary, it helps to understand a bit about
+the architecture of Titan. To make titan possible, there is a container
+(``titan-server``) running in the background that provides data versioning
+capabilities on top of `ZFS <http://openzfs.org>`_. This requires that ZFS
+be installed on the host operating system, but because of how out-of-tree
+kernel modules work, this needs to be done by the titan software (a
+container named ``titan-launch`` in particular). Titan attempts to provide
+pre-built versions for common OSes, as well as a means to build them on the
+fly for new versions, but there are limits to this system. If you are not
+on a supported operating system, you may find ``titan install`` taking
+a long time to build binaries, or failing outright.
+
+MacOS and Windows
+-----------------
+MacOS and Windows operate in a similar fashion, with an embedded
+`HyperKit <https://github.com/moby/hyperkit>`_ VM running Linux behind the
+scenes. This VM runs `LinuxKit <https://github.com/linuxkit/linuxkit>`_.
+Titan supports the latest Docker Desktop releases. If you are running a very
+old distribution (for example, using the old ``boot2docker`` framework on
+Windows), you mileage may vary. You should update to the latest version of
+Docker Desktop prior to using Titan.
+
+.. note::
+
+   If a brand new Docker Desktop release comes out that ships with a new
+   LinuxKit kernel, it may take some time for the community to update the
+   pre-built packages for the newest versions. If you encounter titan
+   trying to build packags for a new ZFS kernel, head over to the
+   `zfs-releases <https://github.com/titan-data/zfs-releases>`_ repository
+   and open an issue (or PR) with the new version and ``uname -a`` output.
+
+.. note::
+
+   Titan has not been tested and may or may not work with the new
+   `Docker for WSL <https://docs.docker.com/docker-for-windows/wsl-tech-preview/>`_.
+   This will be addressed shortly, but in the meantime only traditional
+   Docker Desktop is supported.
+
+Linux
+-----
+
+The situation with Linux is quite different. With Linux, there's no standard
+Docker VM being provided by Docker Desktop. Instead, we're running on whatever
+host VM you have. Because each distribution requires distro-specific mechanisms
+to download and install the right kernel files required to build ZFS, we have
+a much more limited support matrix. In addition, distros will often build
+specialized versions for different clouds (e.g. AWS, Azure, GCP), requiring
+specific builds for each of them. You're much more likely to encounter an
+unsupported platform when running Titan on Linux, but the community tries to
+provide pre-built binaries for:
+
+* Ubuntu Bionic (18.04) and later
+* CentOS 7 and later
+* LinuxKit as used by Docker Desktop
+
+If you are running one of these flavors and not finding pre-buit binaries
+available, it's likely just a matter of updating the
+`zfs-releases <https://github.com/titan-data/zfs-releases>`_ repository with
+the latest build information. If you are trying to use a different distribution
+alltogether, or are trying a new major version for the first time in the
+community, you may need to update the
+`zfs-builder <https://github.com/titan-data/zfs-builder>`_ repository such that
+it knows how to build the new variant.
+
+.. note::
+
+   If you are using an unsupported Linux version, you can always
+   `install ZFS <https://github.com/zfsonlinux/zfs/wiki/Building-ZFS>`_
+   yourself. Titan will use any installed ZFS, version 0.8.1 or later, and
+   won't attempt to install its own modules.

docs/src/lifecycle/uninstall.rst

@@ -3,4 +3,21 @@
 Uninstalling Titan
 ==================
 
-Coming soon!
+The :ref:`cli_cmd_install` command will install supporting Titan infrastructure
+automatically, including installing ZFS on the host or Docker VM if necessary.
+The :ref:`cli_cmd_uninstall` command will uninstall titan, destroying any
+repositories in the process.
+
+.. warning::
+
+   Uninstalling titan will remove all repositories. This operation cannot be
+   undone.
+
+If Titan was responsible for installing ZFS on the host VM, it will also
+uninstall ZFS. If ZFS was already present on the system when Titan was
+installed, then it will leave the ZFS installation as-is.
+
+.. note::
+
+   The process only uninstalls the supporting infrastructure. You will have to
+   manually remove the ``titan`` binary yourself.

docs/src/lifecycle/upgrade.rst

@@ -3,4 +3,33 @@
 Upgrading Titan
 ===============
 
-Coming soon!
+Titan can be automatically upgraded with the :ref:`cli_cmd_upgrade` command.
+This command works by:
+
+1. Downloading a newest version of the titan binary
+2. Finding the location of the ``titan`` binary in your ``PATH``.
+3. Copying over the new titan binary
+4. Running post-installation phase of the new binary, which may stop
+   all repositories and upgrade the titan docker container in the process.
+
+This will require access to download binaries from GitHub.
+If any parts of this fail, it should leave the original titan installation
+intact.
+
+.. warning::
+
+   As of version ``0.3.1``, upgrade is not currently working. This will be
+   addressed in a future release.
+
+.. note::
+
+   If your titan binary is not found in the PATH, you can specify the
+   ``--path`` option to point to where titan can be found.
+
+Manual Upgrade
+--------------
+Titan does not currently support upgrading to a titan binary that has been
+manually downloaded, such as when corporate firewalls prevent titan from
+automatically downloading from GitHub. Until this is supported, you will have
+to uninstall and re-install titan, destroying any active repositories in the
+process.