README.md 6.84 KB
Newer Older
gboudrias's avatar
gboudrias committed
1 2 3
Aegir SaaS
==========

4
This module sets up a fully functional endpoint (via the [Aegir Services API](https://www.drupal.org/project/hosting_services)) allowing for remote administration of sites, notably installing new sites and cloning existing sites.  It provides common parameters for site creation as configured in the module's settings.  Using the API's task resource, sites can also be disabled, enabled, deleted, and have any other task performed on them supported by your [Aegir](https://www.drupal.org/project/hostmaster) installation.
gboudrias's avatar
gboudrias committed
5

6
## What this module does
gboudrias's avatar
gboudrias committed
7

8 9 10 11 12 13 14
1. It creates the *aegir web services* role.
2. It creates the *Aegir SaaS* user (placed in the above role).
3. It adds necessary permissions for the user to issue remote commands (getting site information and running tasks).
4. It configures the new *aegir/saas* [Services](https://www.drupal.org/project/services) endpoint (over at http://example.com/aegir/saas for example).
5. It associates remote commands on the endpoint with the new user.
6. It sets up [API-key-based authentication](https://www.drupal.org/project/services_api_key_auth) on the endpoint.
7. It enables the necessary resources required.
15
8. It allows you to run tasks on sites with their site names; you don't need their node IDs.
gboudrias's avatar
gboudrias committed
16

17
The primary feature of this module is its ability to create new sites with your desired settings.
gboudrias's avatar
gboudrias committed
18

19
The endpoint uses API-key authentication by default, but **it will NOT be usable** (the key will change randomly) until you save its configuration.  This is a security feature that prevents the endpoint from being active until you explicitly enable it.
gboudrias's avatar
gboudrias committed
20

21 22 23 24 25 26 27 28 29 30 31 32
## Dependencies / required modules

* [Services](https://www.drupal.org/project/services)
* [Aegir Services](https://www.drupal.org/project/hosting_services)
* [Services API Key Authentication](https://www.drupal.org/project/services_api_key_auth)
* [Hosting Variables](https://www.drupal.org/project/hosting_variables)

## Installation and set-up

1. Become the Aegir user on your Aegir server.
    * sudo -sHu aegir
2. Download the necessary modules.
33
    * drush @hm dl hosting_services services services_api_key_auth hosting_variables --destination=$(drush dd @hm:%site)/modules/contrib
34 35
3. Enable the Aegir SaaS module.
    * drush @hm en hosting_saas
36 37 38 39
4. Set the emanating e-mail address for new sites.  This is taken from the Aegir SaaS user just created so we need to set its e-mail address.
    * Surf to Administration » People » Aegir SaaS » Edit.
    * Enter your preferred e-mail address in the *E-mail address* field.  You'll probably want something like `do-not-reply@YOUR_DOMAIN`.
5. Save your new automatically generated API key.
40
    * Surf to Administration » Structure » Services.
41
    * Click on the *Edit Authentication* item in the Operations pull-down menu of *hosting_saas*.
42
    * Hit the *Save* button.
43
6. Configure your settings for creating new sites.
44 45 46 47 48
    * Surf to Administration » Hosting » SaaS.
    * Enter/change the *Basic settings* form, and then save it.
    * Enter/change the *Site handovers* form, and then save it.
    * Enter/change the *Injected variables* form, and then save it.

49
For site creation tasks, some arguments do not need to be provided on the main settings form; they can be provided in remote requests.  Request parameters will override configured values in the settings.
50 51 52 53 54 55

## Client usage

### Example

You can test your endpoint with [cURL](https://en.wikipedia.org/wiki/CURL) on the command line:
gboudrias's avatar
gboudrias committed
56

57
    curl --data "api-key=your-api-key&type=clone&options[new_uri]=mynewsite.com&target=&options[testing]=test" http://example.com/aegir/saas/task
gboudrias's avatar
gboudrias committed
58

59
As you can see, you need to specify the *target* parameter for Services to accept the request, but it can be empty if you want it to be overriden with the default site *target* in the SaaS settings. (*target* is the site to clone, and is entered as the site's name. We're calling it *target* instead of *site* because we may want to support platforms or other target types later.)
60 61 62 63 64

If there are errors, you should receive an empty XML response. Errors related to settings will appear in the Recent Logs report (if you have the Database Logging module enabled; it is not enabled by default on Aegir).

### Service call details

65 66 67 68 69
For each of these, the following should be set as a header parameter, but you can also pass it in the URL (not recommended as less secure).  See [Services API Key Authentication](https://www.drupal.org/project/services_api_key_auth) for more information.


* `api-key=super-secret-random-key`

70 71 72 73
#### Using GET

##### List all sites

74
* http://aegir.example.com/aegir/saas/site.json
75 76 77

##### Get information on a particular site

78
* http://aegir.example.com/aegir/saas/site/aegir.example.com.json
79 80 81 82 83

#### Using POST

##### Create site Clone task

84
* http://aegir.example.com/aegir/saas/task
85
* Form data:
86
    * **target**: *template.example.com* (optional if in settings)
87 88
    * **type**: *clone*
    * **options[new_uri]**: *client1.example.com*
89
    * **options[database]**: *12* (DB server node ID, if not in settings)
90
    * **options[target_platform]**: *24* (Platform node ID, if not in settings)
91 92
    * **options[client_email]**: *jane.doe@example.com* (if set up in *Site handovers* configuration)
    * **options[client_name]**: *jane.doe* (if set up in *Site handovers* configuration)
93 94
    * **options[...]**: (arguments set in your *Injected variables* configuration)

95 96
##### Create site Install task

97
* http://aegir.example.com/aegir/saas/task
98
* Form data:
99
    * **target**: *client1.example.com*
100 101 102 103
    * **type**: *install*
    * **options[profile]**: *standard* (installation profile short name / ID, if not in settings)
    * **options[database]**: *12* (DB server node ID, if not in settings)
    * **options[platform]**: *24* (Platform node ID, if not in settings)
104
    * **options[language]**: *en* (Language code for Drupal installation)
105 106 107 108
    * **options[client_email]**: *jane.doe@example.com* (if set up in *Site handovers* configuration)
    * **options[client_name]**: *jane.doe* (if set up in *Site handovers* configuration)
    * **options[...]**: (arguments set in your *Injected variables* configuration)

109 110
##### Create site Disable task

111
* http://aegir.example.com/aegir/saas/task
112
* Form data:
113
    * **target**: *client1.example.com*
114 115 116 117
    * **type**: disable

##### Create site Enable task

118
* http://aegir.example.com/aegir/saas/task
119
* Form data:
120
    * **target**: *client1.example.com*
121 122 123
    * **type**: enable

##### Create site Delete task
gboudrias's avatar
gboudrias committed
124

125
* http://aegir.example.com/aegir/saas/task
126
* Form data:
127 128
    * **target**: *client1.example.com*
    * **type**: delete
colan's avatar
colan committed
129 130 131 132

#### Manipulating Site Variables

Besides being set initially in the module configuration via the *Injected variables* tab, Aegir-controlled site variables can be indexed, created, retrieved, updated and deleted (CRUD) remotely later.  See [that module's documentation](http://cgit.drupalcode.org/hosting_variables/tree/README.md) for information on working with this resource.