Config dist

.gitignore

@@ -1,4 +1,5 @@
 secrets.php
 proxy/file_cache
+proxy/config.php
 debug.log
-.idea
+.idea

docs/configuration.md

@@ -1,20 +1,20 @@
 # How to configure CiviProxy
 !!! caution
-    We assume you have a very basic understanding of PHP and editing PHP files. If you do not, it is probably a good idea to get some support from a CiviCRM expert. You can find one on [Find an Expert](https://civicrm.org/partners-contributors). 
+    We assume you have a very basic understanding of PHP and editing PHP files. If you do not, it is probably a good idea to get some support from a CiviCRM expert. You can find one on [Find an Expert](https://civicrm.org/partners-contributors).
 ## Configuration of the CiviCRM extension
 You can use CiviProxy to do a couple of things related to mails and mailing for you.
 
 * You can still see all the stuff on the CiviMailing report like the click-throughs and bounces and such.
 * You do not want the links in your bulk mailing or individual mails to immediately feed back to your CiviCRM installation but pass through CiviProxy.
 * You want your subscribe/unsubscribe links to pass through CiviProxy rather than go directly to your CiviCRM installation.
 
-If you want to do any of these things, you will need to install and configure the CiviCRM extension **de.systopia.civiproxy** in your CiviCRM installation. 
+If you want to do any of these things, you will need to install and configure the CiviCRM extension **de.systopia.civiproxy** in your CiviCRM installation.
 
 If you have not installed the extension already, check [Installing CiviCRM](installation.md) for instructions how to.
 
 !!! note
     If you do not install the **de.systopia.civiproxy** extension you can still use CiviProxy to whitelist your API requests.
-    
+
 Once you have installed the CiviCRM extension you will need to configure the CiviProxy settings. To do this, go to **Administer>Administration Console**. You will see the CiviProxy Settings in the System Settings section of the menu as you can see below.
 
 ![Administration Console - System Settings](img/administration_console.png)
@@ -36,17 +36,21 @@ The CiviProxy server is the actual policeman that receives all requests and deci
 
 Once you have installed your CiviProxy server you need to complete a few configuration steps.
 ### The Config.php file
-The configuration of CiviProxy is mainly controlled with one PHP file called `config.php`. You will need to locate that file in your CiviProxy scripts:
+
+The configuration of CiviProxy is mainly controlled with one PHP file called `config.php`. Create this file by copying or renaming the `config.dist.php` file.
 
 ![List of files on your CiviProxy server](img/file%20list%20proxy.png)
+
 ### Configuring the URL of your CiviProxy server
+
 First thing you need to configure is the base URL of your CiviProxy server using the `$proxy_base` variable in the `config.php` file. As I have used a local test installation I have used `http://localhost/proxy`:
 ```php
  // this should point to the base address of the CiviProxy installation
  $proxy_base     = 'http://localhost/proxy';
 ```
 ### Configuring the link to the secure target CiviCRM
-Next thing you want to configure is what your target CiviCRM is. This is the CiviCRM installation which you want CiviProxy to police, so the one where the actual data resides and is collected from or sent to. 
+
+Next thing you want to configure is what your target CiviCRM is. This is the CiviCRM installation which you want CiviProxy to police, so the one where the actual data resides and is collected from or sent to.
 
 The assumption is that this CiviCRM resides in some kind of VPN and will accept traffic only from the CiviProxy IP address (and probably a few trusted others like home workers or support people).
 You can set the URL of the target CiviCRM using the variable `$target_civirm` in the `config.php` file. Again, I have used a local test installation:
@@ -92,7 +96,7 @@ If you set it to the value NULL this functionality will not be available on your
     );
     ```
     You can update these settings if you should want to.
-    
+
     You can find documentation on the caching engine used in CiviProxy [here](http://pear.php.net/manual/en/package.caching.cache-lite.cache-lite.cache-lite.php)
 ### Setting for the view unformatted mail link
 If CiviCRM sends a mail you can get a link to view the mail unformatted. CiviProxy keeps this setting in a variable `$target_mail_view` in the `config.php` file:
@@ -130,7 +134,7 @@ Whatever method you prefer, you will have to end up with an array like the one b
 $api_key_map = array('eR1k!tSt4321' => 'cal1Mer0#tST');
 $sys_key_map = array('1234#tsT#eR1k' => 'p1P0!tEst1Ng5678');
 ```
-As you can see you can give the application that is accessing you different keys than the ones you use to access your target CiviCRM. 
+As you can see you can give the application that is accessing you different keys than the ones you use to access your target CiviCRM.
 
 So in this example I will explain to the party wanting to access my CiviProxy that they have to use the key _1234#tsT#eR1k_ and the api key _eR1k!tSt4321_. My target CiviCRM will expect site key _p1P0!tEst1Ng5678_ and the api key _cal1Mer0#tST_.
 
@@ -184,17 +188,17 @@ $rest_allowed_actions = array(
 
 !!! caution
     A little bit of developer background....Obviously you can use the core CiviCRM API's but you have to think carefully of the parameter sanitation. Techically what happens is that if any parameters are passed to CiviProxy that are not _allowed_, they are ignored when the API request is passed to CiviCRM. This could lead to undesired behaviour. Consider this example:
-    
+
     * we have allowed the `Contact Get` API with only the parameter `email`
-    
+
     * the request we get in CiviProxy has the `Contact Get` but the parameters `first_name` and `last_name`
-    
-    * because `first_name` and `last_name` are not whitelisted, they get ignored and a `Contact Get` without parameters if passed to the target CiviCRM, returning the first 25 contacts are a result...which is not what we wanted. 
-    
+
+    * because `first_name` and `last_name` are not whitelisted, they get ignored and a `Contact Get` without parameters if passed to the target CiviCRM, returning the first 25 contacts are a result...which is not what we wanted.
+
     We recommend solving these situations by developing specific API's rather than using the core ones. And if you think of a good solution feel free to raise an issue or do a PR!
-    
+
 ### Debug setting
-CiviProxy has a `$debug` setting which allows you to add the name of a text file where all requests are send to. This can be used during the initial testing to see if everything is processed correcty. 
+CiviProxy has a `$debug` setting which allows you to add the name of a text file where all requests are send to. This can be used during the initial testing to see if everything is processed correcty.
 ```php
 // CAREFUL: only enable temporarily on debug systems. Will log all queries to given PUBLIC file
 $debug                      = NULL; //'debug.log';
@@ -206,10 +210,10 @@ If you set the `$debug` setting to NULL this feature will not be used.
 ### Target Interface setting
 There is a setting for a local network interface or IP to be used for relayed queries. If you have no idea what this is about, just leave it as is.
 ```php
-// Local network interface or IP to be used for the relayed query 
+// Local network interface or IP to be used for the relayed query
 // This is usefull in some VPN configurations (see CURLOPT_INTERFACE)
 $target_interface           = NULL;
 ```
 
 !!! tip
-    We do advice you to monitor what request are still being fired directly to your target CiviCRM once you installed and configured CiviProxy, and then find solutions for the situations if you still see some undesired access requests.
+    We do advice you to monitor what request are still being fired directly to your target CiviCRM once you installed and configured CiviProxy, and then find solutions for the situations if you still see some undesired access requests.

docs/installation.md

@@ -2,14 +2,14 @@
 CiviProxy has to run on its own server (with its own IP address) for maximum effect.
 
 The best option for a server on which you can install CiviProxy is a simple managed webspace, that you can rent cheaply from the hoster of your choice. It should have its own IP address, but other than that there are virtually no restrictions. This approach comes with a lot of advantages:
- 
+
 * Since there are a multitude of clients like you on such a server, the level of security can be expected to be very high, and it should be managed and monitored by professionals 24/7.
-* For the same reason, the bandwith and connectivity of such a server should be very high as well. 
+* For the same reason, the bandwith and connectivity of such a server should be very high as well.
 * The price should not have to be huge.
 
 !!! note
     Obviously there is nothing stopping you from installing CiviProxy on a server you manage yourself, but that then automatically means you have to ensure you maintain a high level of security and update the stuff regularly!
-    
+
 Installing CiviProxy should be pretty straightforward:
 
 * Download the GitHub repository from [https://github.com/systopia/CiviProxy](https://github.com/systopia/CiviProxy).
@@ -21,34 +21,36 @@ Installing CiviProxy should be pretty straightforward:
         * LIBRARIES.md
         * LICENSE
         * README.md
-        * mkdocs.yml 
+        * mkdocs.yml
 ## Installing the CiviCRM extension on your target CiviCRM
 * copy the folder **de.systopia.civiproxy** that you downloaded in the previous step into your CiviCRM extensions folder. You should be able to find your civicrm extensions folder in **Administer>System Settings>Directories**. If you have never touched or changed this it will look like screen print below. In that case your folder is probably `<your civicrm folder>/sites/default/files/civicrm/ext/`
 
 !!! seealso
     ![Screen print of the Administer>System Settings>Directories form](img/civicrm_directories.png)
-     
+
 * go to **Administer>System Settings>Extensions** to see a page with all the installed extensions on your CiviCRM installation. You will have to click the **Refresh** button to see the **de.systopia.civiproxy** extension. Click the **Install** action listed behind the extension information. Upon successfull installation you should see a list like the one below (although you will probably see a larger list as you will have more extensions installed).
 
 !!! seealso
     ![Screen print of the extensions page after successfull installation](img/extensions_list.png)
-    
+
 * type the URL`http://example.org/civicrm/clearcache` to clear the caches and rebuild the menu. This is necessary to add the CiviProxy settings page to CiviCRM.
 
-!!! note 
+!!! note
     use the URL `http://example.org/?q=civicrm/clearcache` if CleanUrls are not enabled
-    
+
 * you should now be able to access the CiviProxy Settings page with **Administer>Administration Console** (in the menu section System Settings) or with the URL `http://example.org/civicrm/admin/setting/civiproxy`.
 
-!!! note 
-    use the URL `http://example.org/?q=civicrm/admin/setting/civiproxy` if CleanUrls are not enabled 
+!!! note
+    use the URL `http://example.org/?q=civicrm/admin/setting/civiproxy` if CleanUrls are not enabled
 
 !!! note
     If you want to you can add the CiviProxy Settings page to your Administration menu with Administer/Customize Data and Screens/Navigation Menu.
-    
-* check the [Configuring CiviProxy](configuration.md) page to see how to configure the CiviProxy extension. 
+
+* check the [Configuring CiviProxy](configuration.md) page to see how to configure the CiviProxy extension.
 
 ## Installing the Proxy scripts your your CiviProxy server
-All you need to do is copy the **proxy** folder on the webspace you want to use for CiviProxy.
 
-As described in [Configuring CiviProxy](configuration.md), you will need to make changes to the `config.php` file. You can either do those changes locally first and then move all the files to your webspace, or move all the files to your webspace first and then changes the `config.php` file there.
+1. Copy the **proxy** folder on the webspace you want to use for CiviProxy
+2. Create a `config.php` file using `config.dist.php` as a template.
+
+See [Configuring CiviProxy](configuration.md) for  details on what you need to include in the `config.php` file.

proxy/config.php → proxy/config.dist.php

@@ -8,6 +8,13 @@
 +---------------------------------------------------------*/
 
 
+/****************************************************************
+ **                      INSTALLATION                          **
+ **                                                            **
+ **  1. Make a copy of this file called config.php             **
+ ****************************************************************/
+
+
 /****************************************************************
  **                            URLS                            **
  ****************************************************************/