From fad3e70116038f9ec30f6fa26ba0b1c502aa1483 Mon Sep 17 00:00:00 2001
From: yuvipanda <yuvipanda@gmail.com>
Date: Fri, 27 Jul 2018 22:57:59 -0700
Subject: [PATCH] Add topic guide on tljh-config

---
 docs/howto/auth/dummy.rst  |  6 +--
 docs/index.rst             |  1 +
 docs/topic/tljh-config.rst | 81 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 85 insertions(+), 3 deletions(-)
 create mode 100644 docs/topic/tljh-config.rst

diff --git a/docs/howto/auth/dummy.rst b/docs/howto/auth/dummy.rst
index dc62893..8810867 100644
--- a/docs/howto/auth/dummy.rst
+++ b/docs/howto/auth/dummy.rst
@@ -18,14 +18,14 @@ Enabling the authenticator
 
 .. code-block:: bash
    
-   tljh-config set auth.DummyAuthenticator.password <password>
+   sudo -E tljh-config set auth.DummyAuthenticator.password <password>
 
    Remember to replace ``<password>`` with the password you choose.
 
 2. Enable the authenticator and reload config to apply configuration:
 
-   tljh-config set auth.type dummyauthenticator.DummyAuthenticator
-   tljh-config reload
+   sudo -E tljh-config set auth.type dummyauthenticator.DummyAuthenticator
+   sudo -E tljh-config reload
 
 Users who are currently logged in will continue to be logged in. When they 
 log out and try to log back in, they will be asked to provide a username and
diff --git a/docs/index.rst b/docs/index.rst
index 6fdf76c..93c8529 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -77,6 +77,7 @@ Topic guides provide in-depth explanations of specific topics.
    guides/admin
    topic/security
    topic/customizing-installer
+   topic/tljh-config
 
 
 Troubleshooting
diff --git a/docs/topic/tljh-config.rst b/docs/topic/tljh-config.rst
new file mode 100644
index 0000000..3e22e5f
--- /dev/null
+++ b/docs/topic/tljh-config.rst
@@ -0,0 +1,81 @@
+.. _topic/tljh-config:
+
+=====================================
+Configuring TLJH with ``tljh-config``
+=====================================
+
+``tljh-config`` is the commandline program used to make configuration
+changes to TLJH. 
+
+Running ``tljh-config``
+======================`
+
+You can run ``tljh-config`` in two ways:
+
+#. From inside a terminal in JupyterHub while logged in as an admin user.
+   This method is **recommended**.
+
+#. By directly calling ``/opt/tljh/hub/bin/tljh-config`` as root when
+   logged in to the server via other means (such as SSH). This is an
+   advanced use case, and not covered much in this guide.
+
+Set a configuration property
+============================
+
+TLJH's configuration is organized in a nested tree structure. You can
+set a particular property with the following command:
+
+.. code-block:: bash
+
+   sudo -E tljh-config set <property-path> <value>
+
+
+where:
+
+#. ``<property-path>`` is a dot-separated path to the property you want
+   to set.
+#. ``<value>`` is the value you want to set the property to.
+
+For example, to set the password for the DummyAuthenticator, you
+need to set the ``auth.DummyAuthenticator.password`` property. You would
+do so with the following:
+
+.. code-block:: bash
+
+   sudo -E tljh-config set auth.DummyAuthenticator.password mypassword
+
+
+This can only set string and numerical properties, not lists.
+
+View current configuration
+==========================
+
+To see the current configuration, you can run the following command:
+
+.. code-block:: bash
+
+   sudo -E tljh-config show
+
+This will print the current configuration of your TLJH. This is very
+useful when asking for support!
+
+Reloading JupyterHub to apply configuration
+===========================================
+
+After modifying the configuration, you need to reload JupyterHub for
+it to take effect. You can do so with:
+
+.. code-block:: bash
+
+   sudo -E tljh-config reload
+
+This should not affect any running users. The JupyterHub will be
+restarted and loaded with the new configuration.
+
+Advanced: ``config.yaml``
+=========================
+
+``tljh-config`` is a simple program that modifies the contents of the 
+``config.yaml`` file located at ``/opt/tljh/config.yaml``. ``tljh-config`` 
+is the recommended method of editing / viewing configuration since editing
+YAML by hand in a terminal text editor is a large source of errors.
\ No newline at end of file