This is an Ansible playbook that from scratch will automatically turn a pristine server into your own Heroku clone. All you need is the server, a domain name, and a DNS service supporting alias records. Everything is powered by Dokku, which itself runs on Docker.
(See bottom section if you are feeling adventurous.)
Just follow these instructions, and you will soon be up and running:
-
Register a domain name where your applications will live, for example
mylittleapp.org
. Each application will run on a subdomain of this host, e.g.helloworld.mylittleapp.org
. -
Set up a new server that you can access by SSH key only. This playbook has been tested on a new Ubuntu 13.04 droplet on DigitalOcean, but a variety of other setups should work as well.
-
Set up two DNS entries for the new domain name, both pointing at the new server's IP address:
-
One
A
record formylittleapp.org
-
One
A
record for*.mylittleapp.org
Your DNS provider must support alias A records of some kind. The above example works on Amazon Route 53, but something like DNSimple should work as well.
-
Make sure your new domain name points at the name servers of your DNS service.
-
Install Ansible and its dependencies on your local machine.
-
Clone this repository to your local machine:
git clone https://github.com/alimony/mylittleapp.git
-
Copy the file
hosts.template
tohosts
and change "mylittleapp.org" to your own domain name. -
Copy your public SSH key to the
authorized_keys
directory (e.g.cp ~/.ssh/id_dsa.pub authorized_keys/mykey.pub
) -
Everything should be ready now! Sit back, relax, and run:
ansible-playbook site.yml -v
To deploy an application to your new server, you just have to add a remote to an existing git repository and push to it. Starting with an empty directory, it can look something like this:
git init
echo '<?php echo "Hello my little app!" ?>' > index.php
git add .
git commit -m 'Initial commit.'
git remote add deploy [email protected]:helloworld
git push deploy master
There will now be application deployment magic happening, much like you're used to from Heroku. The application type is auto-detected and everything needed to run it will be installed (inside a Docker container) and launched. To visit your new application, just go to <appname>.mylittleapp.org
. (In the example above that would be helloworld.mylittleapp.org
.)
All subdomains that are not pointing at an application will redirect to the main hostname. If you want to run an application at the main hostname, create one with just your domain name as its name:
git init
mkdir www
echo 'My little home' > www/index.html
touch .nginx
git add .
git commit -m 'Initial commit.'
git remote add deploy [email protected]:mylittleapp.org
git push deploy master
Touching the .nginx
file is how the nginx buildpack detects it's a static application. All the actual files for the site should live in the www
directory.
You should really set up an application at the main hostname, or it will be in a redirection loop.
- To give more users access to the setup, just add their public SSH to key the
authorized_keys
directory and run the playbook again. - By default, Dokku will be fetched from the
HEAD
of itsmaster
branch. If you want to use another branch, or a specific tag or commit, just change thedokku_version=HEAD
part inhosts
, for exampledokku_version=v0.2.2
. - For maximum encapsulation, you might want to install and run Ansible itself from a virtual environment.
The purpose of this deliberately simple setup is to get you up and running as easy as possible. Only what should be useful to most people is included, which will continue to be the criteria for any changes. With that said, there is of course room for much improvement. If you have ideas, please open an issue about it, or open a pull request directly if you have code to contribute.
This is my first public Ansible playbook ever. Much of it is probably written in a sub-optimal way, since I have yet to learn all the ins and outs of how to organize playbooks, roles, etc. If you have useful input, let me know. I will happily learn and adjust. I can't guarantee that this playbook will not hurt your server, so please only run it on a fresh one, or one that you do not care for :)
If you are feeling adventurous, there is experimental work on creating a server and setting up DNS records as part of the playbook. This means you can go from nothing to a fully working Heroku clone with one single command. Currently, only DigitalOcean and Amazon Route 53 is supported. To try this out, make sure you meet these requirements:
- You have a new domain name with its name servers pointed at a hosted zone in Amazon Route 53.
- You have your API credentials for both DigitalOcean and Amazon Web Services handy.
This is how to proceed:
- Clone this repository to your local machine:
git clone https://github.com/alimony/mylittleapp.git
- Copy
mylittleapp.org.template
tomylittleapp.org
inhost_vars
and edit as needed, uncommenting theserver_provider
anddns_provider
lines. Be sure to fill in alldo_
andaws_
setting values. - Copy
hosts.template
tohosts
and change it to your own domain name. - Copy your public SSH key to the
authorized_keys
directory:cp ~/.ssh/id_dsa.pub authorized_keys/mykey.pub
- Run the playbook and enjoy the ride:
ansible-playbook site.yml -v
Hopefully, the end result will be the same as before, with with far less work. Note that this feature is highly experimental and needs a lot more testing to be considered stable.