Release 1.4.1: Improved documentation

Author: Michel Casabianca

Diff for: CHANGELOG.yml

@@ -1,5 +1,9 @@
 # Semantic changelog: https://github.com/c4s4/changelog
 
+- version: 1.4.1
+  date:    2015-07-30
+  summary: Improved documentation
+
 - version: 1.4.0
   date:    2015-07-30
   summary: Added HTTPS support

Diff for: README.md

@@ -68,7 +68,10 @@ You may also pass the path to the configuration file on the command line:
 
     $ cheeseshop /path/to/cheeseshop.yml
 
-This configuration file should look like this:
+Configuration
+-------------
+
+The configuration file should look like this:
 
     # The root directory for packages
     root:  /home/cheeseshop
@@ -91,30 +94,69 @@ This configuration file should look like this:
         spam: acbd18db4cc2f85cedef654fccc4a4d8
         eggs: 37b51d194a7513e45b56f6524f2d51f2
 
-To compute MD5 sum for a given password, in order to fill the authentication file, you may type following command :
+There is a sample configuration in file *etc/cheeseshop.yml* of the archive.
 
-    $ echo -n foo | md5sum
-    acbd18db4cc2f85cedef654fccc4a4d8  -
-    $ echo -n bar | md5sum
-    37b51d194a7513e45b56f6524f2d51f2  -
+### root
 
-There is a sample configuration file in *etc* directory of the archive.
+The root directory is where live the Python packages. Under this root there is a directory for each package. Files for versions of this package are in these subdirectories. Thus, if our repository hosts packages *spam* (in versions *1.0.0* and *1.1.0*) and *eggs* (in versions *1.0.0* and *1.0.1*) we would have following directory structure :
 
-Of course, you must create an empty directory for the repository. Ensure that the user running CheeseShop has a right to write in this directory.
+    $ tree
+    .
+    ├── spam
+    │   ├── spam-1.0.0.tar.gz
+    │   └── spam-1.1.0.tar.gz
+    └── eggs
+        ├── eggs-1.0.0.tar.gz
+        └── eggs-1.0.1.tar.gz
 
-To disable HTTP or HTTPS, you must set port to *0*. If HTTPS is disabled, you don't have to set certificate and key paths. To disable basic authentication, you must set auth to `~` (which means none in YAML).
+You must create this directory and ensure that user running the server has a right to write in this directory.
 
-To generate a key, you can use openssl as follows:
+It is highly advised to backup this directory.
+
+### key
+
+This is the path to the CheeseShop private key. To generate such a key, you might type:
 
     $ openssl genrsa -out cheeseshop-key.pem 2048
 
-To generate au self signed certificate, you can type:
+This will generate a file *cheeseshop-key.pem* that you should copy in directory */etc/ssl/private*, which is the standard place.
+
+This is only necessary when running HTTPS server. If you run only HTTP, you may set this value to *~*.
+
+### cert
+
+This is the path to the CheeseShop certificate. To generate a self signed certificate, you can type:
 
     $ openssl req -new -x509 -key cheeseshop-key.pem -out cheeseshop-cert.pem -days 3650
 
-This command will ask you many fields, but the only that is necessary is the *FQDN* which is the hostname of the machine that is running CheeseShop.
+This command will ask you many fields, but the only that is necessary is the *FQDN* which is the hostname of the machine that is running CheeseShop. A file named *cheeseshop-cert.pem* will be generated; you should copy this file in directory */etc/ssl/certs*, which is the standard place.
+
+Note that if you have a certificate generated by a Certification Authority, you might not have to add a *trusted-host* in your PIP configuration. But I have such certificate and was unable to test it.
+
+### http
+
+This the port number that HTTP server will listen for incoming connections. Set it to *0* to disable HTTP (and run only on HTTPS). Note that it is not a good idea to perform basic authentication on HTTP, as anybody that intercepts HTTP requests might know you username and password. Standard port for HTTP is *80* but the server must run as root to be able to listen on this port. If you don't run the server as root, you must listen on a port number greater than *1024*.
+
+### https
+
+This is the port number that HTTPS server is listening. Set it to *0* to disable HTTPS. If HTTPS is enabled, you must provide private key and certificate (in *key* and *cert* configuration fields). Standard port for HTTPS is *443* but the server must run as root to be able to listen on this port. If you don't run the server as root, you must listen on a port number greater than *1024*.
+
+### path
+
+This is the URL path that the server will listen. Default value is *simple*, thus to list all packages, you should open URL <http://my.shop.host/simple>. To list available version for package *spam*, you would open URL <http://my.shop.host/simple/spam>. To download version *1.2.3* of this package, you would open <http://my.shop.host/simple/spam/spam-1.2.3.tar.gz>. This value should not be changed.
+
+### shop
+
+This is the URL of the public package repository, aka <http://pypi.python.org/simple>. This should not be changed.
+
+### auth
+
+This is the basic authentication configuration. If you don't want authentication, set this value to *~*. This is a list of usernames and MD5 hash of their password. To get the MD5 hash of a given password, you can type following command:
+
+    $ echo -n foo | md5sum
+    acbd18db4cc2f85cedef654fccc4a4d8  -
 
-You should copy the certificate in directory */etc/ssl/certs* and the key in */etc/ssl/private*.
+Note that if you modify this configuration, you must restart server, because this configuration is loaded at startup.
 
 Service
 -------