Ansible Elixir Playbooks

This project has ansible playbooks for:

• Elixr Build Server - it has installed Erlang, Elixir and nodejs. Basically, all what is required to compile the Phoenix Framework application.
• Phoenix Website - it is a playbook to provision server with installed PostgreSQL and configured nginx and Let's Encrypt for SSL. There is no Erlang/Elixir on this server because we will deploy there only compiled Phoenix application.

You can learn more about the project from this blog post https://blog.lunarlogic.io/2017/phoenix-app-deployment-with-ansible-playbooks-for-elixir/

Here you will find an example Phoenix Framework app configured for deployment.

Requirements

Control machine (your computer)

• Install Ansible

• Download roles:

  $ ansible-galaxy install -r requirements.yml
  

• Generate vault_pass.txt file into this repository. You need it to be able to encrypt/decrypt secrets.

  ⚠️ For security reasons, the vault_pass.txt file should not be committed into the repository. It's ignored in .gitignore.

  $ openssl rand -base64 256 > vault_pass.txt
  

• Generate your DB password and put output to apps/phoenix-website/host_vars/phoenix-website.lunarlogic.io

  $ ansible-vault encrypt_string --name db_password "YOUR_DB_PASSWORD"
  

Target machine (server)

• Server with Ubuntu 16.04 LTS.

Public keys

We keep our public keys in public_keys/ directory. This set of keys is uploaded to the server during each provisioning and overwrites the list of authorized keys, so proper people have access to the server. It is important to keep the list of keys up to date.

If you don't know how to generate a key for yourself, read this article.

App deployement

CircleCI deployment

If you want to deploy app from CI to the staging/production host then you must generate RSA keys for CircleCI.

$ ssh-keygen -t rsa -b 4096 -N "" -C "circle_ci" -f ./apps/elixir-build-server/circle_ci
$ ssh-keygen -t rsa -b 4096 -N "" -C "circle_ci" -f ./apps/phoenix-website/circle_ci

Add circle_ci.pub public key to your app playbook for the role user:

- role: user/0.0.1
  username: phoenix
  authorized_key_paths:
    - ../../public_keys/*.pub
    - ./circle_ci.pub # add this line

Go to CircleCI and find your project, open settings and find SSH Permissions. Click Add an SSH key button and paste there private key apps/YOUR_APP_NAME/circle_ci.

Now you can remove private key apps/YOUR_APP_NAME/circle_ci from local machine. It should not be commited into repo!

Commit into repo only public key apps/YOUR_APP_NAME/circle_ci.pub.

You can always generate a new fresh keys if you need it hence no reason to backup private key. You already added it to CircleCI.

Run playbooks

Warning: This command will provision all servers listed in inventory file for particular app apps/app_name.

$ ./play apps/app_name

If you want to provision only specific machine do (it's useful if your app is deployed to multiple servers like staging and production):

# Warning: There must be comma and the end of the hosts list!
$ ansible-playbook -i 'example-staging.lunarlogic.io,' apps/app_name/playbook.yml

Provisioning logs

You can check when and with what git commit the host was provisioned in log file: /var/log/provision.log (stored on the target machine).

System users

There are 3 types of users on the server:

• root - for provisioning
• admin - user has the sudo access
• app_name_user - for instance phoenix user for Phoenix Website application. The user has no sudo access. The application is running under this user.

Add playbook for new app

• create new app directory in the app directory
• in this new directory create playbook.yml and inventory files
• in the inventory file put host names to provision (see Ansible docs)
• implement playbook.yml

Secrets

We store secrets in encrypted version using Vault. If you are adding new secrets, make sure you commit them to the repository in the encrypted form.

• Encrypting single values (that can be placed inside a "clear text" YAML file, using the !vault tag):

  $ ansible-vault encrypt_string --name pass_to_some_service "secret"  # stdout encrypted string
  

• Encrypting whole YAML files:

  $ ansible-vault encrypt secret.yml   # encrypt unencrypted file
  $ ansible-vault edit secret.yml      # edit encrypted file
  $ ansible-vault decrypt secret.yml   # decrypt encrypted file
  

Roles

Role versioning

We use roles versioning the simplest possible way, we just add version subdirectories under every role directory.

roles/role-name/role-version/ # e.g. roles/webserver/0.3.2/

To create a new version just copy an existing one, bump the role version and modify it. Please, respect Semantic Versioning 2.0.0.

Community developed roles

Include the roles in requirements.yml and download them using the following command:

$ ansible-galaxy install -r requirements.yml

SSL with Let's Encrypt

You can use lets_encrypt role to generate free SSL certificate thanks to https://letsencrypt.org

Rate Limits

The main limit is Certificates per Registered Domain (20 per week).

https://letsencrypt.org/docs/rate-limits/

If you are testing Let's Encrypt then use staging environment with higher limits!

- role: lets_encrypt/0.0.1
  app_name: myapp
  lets_encrypt_contact_email: [email protected]
  lets_encrypt_environment: staging # you can change it to production once ready

If you want to change main domain for your certificate

If you want to change main domain for your certificate then you need to generate a new certificate.

Here is example file for Phoenix Website project with multiple domains.

In order to generate a new certificate please remove first the old files generated by lets_encrypt role on the server:

$ rm -rf /etc/letsencrypt/accounts/*
$ rm -rf /etc/letsencrypt/archive/*
$ rm -rf /etc/letsencrypt/csr/*
$ rm -rf /etc/letsencrypt/keys/*
$ rm -rf /etc/letsencrypt/live/*
$ rm -rf /etc/letsencrypt/renewal/*

# remove the snippents that load SSL certificate
$ rm -rf /etc/nginx/snippets/project_name

Ensure the nginx is running. It's required so Let's Encrypt can do request to our domain. Provision server again.

Note: If you would like to add a new subdomain to domain list then you can just provision server and a new subdomain will be added to the certificate. You need to generate certificate from scrach only if you change the main domain (the first domain on the list of domains).