Mirrors/dokku
1
0
Fork 0
mirror of https://github.com/dokku/dokku.git synced 2025-12-29 00:25:08 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #706 from progrium/docs

Browse Source 
Consolidate documentation for viewthedocs
This commit is contained in:
Jose Diaz-Gonzalez
2014-10-04 05:03:59 -04:00
parent fae98dabd4 002269a664
commit b848accd56
13 changed files with 788 additions and 201 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
README.md
View File

@@ -1,182 +1,25 @@
# Dokku
# Dokku [![Build Status](https://travis-ci.org/progrium/dokku.png?branch=master)](https://travis-ci.org/progrium/dokku)
Docker powered mini-Heroku. The smallest PaaS implementation you've ever seen.
[![Build Status](https://travis-ci.org/progrium/dokku.png?branch=master)](https://travis-ci.org/progrium/dokku)
## Requirements
Ubuntu 14.04 x64 or 12.04 x64. Ideally have a domain ready to point to your host. It's designed for and is probably best to use a fresh VM. The bootstrapper will install everything it needs.
**Note: Support for 12.04 will be sunsetting in the near future after dokku & 14.04 have been more thoroughly tested.**
- A fresh VM running either Ubuntu `14.04 x64` or `12.04 x64`
## Installing
### Stable
To install the latest stable version of dokku, you can run the following bootstrapper command:
$ wget -qO- https://raw.github.com/progrium/dokku/v0.2.3/bootstrap.sh | sudo DOKKU_TAG=v0.2.3 bash
**Note**: Users on 12.04 will need to run `apt-get install -y python-software-properties` before bootstrapping stable.
## Documentation
### Development
$ wget -qO- https://raw.github.com/progrium/dokku/master/bootstrap.sh | sudo bash
This may take around 5 minutes. Certainly better than the several hours it takes to bootstrap Cloud Foundry.
You may also wish to take a look at the [advanced installation](http://progrium.viewdocs.io/dokku/advanced-installation) document for additional installation options.
## Configuring
Set up a domain and a wildcard domain pointing to that host. Make sure `/home/dokku/VHOST` is set to this domain. By default it's set to whatever hostname the host has. This file is only created if the hostname can be resolved by dig (`dig +short $(hostname -f)`). Otherwise you have to create the file manually and set it to your preferred domain. If this file still is not present when you push your app, dokku will publish the app with a port number (i.e. `http://example.com:49154` - note the missing subdomain).
You'll have to add a public key associated with a username by doing something like this from your local machine:
$ cat ~/.ssh/id_rsa.pub | ssh progriumapp.com "sudo sshcommand acl-add dokku progrium"
That's it!
## Deploy an App
Now you can deploy apps on your Dokku. Let's deploy the [Heroku Node.js sample app](https://github.com/heroku/node-js-sample). All you have to do is add a remote to name the app. It's created on-the-fly.
$ cd node-js-sample
$ git remote add progrium dokku@progriumapp.com:node-js-app
$ git push progrium master
Counting objects: 296, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (254/254), done.
Writing objects: 100% (296/296), 193.59 KiB, done.
Total 296 (delta 25), reused 276 (delta 13)
-----> Building node-js-app ...
Node.js app detected
-----> Resolving engine versions
... blah blah blah ...
-----> Application deployed:
http://node-js-app.progriumapp.com
You're done!
Dokku only supports deploying from its master branch, so if you'd like to deploy a different local branch use: ```git push progrium <local branch>:master```
Right now Buildstep supports buildpacks for Node.js, Ruby, Python, [and more](https://github.com/progrium/buildstep#supported-buildpacks). It's not hard to add more, [go add more](https://github.com/progrium/buildstep#adding-buildpacks)!
Please check the documentation for your particular build pack as you may need to include configuration files (such as a Procfile) in your project root.
## Remote commands
Dokku commands can be run over ssh. Anywhere you would run `dokku <command>`, just run `ssh -t dokku@progriumapp.com <command>`
The `-t` is used to request a pty. It is highly recommended to do so.
To avoid the need to type the `-t` option each time, simply create/modify a section in the `.ssh/config` on the client side, as follows :
Host progriumapp.com
RequestTTY yes
## Run a command in the app environment
It's possible to run commands in the environment of the deployed application:
$ dokku run node-js-app ls -alh
$ dokku run <app> <cmd>
## Plugins
Dokku itself is built out of plugins. Checkout the wiki for information about
creating your own and a list of existing plugins:
https://github.com/progrium/dokku/wiki/Plugins
## Removing a deployed app
SSH onto the server, then execute:
$ dokku delete myapp
## Environment variable management
Typically an application will require some environment variables to run properly. Environment variables may contain private data, such as passwords or API keys, so it is not recommend to store them in your application's repository.
The `config` plugin provides the following commands to manage your variables:
```
config <app> - display the config vars for an app
config:get <app> KEY - display a config value for an app
config:set <app> KEY1=VALUE1 [KEY2=VALUE2 ...] - set one or more config vars
config:unset <app> KEY1 [KEY2 ...] - unset one or more config vars
```
## TLS/SPDY support
Dokku provides easy TLS/SPDY support out of the box. This can be done app-by-app or for all subdomains at once. Note that whenever TLS support is enabled SPDY is also enabled.
### Per App
To enable TLS connection to to one of your applications, copy or symlink the `.crt`/`.pem` and `.key` files into the application's `/home/dokku/:app/tls` folder (create this folder if it doesn't exist) as `server.crt` and `server.key` respectively.
Redeployment of the application will be needed to apply TLS configuration. Once it is redeployed, the application will be accessible by `https://` (redirection from `http://` is applied as well).
### All Subdomains
To enable TLS connections for all your applications at once you will need a wildcard TLS certificate.
To enable TLS across all apps, copy or symlink the `.crt`/`.pem` and `.key` files into the `/home/dokku/tls` folder (create this folder if it doesn't exist) as `server.crt` and `server.key` respectively. Then, enable the certificates by editing `/etc/nginx/conf.d/dokku.conf` and uncommenting these two lines (remove the #):
ssl_certificate /home/dokku/tls/server.crt;
ssl_certificate_key /home/dokku/tls/server.key;
The nginx configuration will need to be reloaded in order for the updated TLS configuration to be applied. This can be done either via the init system or by re-deploying the application. Once TLS is enabled, the application will be accessible by `https://` (redirection from `http://` is applied as well).
**Note**: TLS will not be enabled unless the application's VHOST matches the certificate's name. (i.e. if you have a cert for *.example.com TLS won't be enabled for something.example.org or example.net)
### HSTS Header
The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. dokku does not, by default, enable this header. It is thus left up to you, the user, to enable it for your site.
Beware that if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails.
## Upgrading
Dokku is in active development. You can update the deployment step and the build step separately.
**Note**: If you are upgrading from a revision prior to [27d4bc8c3c](https://github.com/progrium/dokku/commit/27d4bc8c3c19fe580ef3e65f2f85b85101cd83e4), follow the instructions in [this wiki entry](https://github.com/progrium/dokku/wiki/Migrating-to-Dokku-0.2.0).
To update the deploy step (this is updated less frequently):
$ cd ~/dokku
$ git pull origin master
$ sudo make install
Nothing needs to be restarted. Changes will take effect on the next push / deployment.
To update the build step:
$ git clone https://github.com/progrium/buildstep.git
$ cd buildstep
$ git pull origin master
$ sudo make build
This will build a fresh Ubuntu Quantal image, install a number of packages, and
eventually replace the Docker image for buildstep.
Full documentation - including advanced installation docs - are available online at [docs](http://progrium.viewdocs.io/dokku/index)
## Support
You can use [Github Issues](https://github.com/progrium/dokku/issues), check [Troubleshooting](https://github.com/progrium/dokku/wiki/Troubleshooting) on the wiki, or join us on [freenode in #dokku](https://webchat.freenode.net/?channels=%23dokku)
## Components
* [Docker](https://github.com/dotcloud/docker) - Container runtime and manager
* [Buildstep](https://github.com/progrium/buildstep) - Buildpack builder
* [pluginhook](https://github.com/progrium/pluginhook) - Shell based plugins and hooks
* [sshcommand](https://github.com/progrium/sshcommand) - Fixed commands over SSH
Looking to keep codebase as simple and hackable as possible, so try to keep your line count down.
## Things this project won't do
* **Multi-host.** Not a huge leap, but this isn't the project for it. Have a look at [Flynn](https://flynn.io/).
* **Multitenancy.** It's ready for it, but again, have a look at [Flynn](https://flynn.io/).
* **Client app.** Given the constraints, running commands remotely via SSH is fine.
## License
MIT

38
docs/advanced-installation.md
View File

@@ -1,38 +0,0 @@
#Advanced installation
## Development
If you plan on developing dokku, the easiest way to install from your own repository is cloning
the repository and calling the install script. Example:
$ git clone https://github.com/yourusername/dokku.git
$ cd dokku
$ sudo make install
The `Makefile` allows source URLs to be overridden to include customizations from your own
repositories. The `DOCKER_URL`, `PLUGINHOOK_URL`, `SSHCOMMAND_URL` and `STACK_URL`
environment variables may be set to override the defaults (see the `Makefile` for how these
apply). Example:
$ sudo SSHCOMMAND_URL=https://raw.github.com/yourusername/sshcommand/master/gitreceive make install
## Bootstrap a server from your own repository
The bootstrap script allows the dokku repository URL to be overridden to bootstrap a host from
your own clone of dokku using the `DOKKU_REPO` environment variable. Example:
$ wget https://raw.github.com/progrium/dokku/master/bootstrap.sh
$ chmod +x bootstrap.sh
$ sudo DOKKU_REPO=https://github.com/yourusername/dokku.git ./bootstrap.sh
## Custom buildstep build
Dokku ships with a pre-built version of version of the [buildstep] component by
default. If you want to build your own version you can specify that with an env
variable.
$ git clone https://github.com/progrium/dokku.git
$ cd dokku
$ sudo BUILD_STACK=true make install
[buildstep]: https://github.com/progrium/buildstep

90
docs/application-deployment.md Normal file
View File

@@ -0,0 +1,90 @@
# Deploy an App
Now you can deploy apps on your Dokku. Let's deploy the [Heroku Node.js sample app](https://github.com/heroku/node-js-sample). All you have to do is add a remote to name the app. It's created on-the-fly.
```
$ cd node-js-sample
$ git remote add progrium dokku@progriumapp.com:node-js-app
$ git push progrium master
Counting objects: 296, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (254/254), done.
Writing objects: 100% (296/296), 193.59 KiB, done.
Total 296 (delta 25), reused 276 (delta 13)
-----> Building node-js-app ...
Node.js app detected
-----> Resolving engine versions
... blah blah blah ...
-----> Application deployed:
http://node-js-app.progriumapp.com
```
You're done!
Dokku only supports deploying from its master branch, so if you'd like to deploy a different local branch use: ```git push progrium <local branch>:master```
Right now Buildstep supports buildpacks for Node.js, Ruby, Python, [and more](https://github.com/progrium/buildstep#supported-buildpacks). It's not hard to add more, [go add more](https://github.com/progrium/buildstep#adding-buildpacks)!
Please check the documentation for your particular build pack as you may need to include configuration files (such as a Procfile) in your project root.
## Specifying a custom buildpack
If buildpack detection isn't working well for you or you want to specify a custom buildpack for one repository you can create & commit a file in the root of your git repository named `.env` containing `export BUILDPACK_URL=<repository>` before pushing. This will tell buildstep to fetch the specified buildpack and use it instead of relying on the built-in buildpacks & their detection methods.
## Default vhost
You might notice the default vhost for Nginx will be one of the apps. If an app doesn't exist, it will use this vhost and it may be confusing for it to go to another app. You can create a default vhost using a configuration under `sites-enabled`. You just have to change one thing in the main nginx.conf:
Swap both conf.d include line and the sites-enabled include line. From:
```
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
```
to
```
include /etc/nginx/sites-enabled/*;
include /etc/nginx/conf.d/*.conf;
```
Alternatively, you may push an app to your dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
## Deploying to subdomains
The name of remote repository is used as the name of application to be deployed, as for example above:
$ git remote add progrium git@progriumapp.com:node-js-app
$ git push progrium master
Is deployed to,
remote: -----> Application deployed:
remote: http://node-js-app.progriumapp.com
You can also specify fully qualified names, say `app.progrium.com`, as
$ git remote add progrium git@progriumapp.com:app.progrium.com
$ git push progrium master
So, after deployment the application is be available at,
remote: -----> Application deployed:
remote: http://app.progrium.com
This is in particular useful, then you want to deploy to root domain, as
$ git remote add progrium git@progriumapp.com:progrium.com
$ git push progrium master
... deployment ...
remote: -----> Application deployed:
remote: http://progrium.com
# Removing a deployed app
SSH onto the server, then execute:
```bash
dokku delete myapp
```

8
docs/components.md Normal file
View File

@@ -0,0 +1,8 @@
# Components
* [Docker](https://github.com/dotcloud/docker) - Container runtime and manager
* [Buildstep](https://github.com/progrium/buildstep) - Buildpack builder
* [pluginhook](https://github.com/progrium/pluginhook) - Shell based plugins and hooks
* [sshcommand](https://github.com/progrium/sshcommand) - Fixed commands over SSH
Looking to keep codebase as simple and hackable as possible, so try to keep your line count down.

13
docs/configuration-management.md Normal file
View File

@@ -0,0 +1,13 @@
# Configuration management
Typically an application will require some configuration to run properly. Dokku supports application configuration via environment variables. Environment variables may contain private data, such as passwords or API keys, so it is not recommend to store them in your application's repository.
The `config` plugin provides the following commands to manage your variables:
```
config <app> - display the config vars for an app
config:get <app> KEY - display a config value for an app
config:set <app> KEY1=VALUE1 [KEY2=VALUE2 ...] - set one or more config vars
config:unset <app> KEY1 [KEY2 ...] - unset one or more config vars
```

88
docs/dns.md Normal file
View File

@@ -0,0 +1,88 @@
# Overview
This is a work in progress.
## DNS Versions
There are many different DNS servers 'in the wild'. Some of the popular ones on Linux are BIND, dnsmasq, and pdns. Windows has its own built-in DNS server as well as Unbound, Posadis, and more. A full list of DNS packages can be found on Wikipedia under [Comparison of DNS Server Software](http://en.wikipedia.org/wiki/Comparison_of_DNS_server_software). In addition to the various DNS packages, there are tens of thousands of [Managed DNS Providers](http://en.wikipedia.org/wiki/List_of_managed_DNS_providers) out that all have different DNS interfaces.
## Focus
Because there are so many different DNS server packages out there as well as a tremendous number of Managed DNS Providers, we will focus on the concepts of DNS as well as providing examples in the 'BIND' format so you can adapt the information to your own server package or managed DNS provider.
## Assumptions
* We assume you have a passing familiarity with DNS. If not, you can read an [in-depth article](http://www.diaryofaninja.com/blog/2012/03/03/devops-dns-for-developers-ndash-now-therersquos-no-excuse-not-to-know) on DNS. But basically you need to know that DNS changes names (like example.tld) into addresses (like 127.0.0.1)
* We assume you already have a domain name registered and pointed to your favorite Managed DNS Provider or have your own BIND DNS server running.
* You have a server on the internet and are about to follow the instructions in the [README](https://github.com/progrium/dokku/blob/master/README.md) to get dokku installed. Don't do the install just yet though.
## HELP!
Don't be afraid to ask if you need help. Create a [new issue](https://github.com/progrium/dokku/issues) and someone will be glad to assist you.
# Getting started
For the examples, we will use the domain name 'example.tld' and the IP address '127.0.0.1'.
Dokku uses a DNS to differentiate between apps on your dokku-powered server. If you are using the domain 'example.tld', and you have two apps 'myapp1' and 'myapp2', dokku will make them available at 'myapp1.example.tld' and 'myapp2.example.tld'.
To get started, you need to know the IP address of your dokku server. Connect in to it and run 'ifconfig' or 'ip addr' to see the IP address.
# Caching
Please remember that DNS relies heavily on _caching_. Changes you make to DNS could take anywhere from a few seconds to a few *days* to 'propagate'. If you tried surfing to example.tld, then changed the IP address in DNS, it could be a while before your computer picks up on the changes.
## The two methods
Now you have to make a decision about your domain. Do you want everything and anything at example.tld to go to your dokku server, or would you rather use a 'sub domain' for your dokku server?
In other words, do you want your applications on your dokku server accessible via myapp.example.tld or via myapp.myserver.example.tld?
### Using a sub-domain (myapp.myserver.example.tld)
Using a sub-domain is easy. When you set up your server, you probably gave it a name like myserver.example.tld.
Go in to your Managed DNS provider and create an 'A' record named 'myserver' and put in the IP address you got from your server a few moments ago.
Hopefully your managed DNS provider also supports wildcards. Create a second 'A' record named '*.myserver' along with the IP address you got from your server a few moments ago.
If you are using BIND, your zone file will look similar to this:
```
$ORIGIN example.tld
$TTL 5m
myserver IN A 127.0.0.1
*.myserver IN A 127.0.0.1
```
You can verify your changes in Linux by trying one or more of the following commands:
* host myserver.example.tld
* dig -t A myserver.example.tld
* nslookup myserver.example.tld
Now is a good time to remind you that the answers you get MAY BE CACHED.
If everything is working correctly, you should also be able to query for any other name 'under' myserver.example.tld and get back the IP address of your server. Try:
* host test.myserver.example.tld
* host xyzzy.myserver.example.tld
If they all return your IP address, you have set DNS up properly for dokku. You should also be able to 'ssh root@myserver.example.tld' and access your server.
Proceed with the setup instructions in the [README](https://github.com/progrium/dokku/blob/master/README.md)
### Using the root of your domain (myapp.example.tld)
This section is a work in progress. It is incomplete.
Using the 'root' of your domain is nearly identical to the previous example.
* hostname is under example.tld, still needs A record
* Need to modify /home/dokku/HOSTNAME and /home/dokku/VHOST

21
docs/index.md
View File

@@ -1,3 +1,22 @@
# Dokku Documentation
Docs go here.
Docker powered mini-Heroku. The smallest PaaS implementation you've ever seen.
## Table Of Contents
- [Installation](http://progrium.viewdocs.io/dokku/installation)
- [Upgrading](http://progrium.viewdocs.io/dokku/upgrading)
- [Troubleshooting](http://progrium.viewdocs.io/dokku/troubleshooting)
- [Components](http://progrium.viewdocs.io/dokku/components)
- [Application Deployment](http://progrium.viewdocs.io/dokku/application-deployment)
- [Remote commands](http://progrium.viewdocs.io/dokku/remote-commands)
- [Plugins](http://progrium.viewdocs.io/dokku/plugins)
- [Configuration management](http://progrium.viewdocs.io/dokku/configuration-management)
- [TLS/SPDY support](http://progrium.viewdocs.io/dokku/tls-spdy-support)
- [DNS](http://progrium.viewdocs.io/dokku/dns)
## Things this project won't do
* **Multi-host.** Not a huge leap, but this isn't the project for it. Have a look at [Flynn](https://flynn.io/).
* **Multitenancy.** It's ready for it, but again, have a look at [Flynn](https://flynn.io/).
* **Client app.** Given the constraints, running commands remotely via SSH is fine.

160
docs/installation.md Normal file
View File

@@ -0,0 +1,160 @@
# Installation
## Requirements
- A fresh VM running either Ubuntu `14.04 x64` or `12.04 x64`
Ubuntu 14.04 x64 or 12.04 x64. Ideally have a domain ready to point to your host. It's designed for and is probably best to use a fresh VM. The bootstrapper will install everything it needs.
**Note: Support for 12.04 will be sunsetting in the near future after dokku & 14.04 have been more thoroughly tested.**
## Installing the latest Stable version
To install the latest stable version of dokku, you can run the following bootstrapper command:
```bash
wget -qO- https://raw.github.com/progrium/dokku/v0.2.3/bootstrap.sh | sudo DOKKU_TAG=v0.2.3 bash
```
## Configuring
Set up a domain and a wildcard domain pointing to that host. Make sure `/home/dokku/VHOST` is set to this domain. By default it's set to whatever hostname the host has. This file is only created if the hostname can be resolved by dig (`dig +short $(hostname -f)`). Otherwise you have to create the file manually and set it to your preferred domain. If this file still is not present when you push your app, dokku will publish the app with a port number (i.e. `http://example.com:49154` - note the missing subdomain).
You'll have to add a public key associated with a username by doing something like this from your local machine:
$ cat ~/.ssh/id_rsa.pub | ssh progriumapp.com "sudo sshcommand acl-add dokku progrium"
That's it!
## Advanced installation
### Development via bash script
```bash
wget -qO- https://raw.github.com/progrium/dokku/master/bootstrap.sh | sudo bash
```
This may take around 5 minutes. Certainly better than the several hours it takes to bootstrap Cloud Foundry.
You may also wish to take a look at the [advanced installation](http://progrium.viewdocs.io/dokku/advanced-installation) document for additional installation options.
### Development From Source
If you plan on developing dokku, the easiest way to install from your own repository is cloning
the repository and calling the install script. Example:
```bash
git clone https://github.com/yourusername/dokku.git
cd dokku
sudo make install
```
The `Makefile` allows source URLs to be overridden to include customizations from your own
repositories. The `DOCKER_URL`, `PLUGINHOOK_URL`, `SSHCOMMAND_URL` and `STACK_URL`
environment variables may be set to override the defaults (see the `Makefile` for how these
apply). Example:
```bash
sudo SSHCOMMAND_URL=https://raw.github.com/yourusername/sshcommand/master/gitreceive make install
```
### Bootstrap a server from your own repository
The bootstrap script allows the dokku repository URL to be overridden to bootstrap a host from
your own clone of dokku using the `DOKKU_REPO` environment variable. Example:
```bash
wget https://raw.github.com/progrium/dokku/master/bootstrap.sh
chmod +x bootstrap.sh
sudo DOKKU_REPO=https://github.com/yourusername/dokku.git ./bootstrap.sh
```
### Custom buildstep build
Dokku ships with a pre-built version of version of the [buildstep](https://github.com/progrium/buildstep) component by
default. If you want to build your own version you can specify that with an env
variable.
```bash
git clone https://github.com/progrium/dokku.git
cd dokku
sudo BUILD_STACK=true make install
```
### Install Dokku using Vagrant
- Download and install [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
- Download and install [Vagrant](http://www.vagrantup.com/downloads.html)
- Download Dokku (latest stable)
```
wget https://github.com/progrium/dokku/archive/master.zip
```
- Setup SSH hosts in your `/etc/hosts`
```
10.0.0.2 dokku.me
```
- Setup SSH Config in `~/.ssh/config`
```
Host dokku.me
Port 2222
```
- Create VM
```
# Optional ENV arguments:
# - `BOX_NAME`
# - `BOX_URI`
# - `BOX_MEMORY`
# - `DOKKU_DOMAIN`
# - `DOKKU_IP`.
vagrant up
```
- Add SSH key to Dokku using `sshcommand acl-add <user> <ssh-key-name>`, e.g.:
```
cat ~/.ssh/id_rsa.pub | ssh -i ~/.vagrant.d/insecure_private_key vagrant@dokku.me "sudo sshcommand acl-add dokku progrium"
```
You are now ready to deploy an app or install plugins.
For a different, complete, example see https://github.com/RyanBalfanz/dokku-vagrant-example.
### Installing on Linode
#### Using StackScript
Deploy using the following StackScript:
* https://www.linode.com/stackscripts/view/8552
#### Without StackScript
* Build a Ubuntu 13.04 instance
* Follow these instructions: https://www.linode.com/wiki/index.php/PV-GRUB#Ubuntu_12.04_Precise
* If `apt-get update` no longer works:
* Verify if apt-get is trying to use ipv6 instead of ipv4 (e.g. you read something like "[Connecting to us.archive.ubuntu.com (2001:67c:1562::14)]" and apt-get would not proceed). In that case, follow these instructions: http://unix.stackexchange.com/questions/9940/convince-apt-get-not-to-use-ipv6-method (append "precedence ::ffff:0:0/96 100" to /etc/gai.conf)
* OR: change `/etc/apt/sources.list` to one mentioned in http://mirrors.ubuntu.com/mirrors.txt
* Run the following commands:
```bash
apt-get update
apt-get install lxc wget bsdtar linux-image-extra-$(uname -r)
modprobe aufs
```
* After this, you can install dokku the default way:
```bash
wget -qO- https://raw.github.com/progrium/dokku/master/bootstrap.sh | sudo bash
```

180
docs/plugins.md Normal file
View File

@@ -0,0 +1,180 @@
# Plugins
Dokku itself is built out of plugins and uses [pluginhook](https://github.com/progrium/pluginhook) for its plugin system. In essence a plugin is a collection of scripts that will be run based on naming convention.
Let's take a quick look at the current dokku nginx plugin that's shipped with dokku by default.
nginx-vhosts/
├── commands # contains additional commands
├── install # runs on dokku installation
└── post-deploy # runs after an app is deployed
## Installing a plugin
```bash
cd /var/lib/dokku/plugins
git clone <git url>
dokku plugins-install
```
> todo: add a command to dokku to install a plugin, given a git repository `dokku plugin:install <git url>`?
## Creating your own plugin
If you create your own plugin:
1. take a look at the plugins shipped with dokku and hack away!
2. upload your plugin to github with a repository name in form of `dokku-<name>` (e.g. `dokku-mariadb`)
3. edit this page and add a link to it below!
4. subscribe to the [dokku development blog](http://progrium.com/dokku/) to be notified about API changes and releases
## Community plugins
Note: The following plugins have been supplied by our community and may not have been tested by dokku maintainers.
[Kloadut]: https://github.com/Kloadut
[jeffutter]: https://github.com/jeffutter
[jezdez]: https://github.com/jezdez
[blag]: https://github.com/blag
[luxifer]: https://github.com/luxifer
[stuartpb]: https://github.com/stuartpb
[hughfletcher]: https://github.com/hughfletcher
[Aomitayo]: https://github.com/Aomitayo
[jlachowski]: https://github.com/jlachowski
[apmorton]: https://github.com/apmorton
[statianzo]: https://github.com/statianzo
[sehrope]: https://github.com/sehrope
[wmluke]: https://github.com/wmluke
[krisrang]: https://github.com/krisrang
[scottatron]: https://github.com/scottatron
[pauldub]: https://github.com/pauldub
[dyson]: https://github.com/dyson
[musicglue]: https://github.com/musicglue
[motin]: https://github.com/motin
[neam]: https://github.com/neam
[cedricziel]: https://github.com/cedricziel
[pnegahdar]: https://github.com/pnegahdar
[fgrehm]: https://github.com/fgrehm
[alexanderbeletsky]: https://github.com/alexanderbeletsky
[thrashr888]: https://github.com/thrashr888
[robv]: https://github.com/robv
[rlaneve]: https://github.com/rlaneve
[cef]: https://github.com/cef
[alex-sherwin]: https://github.com/alex-sherwin
[F4-Group]: https://github.com/F4-Group
[fermuch]: https://github.com/fermuch
[Zenedith]: https://github.com/Zenedith
[heichblatt]: https://github.com/heichblatt
[michaelshobbs]: https://github.com/michaelshobbs
[iskandar]: https://github.com/iskandar
[mikexstudios]: https://github.com/mikexstudios
[cameron-martin]: https://github.com/cameron-martin
[matto1990]: https://github.com/matto1990
[ohardy]: https://github.com/ohardy
### Datastores
| Plugin | Author | Compatibility |
| --- | --- | --- |
| [CouchDB](https://github.com/racehub/dokku-couchdb-plugin) | [RaceHub](https://github.com/racehub) | Compatible with 0.2.0 |
| [MariaDB](https://github.com/Kloadut/dokku-md-plugin) | [Kloadut][] | Compatible with 0.2.0 |
| [MariaDB (single container)](https://github.com/ohardy/dokku-mariadb) | [ohardy][] | Compatible with 0.2.0 |
| [MongoDB (single container)](https://github.com/jeffutter/dokku-mongodb-plugin) | [jeffutter][] | |
| [PostgreSQL](https://github.com/Kloadut/dokku-pg-plugin) | [Kloadut][] | Compatible with 0.2.0 |
| [PostgreSQL (single container)](https://github.com/jeffutter/dokku-postgresql-plugin) | [jeffutter][] | This plugin creates a single postgresql container that all your apps can use. Thus only one instance of postgresql running (good for servers without a ton of memory). |
| [PostgreSQL](https://github.com/jezdez/dokku-postgres-plugin) | [jezdez][] | Compatible with 0.2.0 |
| [PostgreSQL (single container)](https://github.com/ohardy/dokku-psql) | [ohardy][] | Compatible with 0.2.0 |
| [PostGIS](https://github.com/fermuch/dokku-pg-plugin) | [fermuch][] | |
| [Redis](https://github.com/jezdez/dokku-redis-plugin) | [jezdez][] | Requires https://github.com/rlaneve/dokku-link; compatible with 0.2.0 |
| [Redis](https://github.com/luxifer/dokku-redis-plugin) | [luxifer][] | |
| [Redis (single container)](https://github.com/ohardy/dokku-redis) | [ohardy][] | Compatible with 0.2.0 |
| [RethinkDB](https://github.com/stuartpb/dokku-rethinkdb-plugin) | [stuartpb][] | 2014-02-22: targeting dokku @ [latest][217d00a]; will fail with Dokku earlier than [28de3ec][]. |
| [RiakCS (single container)](https://github.com/jeffutter/dokku-riakcs-plugin) | [jeffutter][] | Incompatible with 0.2.0 (checked at [dccee02][]) |
| [MySQL](https://github.com/hughfletcher/dokku-mysql-plugin) | [hughfletcher][] | |
| [Memcached](https://github.com/jezdez/dokku-memcached-plugin) | [jezdez][] | Compatible with 0.2.0 |
| [Neo4j](https://github.com/Aomitayo/dokku-neo4j-plugin) | [Aomitayo][] | |
| [RabbitMQ](https://github.com/jlachowski/dokku-rabbitmq-plugin) | [jlachowski][] | IP & PORT available directly in linked app container env variables (requires link plugin)|
| [RabbitMQ (single container)](https://github.com/jlachowski/dokku-rabbitmq-single-plugin) | [jlachowski][] | IP & PORT available directly in linked app container env variables (requires link plugin)|
| [Postgresql](https://github.com/jlachowski/dokku-pg-plugin) | [jlachowski][] | IP & PORT available directly in linked app container env variables (requires link plugin)|
| [Memcached](https://github.com/jlachowski/dokku-memcached-plugin) | [jlachowski][] | IP & PORT available directly in linked app container env variables (requires link plugin)|
| [Varnish](https://github.com/Zenedith/dokku-varnish-plugin) | [Zenedith][] | Varnish cache between nginx and application with base configuration|
[dccee02]: https://github.com/jeffutter/dokku-riakcs-plugin/commit/dccee02702e7001851917b7814e78a99148fb709
### Process Managers
| Plugin | Author | Compatibility |
| --- | --- | --- |
| [Circus](https://github.com/apmorton/dokku-circus) | [apmorton][] | |
| [Shoreman ](https://github.com/statianzo/dokku-shoreman) | [statianzo][] | Compatible with 0.2.0 |
| [Supervisord](https://github.com/statianzo/dokku-supervisord) | [statianzo][] | Compatible with 0.2.0 |
| [Logging Supervisord](https://github.com/sehrope/dokku-logging-supervisord) | [sehrope][] | Works with dokku @ [c77cbf1][] - no 0.2.0 compatibility |
| [Forego](https://github.com/iskandar/dokku-forego) | [iskandar][] | Compatible with 0.2.x |
[c77cbf1]: https://github.com/progrium/dokku/commit/c77cbf1d3ae07f0eafb85082ed7edcae9e836147
[28de3ec]: https://github.com/progrium/dokku/commit/28de3ecaa3231a223f83fd8d03f373308673bc40
### Dokku Features
| Plugin | Author | Compatibility |
| --- | --- | --- |
| [Custom Domains](https://github.com/neam/dokku-custom-domains) | [motin][] | Compatible with 0.2.* and master |
| [Multiple Domains](https://github.com/wmluke/dokku-domains-plugin)<sup>4</sup> | [wmluke][] | Compatible with 0.2.0 . |
| [git rev-parse HEAD in env](https://github.com/nornagon/dokku-git-rev) | [nornagon](https://github.com/nornagon) | Compatible with 0.2.0 |
| [Rebuild application](https://github.com/scottatron/dokku-rebuild) | [scottatron][] | Compatible with 0.2.x |
| [Multi-Buildpack](https://github.com/pauldub/dokku-multi-buildpack) | [pauldub][] | |
| [Docker Options](https://github.com/dyson/dokku-docker-options) | [dyson][] | Requires dokku >= [c77cbf1][] |
| [Persistent Storage](https://github.com/dyson/dokku-persistent-storage) | [dyson][] | Requires dokku >= [c77cbf1][] |
| [Volume (persistent storage)](https://github.com/ohardy/dokku-volume) | [ohardy][] | Compatible with 0.2.0 |
| [user-env-compile](https://github.com/musicglue/dokku-user-env-compile)<sup>1</sup> | [musicglue][] | Compatible with dokku master branch |
| [user-env-compile](https://github.com/motin/dokku-user-env-compile)<sup>1</sup> | [motin][] | Compatible with 0.2.1 |
| [SSH Deployment Keys](https://github.com/cedricziel/dokku-deployment-keys)<sup>2</sup> | [cedricziel][] | 2014-01-17: compatible with upstream/master |
| [SSH Hostkeys](https://github.com/cedricziel/dokku-hostkeys-plugin)<sup>3</sup> | [cedricziel][] | 2014-01-17: compatible with upstream/master |
| [Link Containers](https://github.com/rlaneve/dokku-link) | [rlaneve][] | Requires dokku >= [c77cbf1][] |
| [Host Port binding](https://github.com/stuartpb/dokku-bind-port) | [stuartpb][] | Requires dokku >= [c77cbf1][]. 2014-02-17: [a043e98][] targeting dokku @ [latest][217d00a] |
| [Docker name](https://github.com/alex-sherwin/dokku-name) | [alex-sherwin][] | Requires dokku >= [c77cbf1][] |
| [No VHOST](https://github.com/alex-sherwin/dokku-novhost) | [alex-sherwin][] | Requires dokku >= [c77cbf1][] |
| [Docker Direct](https://github.com/heichblatt/dokku-docker-direct) | [heichblatt][] | |
| [Ports](https://github.com/heichblatt/dokku-ports) | [heichblatt][] | |
| [Debug](https://github.com/heichblatt/dokku-debug) | [heichblatt][] | |
| [Pre-Deploy Tasks](https://github.com/michaelshobbs/dokku-app-predeploy-tasks) | [michaelshobbs][] | |
| [Hostname](https://github.com/michaelshobbs/dokku-hostname) | [michaelshobbs][] | |
| [VHOSTS Custom Configuration](https://github.com/neam/dokku-nginx-vhosts-custom-configuration) | [motin][] | Requires https://github.com/progrium/dokku/pull/579 |
| [Multiple domains and per-app custom nginx.conf](https://github.com/mikexstudios/dokku-nginx-alt) | [mikexstudios][] | Works with v0.2.3 |
| [Supply env vars to buildpacks](https://github.com/cameron-martin/dokku-build-env)| [cameron-martin][] | Works with v0.2.3 |
| [HTTP Auth Secure Apps](https://github.com/matto1990/dokku-secure-apps) | [matto1990][] | Works with v0.2.3 |
| [app-url](https://github.com/mikecsh/dokku-app-url) | [mikecsh](https://github.com/mikecsh) | Works with 0.2.0 |
[8fca220]: https://github.com/progrium/dokku/commit/8fca2204edb0017796d6915ca9157c05b1238e28
[217d00a]: https://github.com/progrium/dokku/commit/217d00a1bc47a7e24d8847617bb08a1633025fc7
[98332de]: https://github.com/dyson/dokku-persistent-storage/commit/98332de4b5b640610bee535f4d5260263074e18b
[a043e98]: https://github.com/stuartpb/dokku-bind-port/commit/a043e9892f4815b6525c850131e09fd64db5c1fa
<sup>1</sup> Similar to the heroku-labs feature (see https://devcenter.heroku.com/articles/labs-user-env-compile)
<sup>2</sup> Adds the possibility to add SSH deployment keys to receive private hosted packages
<sup>3</sup> Adds the ability to add custom hosts to the containers known_hosts file to be able to ssh them easily (useful with deployment keys)
<sup>4</sup> Conflicts with [VHOSTS Custom Configuration](https://github.com/neam/dokku-nginx-vhosts-custom-configuration)
### Other Add-ons
| Plugin | Author | Compatibility |
| --- | --- | --- |
| [Node](https://github.com/pnegahdar/dokku-node) | [pnegahdar](https://github.com/pnegahdar) | |
| [Node](https://github.com/ademuk/dokku-nodejs) | [ademuk](https://github.com/ademuk) | |
| [Chef cookbooks](https://github.com/fgrehm/chef-dokku) | [fgrehm][] | |
| [Bower install](https://github.com/alexanderbeletsky/dokku-bower-install) | [alexanderbeletsky][] | |
| [Bower/Grunt](https://github.com/thrashr888/dokku-bower-grunt-build-plugin) | [thrashr888][] | |
| [Bower/Gulp](https://github.com/gdi2290/dokku-bower-gulp-build-plugin) | [gdi2290](https://github.com/gdi2290) | |
| [Elasticsearch](https://github.com/robv/dokku-elasticsearch) | [robv][] | |
| [Elasticsearch](https://github.com/jezdez/dokku-elasticsearch-plugin) | [jezdez][] | Compatible with 0.2.0 |
| [Elasticsearch](https://github.com/blag/dokku-elasticsearch-plugin)<sup>1</sup> | [blag][] | Compatible with 0.2.0 |
| [HipChat Notifications](https://github.com/cef/dokku-hipchat) | [cef][] | |
| [Graphite/statsd] (https://github.com/jlachowski/dokku-graphite-plugin) | [jlachowski][] | |
| [APT](https://github.com/F4-Group/dokku-apt) | [F4-Group][] | |
| [User ACL](https://github.com/mlebkowski/dokku-acl) | [Maciej Łebkowski](https://github.com/mlebkowski) | |
| [PrimeCache](https://github.com/darkpixel/dokku-prime-cache) | [darkpixel](https://github.com/darkpixel/) | |
<sup>1</sup> Forked from [jezdez/dokku-elasticsearch-plugin](https://github.com/jezdez/dokku-elasticsearch-plugin): uses Elasticsearch 1.2 (instead of 0.90), doesn't depend on dokku-link, runs as elasticsearch user instead of root, and turns off multicast autodiscovery for use in a VPS environment.

19
docs/remote-commands.md Normal file
View File

@@ -0,0 +1,19 @@
# Remote commands
Dokku commands can be run over ssh. Anywhere you would run `dokku <command>`, just run `ssh -t dokku@progriumapp.com <command>`
The `-t` is used to request a pty. It is highly recommended to do so.
To avoid the need to type the `-t` option each time, simply create/modify a section in the `.ssh/config` on the client side, as follows:
```
Host progriumapp.com
RequestTTY yes
```
## Run a command in the app environment
It's possible to run commands in the environment of the deployed application:
```bash
dokku run node-js-app ls -alh
dokku run <app> <cmd>
```

30
docs/tls-spdy-support.md Normal file
View File

@@ -0,0 +1,30 @@
# TLS/SPDY support
Dokku provides easy TLS/SPDY support out of the box. This can be done app-by-app or for all subdomains at once. Note that whenever TLS support is enabled SPDY is also enabled.
## Per App
To enable TLS connection to to one of your applications, copy or symlink the `.crt`/`.pem` and `.key` files into the application's `/home/dokku/:app/tls` folder (create this folder if it doesn't exist) as `server.crt` and `server.key` respectively.
Redeployment of the application will be needed to apply TLS configuration. Once it is redeployed, the application will be accessible by `https://` (redirection from `http://` is applied as well).
## All Subdomains
To enable TLS connections for all your applications at once you will need a wildcard TLS certificate.
To enable TLS across all apps, copy or symlink the `.crt`/`.pem` and `.key` files into the `/home/dokku/tls` folder (create this folder if it doesn't exist) as `server.crt` and `server.key` respectively. Then, enable the certificates by editing `/etc/nginx/conf.d/dokku.conf` and uncommenting these two lines (remove the #):
```
ssl_certificate /home/dokku/tls/server.crt;
ssl_certificate_key /home/dokku/tls/server.key;
```
The nginx configuration will need to be reloaded in order for the updated TLS configuration to be applied. This can be done either via the init system or by re-deploying the application. Once TLS is enabled, the application will be accessible by `https://` (redirection from `http://` is applied as well).
**Note**: TLS will not be enabled unless the application's VHOST matches the certificate's name. (i.e. if you have a cert for *.example.com TLS won't be enabled for something.example.org or example.net)
## HSTS Header
The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. dokku does not, by default, enable this header. It is thus left up to you, the user, to enable it for your site.
Beware that if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails.

102
docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,102 @@
## Troubleshooting
__Symptom:__ I deployed my app but I am getting the default nginx page
__Solution:__
Most of the time it's caused by some defaults newer versions of nginx set. To make sure that's the issue you're having run the following:
```
root@dockerapps:/home/git# nginx
nginx: [emerg] could not build the server_names_hash, you should increase server_names_hash_bucket_size: 32
```
If you get a similar error just edit __/etc/nginx/nginx.conf__ and add the following line to your http section:
```
http {
(... existing content ...)
server_names_hash_bucket_size 64;
(...)
}
```
Note that the `server_names_hash_bucket_size` setting defines the maximum domain name length.
A value of 64 would allow domains with up to 46 characters. Set it to 128 if you need longer ones.
Save the file and try stopping nginx and starting it again:
```
root@dockerapps:~/dokku/buildstep# /etc/init.d/nginx stop
* Stopping nginx nginx [ OK ]
root@dockerapps:~/dokku/buildstep# /etc/init.d/nginx start
* Starting nginx nginx [ OK ]
```
***
__Symptom:__ I want to deploy my app, but while pushing I get the following error
! [remote rejected] master -> master (pre-receive hook declined)
__Solution:__
The `remote rejected` error does not give enough information. Anything could have failed.
Create a `/home/dokku/dokkurc` file containing the following :
export DOKKU_TRACE=1
This will trace all of dokku's activity. If this does not help you create a pastebin or a gist containing the full log, and create an issue.
***
__Symptom:__ I want to deploy my app but I am getting asked for the password of the git user and the error message
fatal: 'NAME' does not appear to be a git repository
fatal: Could not read from remote repository.
__Solution:__
You get asked for a password because your ssh secret key can't be found. This may happen if the private key corresponding to the public key you added with `sshcommand acl-add` is not located in the default location `~/.ssh/id_rsa`.
You have to point ssh to the correct secret key for your domain name. Add the following to your `~/.ssh/config`:
Host DOKKU_HOSTNAME
IdentityFile "~/.ssh/KEYNAME"
Also see [issue #116](https://github.com/progrium/dokku/issues/116)
***
__Symptom:__ I want to deploy my nodejs app on dokku and use a postinstall script within the package.json but I keep getting this error:
npm WARN cannot run in wd app@1.0.0 echo blah (wd=/build/app)
__Solution:__
This is a permissions problem as dokku (buildstep) uses a root account for running the application. (This may change please see this thread: https://github.com/progrium/buildstep/pull/42).
To allow npm to work as root account one must set the configuration option of ```unsafe-perm``` to true. There are many ways to set this configuration option but the one I've found works most consistently with the heroku-nodejs-buildpack is as a .npmrc file. The file should contain
```
unsafe-perm = true
```
Note that this is NOT required on heroku as heroku does not use a root account for running the application.
Please see https://github.com/progrium/dokku/issues/420 and https://github.com/heroku/heroku-buildpack-nodejs/issues/92.
***
__Symptom:__ I successfully deployed my application with no deployment errors and receiving Bad Gateway when attempting to access application
__Solution:__
In many cases the application will require the a `process.env.PORT` port opposed to a specified port.
When specifying your port you may want to use something similar to:
var port = process.env.PORT || 3000
Please see https://github.com/progrium/dokku/issues/282

73
docs/upgrading.md Normal file
View File

@@ -0,0 +1,73 @@
# Upgrading
Dokku is in active development. You can update the deployment step and the build step separately.
**Note**: If you are upgrading from a revision prior to [27d4bc8c3c](https://github.com/progrium/dokku/commit/27d4bc8c3c19fe580ef3e65f2f85b85101cd83e4), follow the instructions in [this wiki entry](https://github.com/progrium/dokku/wiki/Migrating-to-Dokku-0.2.0).
To update the deploy step (this is updated less frequently):
```bash
cd ~/dokku
git pull origin master
sudo make install
```
Nothing needs to be restarted. Changes will take effect on the next push / deployment.
To update the build step:
```bash
git clone https://github.com/progrium/buildstep.git
cd buildstep
git pull origin master
sudo make build
```
This will build a fresh Ubuntu Quantal image, install a number of packages, and
eventually replace the Docker image for buildstep.
## Migrating from 0.1.0 to 0.2.0
This should be summary of breaking changes between 0.1 and 0.2 version with instructions to upgrade.
### software-properties-common
software-properties-common is now dependency for plugins. Before running dokku install script, make sure it installed.
```bash
> sudo apt-get install software-properties-common
```
### Gitreceive removed
PR [#270](https://github.com/progrium/dokku/pull/270).
Starting with Dokku 0.2.0, [Gitrecieve](https://github.com/progrium/gitreceive) is replaced by a `git`plugin.
Dokku no longer uses the `git` user. Everything is done with the `dokku` user account.
This causes the remote url to change. Instead of pushing to `git@hostname:app`, you should now push to `dokku@hostname:app`.
The url must be modified using the `git remote set-url` command :
git remote set-url deploy dokku@hostname:app
Where `deploy` is the name of the remote.
Additionally, the repositiories on the server must be migrated to work with dokku 0.2.0
There is upgrade [script](https://gist.github.com/plietar/7201430), which is meant to automate this migration. To use it:
1. run the script as root
2. `git pull` to get the latest version of dokku
3. make install
4. `dokku deploy:all`
TDB.
### Cache directory
Commit [#6350f373](https://github.com/progrium/dokku/commit/6350f373be2cef4f3bb90912099e1be6196522d1)
Buildstep have to re-installed in order to support cache directory.
TDB.