improve settings documentation
authorLunar <lunar@anargeek.net>
Fri, 24 Feb 2012 19:33:16 +0000 (20:33 +0100)
committerLunar <lunar@anargeek.net>
Fri, 24 Feb 2012 19:33:16 +0000 (20:33 +0100)
conf/settings-default.yml
conf/settings-imap.yml
conf/settings-simplepass.yml

index c148f54..cf17993 100644 (file)
@@ -1,12 +1,89 @@
+# Default settings for Coquelicot
+# ===============================
+#
+# Coquelicot is a "one-click" file sharing web application with a specific
+# focus on protecting users' privacy.
+#
+# This file contains the default settings and their meaning.
+#
+# These settings are only here for illustration purpose. Site specific
+# configuration only needs to specify the ones that need to be changed.
+
+# Base URL for Coquelicot
+#
+#   It should end with a '/'.
+#
+#   When empty, it will be computed dynamically using upcoming requests.
+#
+url: ""
+
+# Default expiration time (if unspecified by users)
+# (in minutes)
+#
 default_expire: 60
 default_expire: 60
-# 43200 == 60 * 24 * 30 == 1 month
+
+# Maximum expiration time that can be set by users
+# (in minutes)
+#
+#   Default: 43200 = 60 * 24 * 30 ≈ 1 month
+#
 maximum_expire: 43200
 maximum_expire: 43200
+
+# Time before complete cleanup of an expired file
+# (in minutes)
+#
+#   Once a file is expired either because of time or because
+#   it was set for only one download, Coquelicot will scrape
+#   the file content, but keep an empty file around to display
+#   a “Too late” message instead of the default “Not found”.
+#
+#   This setting will influence how long will users see the
+#   first message instead of the second in case they try to
+#   access an expired link.
+#
+#   Default: 10080 = 60 * 24 * 7 ≈ 1 week
+#
 gone_period: 10080
 gone_period: 10080
+
+# Number of characters in generated filenames
+#
+#   URL to download files looks like:
+#     https://example.org/dhut7f73u2hiwwifwyrs-gs5wj3ixjheg6dg7
+#     (when no password has been specified)
+#   or:
+#     https://example.org/dhut7f73u2hiwwifwyrs
+#
+#   This setting controls the first set of characters.
+#
 filename_length: 20
 filename_length: 20
+
+# Number of characters in generated passwords
+#
+#   When no password is specified URL looks like:
+#     https://example.org/dhut7f73u2hiwwifwyrs-gs5wj3ixjheg6dg7
+#
+#   This setting controls the second set of characters. The same
+#   code is also used when using the 'Generate password…' link.
+#
 random_pass_length: 16
 random_pass_length: 16
-depot_path: './files'
-about_text: ''
-additional_css: ''
+
+# Directory in which Coquelicot will write its files
+#
+depot_path: "./files"
+
+# Text to display on top of the upload form
+#
+about_text: ""
+
+# Path to an additional stylesheet
+additional_css: ""
+
+# Authentication method
+#
+#   Please have look at `conf/settings-simplepass.yml` and
+#   `conf/settings-imap.yml` for more details.
+#
+# The default password is 'test'.
 authentication_method:
 authentication_method:
-  name: 'simplepass'
-  upload_password: 'a94a8fe5ccb19ba61c4c0873d391e987982fbbd3'          
+  name: "simplepass"
+  upload_password: "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"
index 411d0f0..892f64f 100644 (file)
@@ -1,4 +1,17 @@
+# Settings for the IMAP authentication method
+# -------------------------------------------
+#
+# When using the IMAP authentication method users will be
+# asked for a login and a password. Those credentials will
+# be tested against the given IMAP server.
+#
+# Connections to the IMAP server are made using SSL/TLS.
+
 authentication_method:
   name: imap
 authentication_method:
   name: imap
-  imap_server: 'imap.example.com'
+
+  # Hostname of the authenticating IMAP server
+  imap_server: "imap.example.com"
+
+  # Port of the authenticating IMAP server
   imap_port: 993
   imap_port: 993
index 43e5c2d..b37201c 100644 (file)
@@ -1,3 +1,16 @@
+# Settings for the 'simplepass' authentication method
+# ---------------------------------------------------
+#
+# When using the 'simplepass' authentication method, users will
+# be asked for a pre-shared password.
+
 authentication_method:
   name: simplepass
 authentication_method:
   name: simplepass
-  upload_password: 'a94a8fe5ccb19ba61c4c0873d391e987982fbbd3'
+
+  # SHA1 of the pre-shared password
+  #
+  #   One way to compute the hash could be:
+  #
+  #       $ echo -n 'test' | sha1sum
+  #
+  upload_password: "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"