Cookiecutter Static Site Template 1.0 Documentation¶

Section Goals¶

This section prepares you for:

1. Using the cookiecutter-static-site template to generate a project
2. Generating security certificates to secure your website
3. Using the provided scripts in your new project to upload (deploy) your static website to the cloud

This section lists all of the tools required to perform the three steps above. Rather than provide detailed instructions for each installation, this section refers you instead to installation instructions of each utility.

The tools below are listed in the order they will be used.

Python and pip¶

Python version 2.7, 3.3, 3.4, or 3.5 must be installed for both project generation and site deployment. If you’re on a modern Mac, Python 2.7 is already installed for you (but you are encouraged to upgrade Python). If you’re on Windows, you will need to install Python. If you’re on BSD or Linux, you don’t need my help.

Python is installed with pip, a package manager for Python packages/applications.

virtualenvwrapper¶

virtualenvwrapper is an optional tool that allows for the logical separation of installed packages. I highly recommend using it.

If you are on Windows, you may wish to use either virtualenvwrapper-win or virtualenvwrapper-powershell. The installation guide for virtualenvwrapper has more information.

OpenSSL¶

Named after the now-deprecated Secure Sockets Layer security protocol, OpenSSL is an open-source utility that allows for many cryptographic and security applications. In this walkthrough, you will use it to obtain a TLS security certificate for your website.

If you’re on Windows, you will need to google installations instructions (Sorry, I cannot help you here.) If you’re on a Mac, then OpenSSL is already installed. On Linux and BSD, if OpenSSL is not on your system, then your package manager should quickly fix that problem for you.

jq¶

Whereas Python, pip, and virtualenvwrapper are tools for generating the static site deployment project, jq is a tool necessary for the deployment of the site to the cloud. You will not need to use the tool yourself, but the deployment scripts we will use do rely on the tool.

Downloads and installation instructions may be found here.

Section Goals¶

Once you have an account, your goal will be to create a user to allow command-line access to the cloud. However, before we can create the user, we will have to secure the cloud.

Both securing an account and creating a user happen in the Identity and Access Management (IAM) section. You can find it on the AWS console under Security & Identity, or you can click here if you’re currently logged in.

Securing your Account¶

When you are greeted by the IAM Management Console, you will discover a list of actions to take to secure your cloud resources.

Security Task List in the AWS IAM Management Console

By default on new accounts, the first item will have been completed for you (if your account is older, this may not have been done for you).

The second item, Multi-Factor Authentication (MFA), will allow us to setup Two-Factor Authentication using a smartphone. This is certainly not required, but I heartily recommend it. Click on the Activate MFA on your root account item in the list, then on Manage MFA, and then follow the instructions. You will need to install Google Authenticator on your smartphone to properly setup the service.

You may have to hit the Dashboard link towards the top left of your window to get back to the IAM console. You’ll be greeted by a green checkmark in your task list.

Security Task List with MFA Setup Complete

We can then skip to the end of the task list, and setup password restrictions for any future users. Click on Apply an IAM password policy and then on Manage Password Policy. You’ll be greeted with a page with a number of choices. My usual selection consists of the following (but feel free to pick your own):

Andrew’s Password Policy Settings.

Once you successfully apply a password policy, the task list will appear with three checkmarks:

Security Task List with Password Policy Complete

Creating a User and applying permissions with a Group¶

With user management comes the idea of permissions: we want to restrict what a user can do on our system for security purposes. The best way to do this is to create a group, and assign permissions to that group. We then add users to that group, rather than adding permissions directly to the user.

Creating a Group with Permissions¶

Our first task is thus to create a group. In the IAM console, in our security task list, click on Use groups to assign permissions and then on Manage Groups. Alternatively, you can simply click on Groups in the sidebar on the left.

Groups button in the IAM Console Sidebar

On this new page, click on the Create New Group button. This will bring you to the Create New Group Wizard. I will call the new group administrators and then click Next Step at the bottom right of the screen. This brings us to the long list of permissions we can apply to our new group.

Groups button in the IAM Console Sidebar

As we’re creating a user policy for our own command-line access, we want to give ourselves full access to the cloud. We therefore click the checkbox next to AdministratorAccess, and click Next Step.

AdministratorAccess Policy in the AWS IAM Create New Group Wizard

AWS will give us an overview of our new group, allowing us to click Create Group to actually finish the task.

AdministratorAccess Policy Review in the AWS IAM Create New Group Wizard

Creating a User¶

Finally, we can create a user, and then add the user to our administrators group.

Much like with groups, we can either click on Create individual IAM users in the task list and then click on Manage Users, or use the Users link in the sidebar. On the new page, click Create New Users.

We only need a single user, so I will only fill in the top text field. Make sure that Generate an access key for each user checkbox at the bottom of the textfields is checked (the default).

Create User in AWS IAM Console

With this new user created, you will be prompted to download the authentication credentials for the new user (the button at the bottom right of the screen on the new page). You will need this information when generating the static site project with our template. I recommend saving this information in a safe location, such as a password manager, as this information gives full access to your AWS account.

After you’ve downloaded and saved your credentials, your new user will appear in the list of users.

New User in User List of AWS IAM Console

If you click on the new user, the full profile will be displayed.

New User Profile

Warning

The Amazon Resource Numbers (ARNs) associated with various cloud resources are unique, and should be kept semi-secret.

Use the Add User to Group button to add the new user to the administrators group.

Having created a user and assigned it a group with permissions, the task list for securing your account is now complete. Congratulations!

Section Goals¶

In all cases, our goal is to use cookiecutter to download the cookiecutter-static-site project (this project!) to jump start our work by generating a static website project. The project will make deploying the static website to the cloud as easy as possible.

In the first walkthrough below, we will do this without any complications. In the second walkthrough, we will use virtualenvwrapper to separate our project tools from other projects.

virtualenvwrapper : to use, or not to use?¶

If you’re planning to learn Python, or use any other Python projects, I strongly encourage you to use virtualenvwrapper (discussed and installed in the Prerequisites section).

If you have no intention of using multiple Python projects or programming Python, you do not need to use virtualenvwrapper. Even if you plan to generate multiple static websites using this project template, you will not need virtualenvwrapper.

Generating the project without virtualenvwrapper¶

Our first task is to install cookiecutter. In your terminal, write the following code, without the dollar sign (which is shown to designate the fact that this is a terminal).

$ pip install cookiecutter

Now that you have cookiecutter installed, we can use cookiecutter to use the cookiecutter-static-site template to create our new project.

$ cookiecutter gh:jambonsw/cookiecutter-static-site

cookiecutter will prompt you for information to customize your project. Below is an example of the questions asked (but may not reflect the most current questions!).

project_name [My Static Website]: JamBon Software
project_slug [jambon-software]: jambonsw
domain_name [example.com]: jambonsw.com
aws_access_key_id [XXXXXXXXXXXXXXXXXXXX]:
aws_secret_access_key [XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX]:

The project slug will be used to create a new directory (folder) with the project code in it. You can use the code below to navigate into directory using the terminal (you’ll need to replace jambonsw with the slug of your own project).

$ cd jambonsw  # replace with the value you specified when prompted by cookiecutter

$ rm -rf .git  # Warning: deletes with impunity
$ rm -f .gitignore  # Warning: deletes with impunity

We then install all of the smaller Python tools (not listed in the prerequisites section!) necessary for our project.

$ pip install -r requirements.txt

Please note that whenever you work on this project, the scripts provided will need to have specific information available: specifically, the scripts expect to have several environment variables available in the environment. To make your life easier, all of these variables are specified in env.sh. You will need to enter the command below whenever you start working on this project (one of the major advantages of virtualenvwrapper is that we only need to specify the variables once).

$ source env.sh

The unenv.sh script removes these secret variables from your environment. Us the command below when you stop working on your project (or you can simply close your terminal window).

$ source unenv.sh

Your project is ready to go! You can either read below to see how to do the same with virtualenvwrapper, or jump directly to instructions about how to obtain a security certificate.

Generating the project with virtualenvwrapper¶

Much like in the first walkthrough above, the goal is to use cookiecutter to generate a project from the cookiecutter-static-site project. However, this time we will separate the project logically according to terminal environment, making it easy to run other code projects.

Make sure that you have properly installed virtualenvwrapper, and that you’ve created the necessary environment variables, as specified in the installation guide.

To start, we want to create a new virtual environment. In the code below, I name the project jambonsw, in anticipation of the fact that I will name the poject slug the same. The project slug is primarily used to specify the name of the directory that contains the project. You may follow this convention, or name the environment as you please.

$ mkvirtualenv jambonsw

Your terminal will change to show you that you are now working in a virtual environment by printing the name of the environment in parentheses before the dollar sign.

Use the code below if you wish to leave the environment.

(jambonsw) $ deactivate

To enable an existing environment, use the workon command with the name of the environment.

$ workon jambonsw

In this environment, we then install cookiecutter. Note that cookiecutter will only be available if we’re in the environment!

(jambonsw) $ cookiecutter gh:jambonsw/cookiecutter-static-site

As show in the example code in the first walkthrough above, cookiecutter will prompt you with various questions to get you started.

We use the project slug (specified by you when prompted) to enter the project directory (folder). Replace the jambonsw directory name in the code below with the slug of your own project.

(jambonsw) $ cd jambonsw

$ rm -rf .git  # Warning: deletes with impunity
$ rm -f .gitignore  # Warning: deletes with impunity

To make our life easier in the long run, we can now associate this directory with the environment. We do so with the setvirtualenvproject command.

(jambonsw) $ setvirtualenvproject

If you use the workon command while in another directory, the command will automatically bring you to this directory.

We then install all of the smaller Python tools (not listed in the prerequisites section!) necessary for our project.

(jambonsw) $ pip install -r requirements.txt

One of the key advantages of using virtualenvwrapper is that we don’t need to source env.sh whenever we choose to work on the project. Instead, we can get virtualenvwrapper to add the needed environment variables to the environment for us. We simply copy the file to a place where

(jambonsw) $ mv env.sh $WORKON_HOME/$(basename $VIRTUAL_ENV)/bin/postactivate
(jambonsw) $ mv unenv.sh $WORKON_HOME/$(basename $VIRTUAL_ENV)/bin/postdeactivate

Your project is ready to go! Before you can deploy the website, however, you’ll need to obtain a security certificate.

Section Goals¶

The goal of this section is to upload a security certificate for AWS to use to encrypt communication to and from your website.

To obtain a certificate, we must first buy the right to a certificate from a Certificate Authority (CA). We then use OpenSSL to generate cryptographic keys, which in turn allows us to generate a Certificate Signing Request (CSR). We return to the CA with our CSR to obtain (generate and activate) our certificate.

We will then upload three things to AWS:

1. a private key
2. a security certificate
3. a certificate chain proving the validity of our certificate

Using a classical CA will cost you $10-20/year. If you’re feeling daring (and comfortable with the command line) you may be interested in Let’s Encrypt (LE). LE is a free, open-source CA. However, LE is currently in beta, and can be a bit finicky. Once I think LE is ready for you, I will update this section with instructions on how to use it. In the meantime, you’re on your own!

Obtaining a Security Certificate from a Certificate Authority¶

Security certificates rely on Public-Key Cryptography. To obtain a security certificate, we first need to generate a set of keys. We will then create a Certificate Signing Request (CSR) for the keys, which will be the information a Certifcate Authority needs to generate a certificate for us.

Before any of that, however, we need to buy the ability to request a certificate from a Certificate Authority (CA).

$ cd certificates

$ openssl genrsa 2048 > private-key.pem

$ openssl req -new -key private-key.pem -out csr.pem

Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MA
Locality Name (eg, city) []:Boston
Organization Name (eg, company) [Internet Widgits Pty Ltd]:JamBon Software
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:jambonsw.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

$ openssl x509 -in jambonsw_com.crt -outform pem -out jambonsw_com_cert.pem
$ openssl x509 -in jambonsw_com.ca-bundle -outform pem -out jambonsw_com_ca_chain.pem

$ rm jambonsw_com.crt
$ rm jambonsw_com.ca-bundle

$ openssl x509 -in COMODORSADomainValidationSecureServerCA.crt -outform pem -out COMODORSADomainValidationSecureServerCA.pem
$ openssl x509 -in COMODORSAAddTrustCA.crt -outform pem -out COMODORSAAddTrustCA.pem
$ openssl x509 -in AddTrustExternalCARoot.crt -outform pem -out AddTrustExternalCARoot.pem
$ openssl x509 -in jambonsw_com.crt -outform pem -out jambonsw_com_cert.pem

$ cat COMODORSADomainValidationSecureServerCA.pem > jambonsw_com_ca_chain.pem
$ cat COMODORSAAddTrustCA.pem >> jambonsw_com_ca_chain.pem
$ cat AddTrustExternalCARoot.pem >> jambonsw_com_ca_chain.pem

$ rm AddTrustExternalCARoot.crt
$ rm AddTrustExternalCARoot.pem
$ rm COMODORSAAddTrustCA.crt
$ rm COMODORSAAddTrustCA.pem
$ rm COMODORSADomainValidationSecureServerCA.crt
$ rm COMODORSADomainValidationSecureServerCA.pem
$ rm jambonsw_com.crt

$ make upload-cert

Section Goals¶

We will first use the scripts to create a Cloud Formation stack. This will create all of the cloud resources we need to store our website.

We will then upload the website to the cloud.

Preparing for Work¶

If you’re using virtualenvwrapper, simply activate the environment.

$ workon jambonsw  # Replace jambonsw with the name of your own env
$ # if you don't remember the name of your env
$ # type workon, and then tap the tab button on your keyboard twice

If you’re not using virtualenvwrapper, you need to load the appropriate environment variables.

$ cd Path/To/Your/Project
$ source env.sh

Creating a CloudFormation Stack¶

To create a CloudFormation stack, we need a script (currently in your_project_dir/certificates/cloudformation_build.json) and parameters for that script (will be created at your_project_dir/certificates/cloudformation_parameters.json).

To make your life as simple as possible, a script has been supplied to generate the parameters for you (this works as long as you’ve already uploaded a security certificate).

$ ./generate-params.sh

If the script succeeds, it will delete itself after creating your_project_dir/certificates/cloudformation_parameters.json.

$ git add certificates/cloudformation_parameters.json
$ git commit -m "Generated CloudFormation parameters."

With all the right files in place, we can now create the CloudFormation stack with the simple command listed below.

$ make create-stack

This can take up to 20 minutes to complete.

Pointing your Domain to Amazon’s Nameservers¶

Now that you have a set of resources in the cloud, you need to point your domain name at the cloud. You are setting the nameservers of your domain.

To get the Amazon Nameservers for your website, simply use the command below.

$ make dns

You will need to go to you domain’s registrar and specify these nameservers. If you don’t know how to do this, look through the FAQ section of your registrar’s website, or contact support.

Uploading Content to the Cloud¶

We now have the infrastructure for a website, but we’ve not actually put any content in the cloud yet. The command below changes that, by uploading all of the content in the your_project_dir/content/ directory. By default, the template includes and extremely basic webpage.

$ make

And with that last command issued, you have successfully deployed your website to the cloud.

Congratulations!