diff --git a/Add-on Documentation/Data Storage/MySQLs.md b/Add-on Documentation/Data Storage/MySQLs.md index 3c8b904..c75e281 100644 --- a/Add-on Documentation/Data Storage/MySQLs.md +++ b/Add-on Documentation/Data Storage/MySQLs.md @@ -1,15 +1,14 @@ # MySQLs: Shared MySQL Add-on -Every deployment can access a highly available shared MySQL Add-on based on [Amazon RDS](http://aws.amazon.com/rds/). -The shared MySQL Add-on is recommended for development and low-traffic apps only. For medium to high-traffic apps we -recommend one of the dedicated [MySQLd Add-on](https://www.cloudcontrol.com/add-ons/mysqld) plans. +Every deployment can access a highly available shared MySQL add-on with +databases guaranteed to be located in exoscale datacenters in Switzerland. ## Adding the MySQLs Add-on The database comes in different sizes and prices. It can be added using the addon.add command. ~~~ -$ cctrlapp APP_NAME/DEP_NAME addon.add mysqls.OPTION +$ exoapp APP_NAME/DEP_NAME addon.add mysqls.OPTION ~~~ Replace `mysqls.OPTION` with a valid option, e.g. `mysqls.free`. @@ -18,7 +17,7 @@ Replace `mysqls.OPTION` with a valid option, e.g. `mysqls.free`. To upgrade from one plan to another use the addon.upgrade command. ~~~ -$ cctrlapp APP_NAME/DEP_NAME addon.upgrade mysqls.OPTION_OLD mysqls.OPTION_NEW +$ exoapp APP_NAME/DEP_NAME addon.upgrade mysqls.OPTION_OLD mysqls.OPTION_NEW ~~~ ## Downgrading the MySQLs Add-on @@ -26,103 +25,78 @@ $ cctrlapp APP_NAME/DEP_NAME addon.upgrade mysqls.OPTION_OLD mysqls.OPTION_NEW To downgrade from the current plan to a smaller one use the addon.downgrade command. ~~~ -$ cctrlapp APP_NAME/DEP_NAME addon.downgrade mysqls.OPTION_OLD mysqls.OPTION_NEW +$ exoapp APP_NAME/DEP_NAME addon.downgrade mysqls.OPTION_OLD mysqls.OPTION_NEW ~~~ ## Removing the MySQLs Add-on -Similarily, an Add-on can also be removed from the deployment by using the addon.remove command. +Similarily, an add-on can also be removed from the deployment by using the addon.remove command. -**Attention:** Removing the MySQLs Add-on deletes all data in the database. +**Attention:** Removing the MySQLs add-on deletes all data in the database. ~~~ -$ cctrlapp APP_NAME/DEP_NAME addon.remove mysqls.OPTION +$ exoapp APP_NAME/DEP_NAME addon.remove mysqls.OPTION ~~~ ## Replication and Failover -All instances are master-slave replicated accross two different availability zones. In case of a failure -of the master, an automatic failover to the slave will trigger to restore availability. This failover process -takes usually between 3 and 10 minutes. +All data is synchronously replicated in our robust multi master +[MariaDB](https://mariadb.org/) [Galera](http://galeracluster.com/) cluster. No slave lag or lost transactions. We provide high available access with our smart load balancers. By periodically checks, nodes in maintenance or failure state are automatically excluded from the load balancers database backend pool. That assures that requests are routed to healthy nodes only. -## Encoding - -All databases and tables use `latin1` as the default character set. You can find the character set -and collation of all your tables by running `SHOW TABLE STATUS;` under the `Collation` row. - -You can change the encoding of a table with this query: - -~~~ -ALTER TABLE CHARSET=; -~~~ - -Or create a new table with an explicit encoding adding a `CHARSET` value to the query: - -~~~ -CREATE TABLE ( - `id` int, - ...... - ) CHARSET=; -~~~ - -Or change the default character set for a database, so all tables created would use this enconding: +## Database Credentials -~~~ -ALTER DATABASE CHARSET ; -~~~ +### Internal Access -You can find a list with all character sets supported by MySQL with this query: +It's recommended to the read database credentials from the creds.json file. The +location of the file is available in the `CRED_FILE` environment variable. +Reading the credentials from the creds.json file ensures your app is always +using the correct credentials. For detailed instructions on how to use the +creds.json file please refer to the section about +[Add-on Credentials](https://community.exoscale.ch/apps/documentation/#add-ons) +in the general documentation. +Most database drivers provide a reconnect on connection issues when you add **autoReconnect=true** parameter to your database uri. This should be enabled to have the most stable setup. For example with Java: ~~~ -SHOW CHARSET; +jdbc:mysql://{MYSQLS_HOSTNAME}:{MYSQLS_PORT}/{MYSQLS_DATABASE}?autoReconnect=true ~~~ -## Database Credentials - -### Internal Access - -It's recommended to the read database credentials from the creds.json file. The location of the file is available -in the `CRED_FILE` environment variable. Reading the credentials from the creds.json file ensures your app is always -using the correct credentials. For detailed instructions on how to use the creds.json file please refer to the -section about [Add-on Credentials](https://www.cloudcontrol.com/dev-center/platform-documentation#add-ons) in -the general documentation. ### External Access -External access to the MySQLs Add-on is available through an SSL encrypted connection by following these simple steps. +External access to the MySQLs add-on is available through an SSL encrypted connection by following these simple steps. - 1. Download the [certificate file](https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem) to your local machine. + 1. Download the [certificate file](https://community.exoscale.ch/static/apps/ca-cert.pem) to your local machine. 1. Connect to the database using an SSL encrypted connection. The following example uses the MySQL command line tool. ~~~ -$ mysql -u MYSQLS_USERNAME -p --host=MYSQLS_HOSTNAME --ssl-ca=PATH_TO_CERTIFICATE/mysql-ssl-ca-cert.pem +$ mysql -u MYSQLS_USERNAME -p --host=MYSQLS_HOSTNAME --ssl-ca=PATH_TO_CERTIFICATE/ca-cert.pem ~~~ Replace the uppercase variables with the corresponding values shown by the addon command. ~~~ -$ cctrlapp APP_NAME/DEP_NAME addon mysqls.OPTION +$ exoapp APP_NAME/DEP_NAME addon mysqls.OPTION Addon : mysqls.512mb Settings +MYSQLS_DATABASE : SOME_DATABASE_NAME +MYSQLS_HOSTNAME : mysql.app.exo.io +MYSQLS_PORT : 3306 MYSQLS_PASSWORD : SOME_SECRET_PASSWORD MYSQLS_USERNAME : SOME_SECRET_USERNAME -MYSQLS_HOSTNAME : SOME_HOST.eu-west-1.rds.amazonaws.com:3306 -MYSQLS_DATABASE : SOME_DATABASE_NAME ~~~ Likewise imports and exports are equally simple. To **export** your data use the mysqldump command. ~~~ -$ mysqldump -u MYSQLS_USERNAME -p --host=MYSQLS_HOSTNAME --ssl-ca=PATH_TO_CERTIFICATE/mysql-ssl-ca-cert.pem MYSQLS_DATABASE > MYSQLS_DATABASE.sql +$ mysqldump -u MYSQLS_USERNAME -p --host=MYSQLS_HOSTNAME --ssl-ca=PATH_TO_CERTIFICATE/ca-cert.pem MYSQLS_DATABASE > MYSQLS_DATABASE.sql ~~~ To **import** an sql file into a MySQL database use the following command. ~~~ -$ mysql -u MYSQLS_USERNAME -p --host=MYSQLS_HOSTNAME --ssl-ca=PATH_TO_CERTIFICATE/mysql-ssl-ca-cert.pem MYSQLS_DATABASE < MYSQLS_DATABASE.sql +$ mysql -u MYSQLS_USERNAME -p --host=MYSQLS_HOSTNAME --ssl-ca=PATH_TO_CERTIFICATE/ca-cert.pem MYSQLS_DATABASE < MYSQLS_DATABASE.sql ~~~ - diff --git a/Add-on Documentation/Deployment/SSL.md b/Add-on Documentation/Deployment/SSL.md index 9be5e87..63c75f6 100644 --- a/Add-on Documentation/Deployment/SSL.md +++ b/Add-on Documentation/Deployment/SSL.md @@ -1,22 +1,40 @@ # SSL Add-on -This add-on provides SSL support for custom domains (e.g. "www.example.com") -that you have added to your application using the [alias addon](https://www.cloudcontrol.com/dev-center/add-on-documentation/alias). +Overview: + * This Add-on provides SSL support for custom domains. + * You need to have an RSA Private Key, an SSL Certificate and a Certificate Chain. + * Add the Add-on to your deployment via our CLI with the [addon.add command](#adding-the-ssl-add-on). -## Overview +Secure Socket Layer (SSL) encryption is available for improved security when +transmitting passwords and other sensitive data. + +As part of the provided `.app.exo.io` subdomain, all deployments have +access to piggyback SSL using a `*.app.exo.io` wildcard certificate. +To use this, simply point your browser to: +* `https://APP_NAME.app.exo.io` for the default deployment +* `https://DEP_NAME-APP_NAME.app.exo.io` for non-default deployments + + Please note the **dash** between DEP_NAME and APP_NAME. + +SSL support for custom domains is available through the SSL Add-on. + +## Custom Domain Certificates + +To enable SSL support for custom domains like `www.example.com` or +`secure.example.com`, you need the SSL Add-on. Please go through the following steps, which are described in the upcoming -sections, to add SSL support for custom domains to your deployment: +sections, to add SSL support to your deployment: * Acquire a signed certificate from your certificate authority of trust. - * Add the SSL add-on providing the certificate, the private key and the + * Add the SSL Add-on providing the certificate, the private key and the certificate-chain files. * Set your DNS entry to point to your SSL DNS Domain. -Root or naked domains like `example.com` without a subdomain are not -directly supported. For details, please see the [alias addon](https://www.cloudcontrol.com/dev-center/add-on-documentation/alias) documentation. - +Note: Please allow up to one hour for DNS changes to propagate before they take +effect. Root or naked domains like `example.com` without a subdomain are not +supported. ### Acquiring an SSL Certificate @@ -99,27 +117,20 @@ previous step. Quite often you will also need define the web server you are going to use. In this case you should select the Nginx web server, and if this is not an option then Apache 2.x should also be OK. -In the end, your CA will provide you with one or more files including the -SSL certificate and the certificate chain (the intermediate certificate(s)). - -If you got only one file with both your certificate and all intermediates, -you have to split this file into two, server.crt (topmost certificate) -and chain.crt (rest of original file). - -The SSL certificates have to be in PEM format and should look like this: - -~~~ ------BEGIN CERTIFICATE----- -... ------END CERTIFICATE----- -~~~ - -If your certificates are not in PEM yet, you can transform them with the -following command: +In the end, your CA will provide you with some files including the SSL +certificate and the certificate chain. Your certificate file should have either +a `.crt` or `.pem` extension. Our service requires the certificates to be in +PEM format, so if it isn't, you can transform it with the following command: + ~~~ + $ openssl x509 -inform PEM -in www_example_com.crt -out www_example_com.pem + ~~~ -~~~ -$ openssl x509 -inform PEM -in www_example_com.crt -out www_example_com.pem -~~~ +The content of the SSL certificate file should look like this: + ~~~ + -----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE----- + ~~~ The certificate chain is a chain of trust which proves that your certificate is issued by a trustworthy provider authorized by a Root CA. Root CA certificates @@ -149,7 +160,7 @@ in PEM format. To add the SSL Add-on, simply provide the paths to the files provided by the certificate authority using the respective parameters of the addon.add command. ~~~ - $ cctrlapp APP_NAME/DEP_NAME addon.add ssl.host --cert path/to/CERT_FILE --key path/to/KEY_FILE --chain path/to/CHAIN_FILE + $ cctrlapp APP_NAME/DEP_NAME addon.add ssl.host --cert path/to/CERT_FILE --key path/to/KEY_FILE [--chain path/to/CHAIN_FILE] ~~~ In order to check the status of the Add-on, you can do the following. @@ -158,89 +169,15 @@ In order to check the status of the Add-on, you can do the following. Addon : ssl.host Settings - SSL_CERT_EXPIRES : 2016-01-01 10:00:00 - SSL_DNS_DOMAIN : addonssl-depxxxxxxxx-1234567890.eu-west-1.elb.amazonaws.com - SSL_CERT_INCEPTS : 2013-01-01 10:00:00 - ~~~ - -### Updating your Certificate - -When the SSL certificate is expired, you can update it by removing the Add-on -and re-adding it, providing the updated certificate. The SSL service is provided -for 23 minutes after removing the Add-on so that it can be updated in the -meantime without interrupting the service. To achieve that you have to run the -following commands: - ~~~ - $ cctrlapp APP_NAME/DEP_NAME addon.remove ssl.host - $ cctrlapp APP_NAME/DEP_NAME addon.add ssl.host --cert path/to/NEW_CERT_FILE --key path/to/KEY_FILE --chain path/to/CHAIN_FILE - ~~~ - -Note: You need to provide the original key and chain again when updating the -Add-on even if those are not changed. - - -### Setup your DNS - -As a final step, create a corresponding CNAME entry and point it to the -SSL_DNS_DOMAIN shown in the configuration for your SSL add-on as seen -above. - - -## HTTPS Redirects - -HTTPS termination is done at the routing tier. Requests are then routed via -HTTP to one of your app's clones. To determine if a request was made via HTTPS -originally, the routing tier sets the `X-FORWARDED-PROTO` header to `https`. -The header is only set for requests that arrived via HTTPS at the routing tier. -This allows you to redirect accordingly. - -### PHP Example - -For PHP you can either redirect via Apache's mod_rewrite using a `.htaccess` -file or directly in your PHP code. - -#### .htaccess -~~~ - - RewriteEngine On - RewriteCond %{HTTP:X-FORWARDED-PROTO} !=https [NC] - RewriteRule ^.*$ https://%{HTTP_HOST} - -~~~ - -#### PHP -~~~php - -~~~ - -### Rails Example - -For Rails you can find several ways to force requests to be redirected via HTTPS protocol. -As of version 3.10, [`force_ssl`](http://api.rubyonrails.org/classes/ActionController/ForceSSL/ClassMethods.html) -provides this functionality. This can be added to a particular controller or to the whole application via configuration. - -#### At the Controller Level -~~~ruby -MyController < ApplicationController - force_ssl -end -~~~ - -#### At the Application Level -~~~ruby -# config/application.rb -module MyApp - class Application < Rails::Application - config.force_ssl = true - end -end -~~~ + SSLDEV_CERT_EXPIRES : 2016-01-01 10:00:00 + SSLDEV_DNS_DOMAIN : snip.app.exo.com + SSLDEV_CERT_INCEPTS : 2013-01-01 10:00:00 + ~~~ + +If you want to exchange your certificate (e.g. because it is about to expire), +you can upload the new certificate with the following command: + ~~~ + $ exoapp APP_NAME/DEP_NAME addon.upgrade ssl.host ssl.host --cert path/to/NEW_CERT_FILE --key path/to/KEY_FILE [--chain path/to/CHAIN_FILE] + ~~~ + +Note: If the new certificate has the same chain file, you still need to pass it again.