github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

General documentation formatting

Browse Source
This commit is contained in:
Jose Diaz-Gonzalez
2015-10-14 05:29:38 -04:00
parent d665dbacb9
commit 917e26ad82
8 changed files with 88 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/deployment/ssl-configuration.md
View File

@@ -5,11 +5,11 @@
Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the `certs` plugin. Note that whenever SSL/TLS support is enabled SPDY is also enabled.
```
certs:add <app> CRT KEY Add an ssl endpoint to an app. Can also import from a tarball on stdin.
certs:generate <app> DOMAIN Generate a key and certificate signing request (and self-signed certificate)
certs:info <app> Show certificate information for an ssl endpoint.
certs:remove <app> Remove an SSL Endpoint from an app.
certs:update <app> CRT KEY Update an SSL Endpoint on an app. Can also import from a tarball on stdin
certs:add <app> CRT KEY Add an ssl endpoint to an app. Can also import from a tarball on stdin.
certs:generate <app> DOMAIN Generate a key and certificate signing request (and self-signed certificate)
certs:info <app> Show certificate information for an ssl endpoint.
certs:remove <app> Remove an SSL Endpoint from an app.
certs:update <app> CRT KEY Update an SSL Endpoint on an app. Can also import from a tarball on stdin
```
## Per-application certificate management
@@ -22,7 +22,7 @@ The `certs:add` command can be used to push a `tar` containing a certificate `.c
```shell
tar cvf cert-key.tar server.crt server.key
# replace APP with your app name
# replace APP with the name of your application
dokku certs:add < cert-key.tar
```

49
docs/dns.md
View File

@@ -2,51 +2,51 @@
This is a work in progress.
## DNS Versions
### 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
### 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
### 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!
### 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'.
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'.
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.
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.
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?
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?
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.
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.
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.
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:
@@ -55,26 +55,23 @@ $ORIGIN example.tld
$TTL 5m
myserver IN A 127.0.0.1
*.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
* `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:
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 test.myserver.example.tld`
* `host xyzzy.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.
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)
@@ -84,5 +81,5 @@ 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
* hostname is under `example.tld`, still needs `A` record
* Need to modify `/home/dokku/HOSTNAME` and `/home/dokku/VHOST`

61
docs/docker-options.md
View File

@@ -1,57 +1,50 @@
docker-options
========================
# Docker Options
Usage
-----
```
docker-options <app> Display apps docker options for all phases
docker-options <app> <phase(s)> Display apps docker options for phase (comma-separated phase list)
docker-options:add <app> <phase(s)> OPTION Add docker option to app for phase (comma-separated phase list)
docker-options:remove <app> <phase(s)> OPTION Remove docker option from app for phase (comma-separated phase list)
```
```bash
$ dokku help
...
docker-options <app> Display apps docker options for all phases
docker-options <app> <phase(s)> Display apps docker options for phase (comma-separated phase list)
docker-options:add <app> <phase(s)> OPTION Add docker option to app for phase (comma-separated phase list)
docker-options:remove <app> <phase(s)> OPTION Remove docker option from app for phase (comma-separated phase list)
...
````
Add some options (first, for the deployed/running app and second when executing `dokku run`):
Add some options (first, for the deployed/running app and second when executing `dokku run`)
```bash
$ dokku docker-options:add myapp deploy "-v /host/path:/container/path"
$ dokku docker-options:add myapp run "-v /another/container/path"
```
dokku docker-options:add myapp deploy "-v /host/path:/container/path"
dokku docker-options:add myapp run "-v /another/container/path"
```
Check what we added
```bash
$ dokku docker-options myapp
Deploy options:
-v /host/path:/container/path
Run options:
-v /another/container/path
```shell
dokku docker-options myapp
# Deploy options:
# -v /host/path:/container/path
# Run options:
# -v /another/container/path
```
Remove an option
```bash
$ dokku docker-options:remove myapp run "--link container_name:alias"
```shell
dokku docker-options:remove myapp run "--link container_name:alias"
```
Note about `dokku` phases and `docker-options`
------------
`dokku` deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to the underlying docker container in the following 3 phases/containers
### Note about `dokku` phases and `docker-options`
`dokku` deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to the underlying docker container in the following 3 phases/containers:
- `build`: the container that executes the appropriate buildpack
- `deploy`: the container that executes your running/deployed application
- `run`: the container that executes any arbitrary command via `dokku run myapp`
Advanced Usage (avoid if possible)
------------
## Advanced Usage (avoid if possible)
In your applications folder (`/home/dokku/app_name`) create a file called `DOCKER_OPTIONS_RUN` (or `DOCKER_OPTIONS_BUILD` or `DOCKER_OPTIONS_DEPLOY`).
Inside this file list one docker option per line. For example:
```bash
```shell
--link container_name:alias
-v /host/path:/container/path
-v /another/container/path
@@ -59,7 +52,7 @@ Inside this file list one docker option per line. For example:
The above example will result in the following options being passed to docker during `dokku run`:
```bash
```shell
--link container_name:alias -v /host/path:/container/path -v /another/container/path
```

8
docs/dokku-events-logs.md
View File

@@ -3,10 +3,10 @@
Docker provides an _events_ command to show system's real time events. Likewise, Dokku can record events as syslog entries and also provides a plugin to display the last ones.
```
events [-t] Show the last events (-t follows)
events:list List logged events
events:on Enable events logger
events:off Disable events logger
events [-t] Show the last events (-t follows)
events:list List logged events
events:on Enable events logger
events:off Disable events logger
```
## Usage

32
docs/nginx.md
View File

@@ -3,11 +3,11 @@
Dokku uses nginx as it's server for routing requests to specific applications. By default, access and error logs are written for each app to `/var/log/nginx/${APP}-access.log` and `/var/log/nginx/${APP}-error.log` respectively
```
nginx:access-logs <app> [-t] Show the nginx access logs for an application (-t follows)
nginx:build-config <app> (Re)builds nginx config for given app
nginx:disable <app> disable nginx for an application (forces container binding to external interface)
nginx:enable <app> enable nginx for an application
nginx:error-logs <app> [-t] Show the nginx error logs for an application (-t follows)
nginx:access-logs <app> [-t] Show the nginx access logs for an application (-t follows)
nginx:build-config <app> (Re)builds nginx config for given app
nginx:disable <app> Disable nginx for an application (forces container binding to external interface)
nginx:enable <app> Enable nginx for an application
nginx:error-logs <app> [-t] Show the nginx error logs for an application (-t follows)
```
## TLS/SPDY support
@@ -23,8 +23,8 @@ In 0.4.0, SSL Configuration has been replaced by the [`certs` plugin](http://pro
To enable TLS connections to to one of your applications, do the following:
* Create a key file and a cert file.
* You can find detailed steps for generating a self-signed certificate at https://devcenter.heroku.com/articles/ssl-certificate-self
* If you are not paranoid and need it just for a DEV or STAGING app, you can use http://www.selfsignedcertificate.com/ to generate your 2 files more easily.
* You can find detailed steps for generating a self-signed certificate at https://devcenter.heroku.com/articles/ssl-certificate-self
* If you are not paranoid and need it just for a DEV or STAGING app, you can use http://www.selfsignedcertificate.com/ to generate your 2 files more easily.
* Rename your files to server.key and server.crt
* tar these 2 files together, *without* subdirectories. Example: tar cvf cert-key.tar server.crt server.key
* Install the pair for your app, like this: ssh dokku@ip-of-your-dokku-server nginx:import-ssl < cert-key.tar
@@ -45,7 +45,7 @@ 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)
**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
@@ -137,14 +137,18 @@ After your changes a `dokku deploy myapp` will regenerate the `/home/dokku/myapp
The default nginx.conf- templates will include everything from your apps `nginx.conf.d/` subdirectory in the main `server {}` block (see above):
include $DOKKU_ROOT/$APP/nginx.conf.d/*.conf;
```
include $DOKKU_ROOT/$APP/nginx.conf.d/*.conf;
```
. That means you can put additional configuration in separate files, for example to limit the uploaded body size to 50 megabytes, do
mkdir /home/dokku/myapp/nginx.conf.d/
echo 'client_max_body_size 50M;' > /home/dokku/myapp/nginx.conf.d/upload.conf
chown dokku:dokku /home/dokku/myapp/nginx.conf.d/upload.conf
service nginx reload
```shell
mkdir /home/dokku/myapp/nginx.conf.d/
echo 'client_max_body_size 50M;' > /home/dokku/myapp/nginx.conf.d/upload.conf
chown dokku:dokku /home/dokku/myapp/nginx.conf.d/upload.conf
service nginx reload
```
## Customizing hostnames
@@ -228,7 +232,7 @@ d6499edb0edb dokku/node-js-app:latest "/bin/bash -c '/star About a mi
```
# Default site
## Default site
By default, dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. If this is not the desired behavior, you may want to add the following configuration to the global nginx configuration. This will catch all unknown HOST header values and return a `410 Gone` response. You can replace the `return 410;` with `return 444;` which will cause nginx to not respond to requests that do not match known domains (connection refused).

16
docs/process-management.md
View File

@@ -3,14 +3,14 @@
Dokku supports rudimentary process (really container) management via the `ps` plugin.
```
ps <app> List processes running in app container(s)
ps:rebuildall Rebuild all apps
ps:rebuild <app> Rebuild an app
ps:restartall Restart all deployed app containers
ps:restart <app> Restart app container(s)
ps:scale <app> <proc>=<count> [<proc>=<count>] Set how many processes of a given process to run
ps:start <app> Start app container(s)
ps:stop <app> Stop app container(s)
ps <app> List processes running in app container(s)
ps:rebuildall Rebuild all apps
ps:rebuild <app> Rebuild an app
ps:restartall Restart all deployed app containers
ps:restart <app> Restart app container(s)
ps:scale <app> <proc>=<count> [<proc>=<count>] Set how many processes of a given process to run
ps:start <app> Start app container(s)
ps:stop <app> Stop app container(s)
```
## Scaling

2
docs/remote-commands.md
View File

@@ -1,4 +1,4 @@
# Remote commands
# Remote Commands
Dokku commands can be run over ssh. Anywhere you would run `dokku <command>`, just run `ssh -t dokku@dokku.me <command>`
The `-t` is used to request a pty. It is highly recommended to do so.

2
docs/upgrading.md
View File

@@ -1,6 +1,6 @@
# Upgrading
This document covers upgrades for the 0.3.0 series and up. If upgrading from previous versions, we recommend [a fresh install](http://progrium.viewdocs.io/dokku/installation) on a new server.
This document covers upgrades for the 0.3.0 series and up. If upgrading from older versions, we recommend [a fresh install](http://progrium.viewdocs.io/dokku/installation) on a new server.
> As of 0.3.18, dokku is installed by default via a debian package. Source-based installations are still available, though not recommended.