Dokku on Azure
This repository contains a Terraform configuration and an Ansible playbook to set up a VM running Dokku on Microsoft Azure.
Installing dependencies
- Install Terraform, a tool for managing infrastructure as code.
On macOS, you can install Terraform with brew:
brew install terraform
. - Install the Azure CLI.
If you use brew, execute
brew install azure-cli
. - Create an Azure account if you don't have one already. Experimenting with the code in this repository will cost you next to nothing.
- Install Ansible.
If you use brew, execute
brew install ansible
.
Creating resources on Azure
- Log in to Azure by executing
az login
and following the instructions. After logging in, you'll see a list of subscriptions associated to your Azure account. If you want to use a different subscription for each of the environments, log in to the Azure Portal and create additional subscriptions. If you do so, you can easily see how much each environment costs. However, using the same subscription for each environment is also fine. - Log in to the Azure Portal and create a resource group for each of the environments.
The name of the resource group used for the development environment should be named
eu-dev
. This name is used in the fileterraform/dev/main.tf
. Similarly, the resource group for staging should be namedeu-staging
, which is used interraform/staging/main.tf
, and the resource group for production should be namedeu-production
, which is used interraform/production/main.tf
. Make sure that the resource group you create for a given environment is part of the subscription for that environment. - In the Azure Portal, create one or more storage accounts. Blobs stored in Azure storage accounts can be used by Terraform to store the state of the infrastructure it manages. By storing this state online, it can be shared by multiple developers. You could use a separate storage account for each environment, but a single one works fine too. Within each of the storage accounts, create a blob container.
- Create the SSH key pairs to access the VMs as administrator.
You can create a single key pair for all environments or a separate pair for each environment.
To generate an RSA key pair with a key size of 4096 bits named
~/.ssh/azure_dokku_admin.pub
and~/.ssh/azure_dokku_admin
withssh-keygen
, executessh-keygen -t rsa -b 4096 -f ~/.ssh/azure_dokku_admin
. - Create a file called
secrets.tfvars
in theterraform
folder. The filesecrets.example.tfvars
indicates for which variables you need to provide values.- Choose usernames that meet Azure's password complexity requirements.
- Refer to the public keys of the SSH key pairs you generated in the previous step.
- Update the subscription identifiers for each of the environments such that they correspond to one of the subscriptions associated to your Azure account.
- Create files called
backend.tfvars
in the foldersterraform/dev
,terraform/staging
, andterraform/production
. The filesbackend.example.tfvars
indicates for which variables you need to provide values. Refer to the name and access keys of the storage account you created for the given environment in one of the previous steps. - Enter the folder
terraform
. - Enter the folder for the environment you'd like to set up, either
dev
,staging
, orproduction
. - Execute
terraform init -backend-config=backend.tfvars
. - Execute
terraform apply -var-file=../secrets.tfvars -var-file=../common.tfvars
.
After completing all the steps above for a given environment, you've set up a virtual machine running Ubuntu on Microsoft Azure that is publicly accessible via HTTP on ports 80 and 8080 and via SSH from a single IP address.
Once you're done with your experiments, you can clean up by running terraform destroy -var-file=../secrets.tfvars -var-file=../common.tfvars
.
Setting up Dokku
- Configure SSH to use the administrator keys you created above to access the VMs.
For example, add the following to the file
~/.ssh/config
for thedev
environment, assuming you've named the SSH key pair for this environmentazure_dokku_dev_admin
.
Host kabisa-dokku-demo-dev.westeurope.cloudapp.azure.com
IdentityFile ~/.ssh/azure_dokku_admin_dev
- After creating the resources on Azure and configuring SSH, verify that you can log in to the created VMs via SSH.
- Create the SSH key pairs to access the Git repositories managed by Dokku. You can create a single key pair for all environments or a separate pair for each environment. If you only want to deploy to each environment from a single machine, such as an instance of Jenkins, a single key is fine.
- Create a file called
dokku.yml
in the foldersinventories/<env>/group_vars
for each environment. The filesdokku.example.yaml
indicate for which variables you need to provide values.- The usernames must match those that you configured for Terraform.
- The SSH keys for administrators must match those that you configured for Terraform.
- The SSH keys for access to the Git repositories managed by Dokku must be those created in the previous step.
- Enter the folder
ansible
. - Execute
ansible-playbook -i inventories/<env> dokku.yml
to set up Dokku, where<env>
should be one ofdev
,staging
, andproduction
.
Deploying apps
After you've completed the steps above, you might want to see whether you can actually deploy apps. To do that, you'll need to configure Dokku.
- Enter the folder
ansible
. - Execute
ansible-playbook -i inventories/<env> dokku_apps.yml
to set up two apps, where<env>
should be one ofdev
,staging
, andproduction
.
To deploy a static front end, execute the following steps.
- Clone the repository for the front end to a temporary folder by executing
git clone dokku@kabisa-dokku-demo-<env>.westeurope.cloudapp.azure.com:front-end /tmp/deploy-front-end
, where<env>
is one ofdev
,staging
, andproduction
. - Enter the folder
tmp/deploy-front-end
. - Create a file called
.static
by executingtouch .static
. - Create a folder called
dist
by executingmkdir dist
. - Create a file called
dist/index.html
by executingecho "<html><body>Hello world</body></html>" >> dist/index.html
. - Deploy this front end by executing
git add . && git commit -m "Deploy" && git push
.
If you visit kabisa-dokku-demo-<env>.westeurope.cloudapp.azure.com
in a browser, you should see the front end you just deployed.
To deploy a back end defined by a Dockerfile, execute the following steps.
- Create a folder
tmp/deploy-back-end/dockerfiles/deploy
. - Enter the folder
tmp/deploy-back-end
. - Initialize a Git repository by executing
git init
. - Create a Dockerfile by executing
echo "FROM google/python-hello" >> dockerfiles/deploy/Dockerfile
. - Deploy the application defined by the Dockerfile by executing
git add . && git commit -m "Deploy" && git push -f dokku@$kabisa-dokku-demo-<env>.westeurope.cloudapp.azure.com:back-end HEAD:refs/heads/master
, where<env>
is one ofdev
,staging
, andproduction
.
If you visit kabisa-dokku-demo-<env>.westeurope.cloudapp.azure.com:8080
in a browser, you should see the back end you just deployed.