From 0156e77379ac0462f4ee43c20a65e5e49f5404a6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@debian.org>
Date: Sat, 6 Jan 2018 22:33:25 -0500
Subject: [PATCH] introduce FAQ section

This is primarly made of documentation about password protection, but
will likely be expanded in the future.

See #220
---
 docs/faq.rst   | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst |  1 +
 2 files changed, 77 insertions(+)
 create mode 100644 docs/faq.rst

diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 0000000..ca93fae
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,76 @@
+==================================
+ Frequently Asked Questions (FAQ)
+==================================
+
+How do I protect the gallery with a password?
+---------------------------------------------
+
+Sigal simply generates HTML pages, there is no server process that
+could handle a password protection. So the password has to be handled
+in your web server (Apache, Nginx, etc). A complete treatise on
+webserver configuration is beyond the scope of this document, but, for
+example, you may get started with Apache with the `official
+documentation
+<https://httpd.apache.org/docs/2.2/en/howto/auth.html#gettingitworking>`_.
+
+Here is an example Apache configuration, assuming your gallery was
+built in ``/var/www/sigal/_build``::
+
+  <Directory /var/www/sigal/_build>
+      AuthType Basic
+      AuthName "Restricted Content"
+      AuthUserFile /etc/apache2/htpasswd
+      Require valid-user
+  </Directory>
+
+You will then need to create username/password combinations in the
+``/etc/apache2/htpasswd`` using the `htpasswd command
+<https://httpd.apache.org/docs/2.4/programs/htpasswd.html>`_.
+
+How do I protect only *some* folders of the gallery with a password?
+--------------------------------------------------------------------
+
+This is more complicated than the above. Assuming you want to protect
+only the ``foo/`` subdirectory, the following will unfortunately not
+do what you expect::
+
+  <Directory /var/www/sigal/_build/foo>
+      AuthType Basic
+      AuthName "Restricted Content"
+      AuthUserFile /etc/apache2/htpasswd
+      Require valid-user
+  </Directory>
+
+It *will* protect the folder with a password, but, because of the
+thumbnails shown on the main page, the web browser will prompt the
+user for a password on the parent directory as well, which will
+confuse users and is probably not what you want.
+
+The trick is then to whitelist the thumbnail files. Here we'll assume
+you will name the thumbnail files ``public.jpg`` and then configure
+those files to be visible even in the private section, like so::
+
+  <Directory /var/www/sigal/_build/foo>
+      AuthType Basic
+      AuthName "Restricted Content"
+      AuthUserFile /etc/apache2/htpasswd
+      Require valid-user
+  </Directory>
+
+  <Files "public.jpg">
+      Satisfy any
+  </Files>
+
+Then just make sure, through the album information mechanism, that the
+right image is chosen as a thumbnail for that album, for example, in
+``foo/index.md``::
+
+  Title: Private section
+  Thumbnail: public.jpg
+
+Et voilà! You now have a hybrid private/public gallery. This is not
+recommended for highly sensitive pictures; because other parts of
+Sigal may (eventually?) leak information about filenames, thumbnails
+or even contents without your knowledge in the future. But it's a good
+simple way to add basic snooping protection over certain areas with
+minimal configuration.
diff --git a/docs/index.rst b/docs/index.rst
index 2f16bc5..ceebf29 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,5 +13,6 @@ Documentation
    image_information
    themes
    plugins
+   faq
    contribute
    changelog