Merge pull request #36 from caktus/develop

Release 1.3.0

.gitignore

@@ -1,2 +1,3 @@
 *.pyc
 content/
+_build/

CHANGELOG.rst

@@ -1,6 +1,25 @@
 Change Log
 ==========
 
+`1.3.0`_ (2018-09-13)
+---------------------
+
+Features:
+
+* Allow overriding parameter defaults at template creation time without having to change the
+  Python code.  See `the README
+  <https://github.com/caktus/aws-web-stacks/blob/master/README.rst#dokku>`_.
+* Add a parameter to control whether certificates are validated by DNS or email, and default
+  to DNS since GDPR has made email validation less likely to work.
+* The database type of the RDS instance can now be configured (previously, only Postgres could
+  be used). Note that, for backwards-compatibility reasons, the resources in the CloudFormation
+  stack is still named ``PostgreSQL`` (this avoids unnecessarily recreating the RDS instance
+  on pre-existing stacks). See: PR #32
+* The RDS instance now supports all allowable special characters in the password field. See: PR #31
+* The CloudFront distribution linked to the S3 assets bucket can now be disabled / enabled at the
+  time a stack is created or updated; the CloudFront distribution now supports a custom domain name
+  and SSL certificate. See: PR #30
+
 
 `1.2.0`_ (2017-09-27)
 ---------------------
@@ -115,6 +134,7 @@ Backwards-incompatible changes:
 * Initial public release
 
 
+.. _1.3.0: https://aws-web-stacks.s3.amazonaws.com/index.html?prefix=1.3.0/
 .. _1.2.0: https://aws-web-stacks.s3.amazonaws.com/index.html?prefix=1.2.0/
 .. _1.1.2: https://aws-web-stacks.s3.amazonaws.com/index.html?prefix=1.1.2/
 .. _1.1.1: https://aws-web-stacks.s3.amazonaws.com/index.html?prefix=1.1.1/

CONTRIBUTING.rst

@@ -31,6 +31,16 @@ Compile JSON Templates
 
 The templates will be saved to the ``content/`` directory.
 
+Building the documentation
+--------------------------
+
+.. code-block:: bash
+
+    cd docs
+    make html
+
+The docs will be available in the ``docs/_build/html/`` directory.
+
 Submitting Pull Requests
 ------------------------
 

README.rst

@@ -7,10 +7,12 @@ AWS Web Stacks
 AWS Web Stacks is a library of CloudFormation templates that dramatically simplify hosting web applications
 on AWS. The library supports using Elastic Container Service (ECS), Elastic Beanstalk (EB), EC2 instances
 (via an AMI you specify), or `Dokku <http://dokku.viewdocs.io/dokku/>`_ for the application server(s) and
-provides auxilary managed services such as a Postgres RDS instance, Redis instance, Elasticsearch instance
+provides auxilary managed services such as an RDS instance, ElastiCache instance, Elasticsearch instance
 (free) SSL certificate via AWS Certificate Manager, S3 bucket for static assets, ECS repository for hosting
-Docker images, etc. All resources (except Elasticsearch, which does not support VPCs) are created in a
-self-contained VPC, which may use a NAT gateway (if you want to pay for that) or not.
+Docker images, etc. All resources (that support VPCs) are created in a self-contained VPC, which may use a
+NAT gateway (if you want to pay for that) or not, and resources that require API authentication (such as
+S3 or Elasticsearch) are granted permissions via the IAM instance role and profile assigned to the
+application servers created in the stack.
 
 The CloudFormation templates are written in `troposphere <https://github.com/cloudtools/troposphere>`_,
 which allows for some validation at build time and simplifies the management of several related
@@ -67,6 +69,12 @@ wish to use the JSON template directly:
 .. _Dokku-No-NAT: https://console.aws.amazon.com/cloudformation/home?#/stacks/new?stackName=dokku-no-nat&templateURL=https://s3.amazonaws.com/aws-web-stacks/dokku-no-nat.json
 .. _dokku-no-nat.json: https://s3.amazonaws.com/aws-web-stacks/dokku-no-nat.json
 
+Documentation
+-------------
+
+In addition to this README, there is additional documentation at
+http://aws-web-stacks.readthedocs.io/
+
 
 Elastic Beanstalk, Elastic Container Service, EC2, or Dokku?
 ------------------------------------------------------------
@@ -90,8 +98,8 @@ it appear unhealthy, e.g.::
 
 For very simple, Heroku-like deploys, choose the **Dokku** option. This will give you a single EC2 instance
 based on Ubuntu 16.04 LTS with `Dokku <http://dokku.viewdocs.io/dokku/>`_ pre-installed and global environment
-variables configured that will allow your app to find the Postgres, Redis or Memcached, and Elasticsearch nodes
-created with this stack.
+variables configured that will allow your app to find the RDS, ElastiCache, and Elasticsearch nodes created
+with this stack.
 
 NAT Gateways
 ------------
@@ -140,8 +148,10 @@ The following is a partial list of resources created by this stack, when Elastic
   which will be pre-configured with the environment variables specified below.
 * **Elasticsearch** (``AWS::Elasticsearch::Domain``): An Elasticsearch instance, which your
   application may use for full-text search, logging, etc.
-* **PostgreSQL** (``AWS::RDS::DBInstance``): The Postgres RDS instance for your application.
-  Includes a security group to allow access only from your EB or ECS instances in this stack.
+* **PostgreSQL** (``AWS::RDS::DBInstance``): The RDS instance for your application.
+  Includes a security group to allow access only from your EB or ECS instances in this stack. Note:
+  this CloudFormation resource is named "PostgreSQL" for backwards-compatibility reasons, but the
+  RDS instance can be configured with any database engine supported by RDS.
 * **Redis** (``AWS::ElastiCache::CacheCluster``): The Redis ElasticCache instance for your
   application. Includes a cache security group to allow access only from your EB or ECS instances in
   this stack.
@@ -183,8 +193,8 @@ application on the specified port, with all of the necessary secrets and environ
 Note that the Elastic Load Balancer will not direct traffic to your instances until the health
 check you specify during stack creation returns a successful response.
 
-Environment Variables
----------------------
+Environment Variables within your server instances
+--------------------------------------------------
 
 Once your environment is created you'll have an Elastic Beanstalk (EB) or Elastic Compute Service
 (ECS) environment with the environment variables you need to run a containerized web application.
@@ -380,11 +390,57 @@ job to automatically renew the cert as needed::
 
 The Python sample app should now be accessible over HTTPS at https://python-sample.your.domain/
 
+Creating or updating templates
+------------------------------
+
+Templates built from the latest release of aws-web-stacks will be available in
+S3 (see links near the top of this file). They're built with generic defaults.
+
+Templates are built by setting some environment variables with your preferences
+and then running ``python -c 'import stack'`` (see the Makefile).
+The template file is output to standard output. It's easy to do this on one line::
+
+    USE_EC2=on python -c 'import stack' >my_ec2_stack_template.json
+
+Here are the environment variables that control the template creation.
+
+USE_EC2=on
+    Create EC2 instances directly.
+USE_GOVCLOUD=on
+    Create EC2 instances directly, but disables AWS services that aren't available
+    in GovCloud like the AWS Certificate Manager and Elastic Search.
+USE_EB=on
+    Create an Elastic Beanstalk application
+USE_ECS=on
+    Create an Elastic Container Service.
+USE_DOKKU=on
+    Create an EC2 instance containing a Dokku server
+
+I believe those environment variables are mutually exclusive.  The remaining
+ones can be used in combination with each other or one of the above.
+
+USE_NAT_GATEWAY=on
+    Don't put the services inside your VPC onto the public internet, and
+    add a NAT gateway to the stack to the services can make connections out.
+DEFAULTS_FILE=<path to JSON file>
+    Changes the default values for parameters. The JSON file should just be
+    a dictionary mapping parameter names to default values, e.g.::
+
+        {
+            "AMI": "ami-078c57a94e9bdc6e0",
+            "AssetsUseCloudFront": "false"
+        }
+
+One more example, creating EC2 instances without a NAT gateway and overriding
+the parameter defaults::
+
+    USE_EC2=on DEFAULTS_FILE=stack_defaults.json python -c 'import stack' >stack.json
+
 Contributing
 ------------
 
 Please read `contributing guidelines here <https://github.com/caktus/aws-web-stacks/blob/develop/CONTRIBUTING.rst>`_.
 
 Good luck and have fun!
 
-Copyright 2017 Jean-Phillipe Serafin, Tobias McNulty.
+Copyright 2017, 2018 Jean-Phillipe Serafin, Tobias McNulty.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = AWSWebStacks
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# AWS Web Stacks documentation build configuration file, created by
+# sphinx-quickstart on Wed Feb  7 15:37:19 2018.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'AWS Web Stacks'
+copyright = '2018, Caktus Group'
+author = 'Caktus Group'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = ''
+# The full version, including alpha/beta/rc tags.
+release = ''
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'AWSWebStacksdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'AWSWebStacks.tex', 'AWS Web Stacks Documentation',
+     'Caktus Group', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'awswebstacks', 'AWS Web Stacks Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'AWSWebStacks', 'AWS Web Stacks Documentation',
+     author, 'AWSWebStacks', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+