One-click service configurations for DNSimple.
Welcome to the home of the DNSimple service templates. The one-click services in DNSimple are defined as JSON configurations and loaded into our system at deploy time. This means that you can contribute a new template by creating a pull request, simplifying the process of creating and updating templates.
Read through the documentation below and look at the other templates in this repository before starting your own. If you have any questions feel free to get in touch with the DNSimple team using the [email protected] email address. Once you're ready to create your template, fork the project, add the template and issue a pull request.
If you have ruby installed then you can use the following steps to get a few rake tasks to make creating new service configurations easier:
gem install bundler --no-ri --no-rdoc
bundle install
Once you've done that you have access to several tasks:
To generate a new service definition:
rake generate[$name]
where $name is the short name of your service (for example: wordpress)
For example: rake generate[my-service]
To verify that a service definition meets our requirements for deployment:
rake verify[$name]
where $name is the short name of your service
For example: rake verify[blogger]
Services are each stored in their own directory. A service definition must have a config.json file and a logo.png file at minimum. The logo.png must be 228 pixels wide by 78 pixels high.
Services may have a readme.md file and/or an instructions.md file as well.
The JSON object defined in config.json holds all of the configuration details for the service. At minimum it must include the config section and the records collection with at least one record, however it may include the fields collection and a hook object as well.
The config section contains meta-data about the template. All of these attributes are required.
You have to choose one and only one category for your service:
To remove a specific service from the list of available one-click services, add the deprecated
attribute to the config section for that service. This prevents users from selecting that service, but keeps the existing configuration if it was applied to a domain before the deprecation. We don't delete any DNS records when a service is deprecated.
config {
...
"deprecated": true
}
A list of variable names and descriptions. These are presented to the user in the UI.
The variables are substituted into the content and name for each record when the template records are rendered into real records.
Each field may have the following attributes:
A list of record objects which are rendered to create the real records.
Each record may have the following attributes:
The name, type and content fields may use variables defined in the Attributes section as well as any values returned by the service hook.
Service records are rendered into the real records when the service is applied to a domain. All variables such as {{variable_name}} are replaced with attributes at this time. If a subdomain is provided then the record name is prepended to the subdomain which is joined with the domain name. For example, if the record name is "email", the subdomain is "staging", and the domain "example.com", the full record name will be "email.staging.example.com". If the record name is provided but the subdomain is omitted, then the full name would be "email.example.com". If the record name is omitted then it would be "staging.example.com". If the subdomain is omitted and the record name is omitted, then it would be "example.com".
In addition to custom attributes, there are also the following variables:
Service hooks provide a way to invoke a URL when the service is applied. This can be used to execute custom behavior at services.
One example service that uses hooks is CloudFlare. The hook is used to provision the domain in the CloudFlare system.
The url
attribute is a fully qualified URL that is invoked in one of several ways:
The following parameters are always sent to the hook as an application/x-www-form-urlencoded body.
In addition to the parameters that are always sent, the values provided by the customer for any fields specified in the service definition are sent along as well.
For example, using the Heroku template, the body of a POST might look like the following:
domain_name=example.com&user_id=123&app=myapp
The hook must return 200 to indicate that the operation completed successfully. Any status code other than 200 are considered an error.
The hook may return a JSON object that contains variables that is substitued in records within the service definition.
For example, the Cloudflare hook returns the following JSON:
{
"user_key": "some_user_key",
"target_name": "abef4637291",
"target_type": "CNAME"
}
Any values returned from the hook are merged with the customer-provided values before being rendered into the services records.
All service definitions should include a readme.md file that explains what the service is for and whether there any specific details about the service that are important. The readme.md is a Markdown file.
If a service requires additional set up you should include an instructions.md file. The file is a Markdown file and will be displayed on the service setup screen.