Merge pull request #1963 from dokku/doc-fixes

Doc fixes
This commit is contained in:
Jose Diaz-Gonzalez
2016-03-08 21:36:57 -05:00
15 changed files with 316 additions and 22 deletions

View File

@@ -16,9 +16,11 @@ Output of the following commands
- `cat /home/dokku/<app>/nginx.conf` (if applicable):
- Link to the exact repository being deployed (if possible/applicable):
- If a deploy is failing:
- the type of application being deployed (node, php, python, ruby, etc.)
- whether or not you have a `Dockerfile` in the root of your repository
- if using buildpacks, which custom buildpacks are in use
- Application name
- The type of application being deployed (node, php, python, ruby, etc.)
- Whether or not you have a `Dockerfile` in the root of your repository
- If using buildpacks, which custom buildpacks are in use
- If it exists, the contents of your `Procfile`.
- Output of failing dokku commands after running `dokku trace on`
(BEWARE: `trace on` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX):

View File

@@ -1,4 +1,4 @@
# Dokku [![Build Status](https://img.shields.io/circleci/project/dokku/dokku/master.svg?style=flat-square "Build Status")](https://circleci.com/gh/dokku/dokku/tree/master) [![Ubuntu Package](https://img.shields.io/badge/package-ubuntu-brightgreen.svg?style=flat-square "Ubuntu Package")](https://packagecloud.io/dokku/dokku) [![IRC Network](https://img.shields.io/badge/irc-freenode-blue.svg?style=flat-square "IRC Freenode")](https://webchat.freenode.net/?channels=dokku) [![Documentation](https://img.shields.io/badge/docs-viewdocs-blue.svg?style=flat-square "Viewdocs")](http://dokku.viewdocs.io/dokku/) [![Gratipay](https://img.shields.io/gratipay/dokku.svg?style=flat-square)](https://gratipay.com/dokku/)
# Dokku [![Build Status](https://img.shields.io/circleci/project/dokku/dokku/master.svg?style=flat-square "Build Status")](https://circleci.com/gh/dokku/dokku/tree/master) [![Ubuntu Package](https://img.shields.io/badge/package-ubuntu-brightgreen.svg?style=flat-square "Ubuntu Package")](https://packagecloud.io/dokku/dokku) [![IRC Network](https://img.shields.io/badge/irc-freenode-blue.svg?style=flat-square "IRC Freenode")](https://webchat.freenode.net/?channels=dokku) [![Slack Group](https://img.shields.io/badge/irc-slack-blue.svg?style=flat-square "Slack Group")](https://glider-slackin.herokuapp.com/) [![Documentation](https://img.shields.io/badge/docs-viewdocs-blue.svg?style=flat-square "Viewdocs")](http://dokku.viewdocs.io/dokku/) [![Gratipay](https://img.shields.io/gratipay/dokku.svg?style=flat-square)](https://gratipay.com/dokku/)
Docker powered mini-Heroku. The smallest PaaS implementation you've ever seen. Sponsored by our friends at [Deis](http://deis.io/).

View File

@@ -1,5 +1,7 @@
# 0.5.0 Migration Guide
## nginx-vhosts
- The nginx-vhosts template language is now [sigil](https://github.com/gliderlabs/sigil)
- No need to escape literal `$` characters (or other "bash-isms")
- Template variables are represented as {{ .VARIABLE_NAME }}

View File

@@ -256,3 +256,48 @@ blockquote.new-as-of {
margin-top: 120px;
}
}
.rst-versions.rst-badge {display: block;}
.rst-other-versions {text-align: left;}
.rst-other-versions a {border: 0;}
.rst-other-versions dl {margin: 0;}
.bookmark-added-msg {display: none;}
.bookmark-active {display: none;}
.bookmark-inactive {display: none;}
.fa:before{-webkit-font-smoothing:antialiased}
.clearfix{*zoom:1}
.clearfix:before,.clearfix:after{display:table;content:""}
.clearfix:after{clear:both}
a .fa{display:inline-block;text-decoration:inherit}
li .fa{display:inline-block}
li .fa-large:before,li .fa-large:before{width:1.875em}
ul.fas{list-style-type:none;margin-left:2em;text-indent:-0.8em}
ul.fas li .fa{width:0.8em}
ul.fas li .fa-large:before,ul.fas li .fa-large:before{vertical-align:baseline}
.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;border-top:solid 10px #343131;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;font-size:13px;z-index:400}
.rst-versions a{color:#2980B9;text-decoration:none}
.rst-versions .rst-badge-small{display:none}
.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27AE60;*zoom:1}
.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{display:table;content:""}
.rst-versions .rst-current-version:after{clear:both}
.rst-versions .rst-current-version .fa{color:#fcfcfc}
.rst-versions .rst-current-version .fa-book{float:left; line-height: 30px}
.rst-versions .rst-current-version .icon-book{float:left}
.rst-versions .rst-current-version.rst-out-of-date{background-color:#E74C3C;color:#fff}
.rst-versions .rst-current-version.rst-active-old-version{background-color:#F1C40F;color:#000}
.rst-versions.shift-up .rst-other-versions{display:block}
.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:gray;display:none}
.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #413d3d}
.rst-versions .rst-other-versions dd{display:inline-block;margin:0}
.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}
.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px}
.rst-versions.rst-badge .icon-book{float:none}
.rst-versions.rst-badge .fa-book{float:none}
.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}
.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{float:left}
.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}
.rst-versions.rst-badge .rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}
@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}
.rst-versions.shift{display:block}img{width:100%;height:auto}}

View File

@@ -0,0 +1,6 @@
{
"max-versions": [
"0.3.26",
"0.4.14"
]
}

View File

@@ -1,5 +1,7 @@
# Zero Downtime Deploys
> Plugin management is New as of 0.5.0
```
checks <app> Show zero-downtime status
checks:disable <app> Disable zero-downtime checks
@@ -39,6 +41,8 @@ To specify checks, add a `CHECKS` file to the root of your project directory. Th
* Comments (lines starting with #)
* Empty lines
> For dockerfile-based deploys, the file *must* be in `/app/CHECKS` within the container. `/app` is used by default as the root container directory for buildpack-based deploys.
### Check Instructions
The format of a check instruction is a path or relative URL, optionally followed by the expected content:

View File

@@ -1,5 +1,7 @@
# Deployment Tasks
> New as of 0.5.0
Sometimes you need to run a command on at deployment time, but before an app is completely deployed.
Common use cases include:

View File

@@ -42,13 +42,15 @@ Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disa
### Procfiles and Multiple Processes
> New as of 0.5.0
You can also customize the run command using a `Procfile`, much like you would on Heroku or
with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process
types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types).
When you deploy your app a Docker image will be built, the `Procfile` will be extracted from the image
(it must be in the folder defined in your `Dockerfile` as `WORKDIR` or `/app`) and the commands
in it will be passed to `docker run` to start your process(es). Here's an example `Procfile`:
```
web: bin/run-prod.sh
worker: bin/run-worker.sh

View File

@@ -1,4 +1,4 @@
# One-off Processes
# One-off Processes and Cron
Sometimes you need to either inspect running containers or run a one-off command under an application. In those cases, Dokku makes it easy to either connect to a running container or run a fresh container.

View File

@@ -18,6 +18,7 @@ To propose a release, the following tasks need to be performed:
- The versioned links should be updated in the `docs/home.html` file.
- The versioned links should be updated in the `docs/template.html` file.
- The versioned links should be updated in the `docs/template.html` file.
- The versioned links should be updated or added to the `docs/assets/versions.raw` file.
- A list of changes must be made in the `HISTORY.md`.
- A tag must be created locally with your release version
- Debian packages *must* be created via `vagrant up build`

View File

@@ -1,21 +1,22 @@
# Dokku Core Storage Plugin
> Spanking New as of 0.5.0
> New as of 0.5.0
As of Dokku 0.5.0, the preferred method to mount external containers to a dokku managed container, is to use the dokku storage plugin.
The preferred method to mount external containers to a dokku managed container, is to use the dokku storage plugin.
```shell
$ dokku storage:help
storage:list <app>, List bind mounts for app's container(s) (host:container)
storage:mount <app> <host-dir:container-dir>, Create a new bind mount
storage:unmount <app> <host-dir:container-dir>, Remove an existing bind mount
storage:list <app>, List bind mounts for app's container(s) (host:container)
storage:mount <app> <host-dir:container-dir>, Create a new bind mount
storage:unmount <app> <host-dir:container-dir>, Remove an existing bind mount
```
## Ideology and Background
The storage plugin requires explicit paths on the host side. This is intentional to ensure that new users avoid running into unexpected results with implicit paths that may not exist (a feature deprecate in [Docker 1.9.0](https://github.com/docker/docker/releases/tag/v1.9.0])). The container directory is created for the mount point in the container. Any existing directory contents are not accessible after a mount is added to the container. Dokku creates a new directory `/var/lib/dokku/data/storage` during installation, it's the general consensus that new users should use this directory. Mounts are only available at run and deploy times, you must redeploy (restart) an app to mount or unmount to an existing app's container.
## Usage
This example demonstrates how to mount the recommended directory to `/storage` inside the container:
```
$ dokku storage:mount app-name /var/lib/dokku/data/storage:/storage
@@ -24,19 +25,19 @@ Dokku will then mount the shared contents of`/var/lib/dokku/storage` to `/storag
## Use Cases
##### Persistent storage
### Persistent storage
Dokku is powered by Docker containers, which recommends in their [best practices](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/#containers-should-be-ephemeral) that containers be treated as ephemeral. In order to manage persistent storage for web applications, like user uploads or large binary assets like images, a directory outside the container should be mounted.
##### Shared storage between containers
### Shared storage between containers
When scaling your app, you may require a common location to access shared assets between containers, a storage mount can be used in this situation.
##### Shared storage across environments
### Shared storage across environments
Your app may be used in a cluster that requires containers or resources not running on the same host access your data. Mounting a shared file service (like S3FS or EFS) inside your container will give you great flexibility.
##### Backing up
### Backing up
Your app may have services that are running in memory and need to be backed up locally (like a key store). Mount a non ephemeral storage mount will allow backups that are not lost when the app is shut down.

View File

@@ -10,6 +10,8 @@ nginx:error-logs <app> [-t]
## Customizing the nginx configuration
> New as of 0.5.0
Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. If you'd like to provide a custom template for your application, there are a couple options:
- Copy the following example template to a file named `nginx.conf.sigil` and either:
@@ -193,3 +195,7 @@ See the [HSTS documentation](/dokku/deployment/ssl-configuration/#hsts-header).
## SSL Configuration
See the [ssl documentation](/dokku/deployment/ssl-configuration/).
## Disabling Nginx
See the [proxy documentation](/dokku/deployment/proxy/).

View File

@@ -1,5 +1,7 @@
# Proxy plugin
> New as of 0.5.0
As of dokku 0.5.0, the proxy functionality has been decoupled from the nginx-vhosts plugin into the proxy plugin. In the future this will allow other proxy software (HAproxy for example) to be used instead of nginx.
```

View File

@@ -34,7 +34,52 @@
<link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.0.0-alpha/css/bootstrap.min.css" rel="stylesheet">
<link href="https://cdn.rawgit.com/dokku/dokku/v0.4.14/docs/assets/style.css" rel="stylesheet">
<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css" rel="stylesheet">
<style>
.rst-versions.rst-badge {display: block;}
.rst-other-versions {text-align: left;}
.rst-other-versions a {border: 0;}
.rst-other-versions dl {margin: 0;}
.bookmark-added-msg {display: none;}
.bookmark-active {display: none;}
.bookmark-inactive {display: none;}
.fa:before{-webkit-font-smoothing:antialiased}
.clearfix{*zoom:1}
.clearfix:before,.clearfix:after{display:table;content:""}
.clearfix:after{clear:both}
a .fa{display:inline-block;text-decoration:inherit}
li .fa{display:inline-block}
li .fa-large:before,li .fa-large:before{width:1.875em}
ul.fas{list-style-type:none;margin-left:2em;text-indent:-0.8em}
ul.fas li .fa{width:0.8em}
ul.fas li .fa-large:before,ul.fas li .fa-large:before{vertical-align:baseline}
.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#15518d;border-top:solid 10px #343131;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;font-size:13px;z-index:400}
.rst-versions a{color:#7c8e98;text-decoration:none}
.rst-versions .rst-badge-small{display:none}
.rst-versions .rst-current-version{padding:12px;background-color:#2475c3;display:block;text-align:right;font-size:90%;cursor:pointer;color:#d8edf8;*zoom:1}
.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{display:table;content:""}
.rst-versions .rst-current-version:after{clear:both}
.rst-versions .rst-current-version .fa{color:#fcfcfc}
.rst-versions .rst-current-version .fa-book{float:left; line-height: 30px}
.rst-versions .rst-current-version .icon-book{float:left}
.rst-versions .rst-current-version.rst-out-of-date{background-color:#E74C3C;color:#fff}
.rst-versions .rst-current-version.rst-active-old-version{background-color:#F1C40F;color:#000}
.rst-versions.shift-up .rst-other-versions{display:block}
.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:light-gray;display:none}
.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #d6edf9}
.rst-versions .rst-other-versions dd{display:inline-block;margin:0}
.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}
.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px}
.rst-versions.rst-badge .icon-book{float:none}
.rst-versions.rst-badge .fa-book{float:none}
.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}
.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{float:left}
.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}
.rst-versions.rst-badge .rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}
@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}
.rst-versions.shift{display:block}img{width:100%;height:auto}}
</style>
</head>
<body>
@@ -59,7 +104,7 @@
<div class="list-group">
<a href="#" class="list-group-item disabled">Getting Started</a>
<a href="/dokku/installation/" class="list-group-item">Getting Started with Dokku</a>
<a href="/dokku/upgrading/" class="list-group-item">Upgrading</a>
<a href="/dokku/upgrading/" class="list-group-item">Upgrading Dokku</a>
<a href="/dokku/troubleshooting/" class="list-group-item">Troubleshooting</a>
<a href="/dokku/getting-started/where-to-get-help/" class="list-group-item">Getting Help</a>
@@ -70,9 +115,9 @@
<a href="/dokku/deployment/dockerfiles/" class="list-group-item">Dockerfile Deployment</a>
<a href="/dokku/deployment/images/" class="list-group-item">Image Tagging</a>
<a href="/dokku/remote-commands/" class="list-group-item">Remote Commands</a>
<a href="/dokku/deployment/one-off-processes/" class="list-group-item">One Off Processes</a>
<a href="/dokku/deployment/one-off-processes/" class="list-group-item">One Off Processes/Cron</a>
<a href="/dokku/process-management/" class="list-group-item">Scaling Apps</a>
<a href="/dokku/checks-examples/" class="list-group-item">Zero Downtime Deploys</a>
<a href="/dokku/checks-examples/" class="list-group-item">Zero Downtime Deploy Checks</a>
<a href="#" class="list-group-item disabled">Configuration</a>
@@ -80,10 +125,15 @@
<a href="/dokku/dns" class="list-group-item">DNS Configuration</a>
<a href="/dokku/nginx/" class="list-group-item">Nginx Configuration</a>
<a href="/dokku/deployment/ssl-configuration/" class="list-group-item">SSL Configuration</a>
<a href="/dokku/docker-options/" class="list-group-item">Docker Container Options</a>
<a href="/dokku/dokku-storage/" class="list-group-item">Storage Plugin</a>
<a href="/dokku/dokku-events-logs/" class="list-group-item">Dokku Event Logs</a>
<a href="#" class="list-group-item disabled">Advanced Usage</a>
<a href="/dokku/backup-recovery/" class="list-group-item">Backup and Recovery</a>
<a href="/dokku/deployment/deployment-tasks/" class="list-group-item">Deployment Tasks</a>
<a href="/dokku/docker-options/" class="list-group-item">Docker Container Options</a>
<a href="/dokku/dokku-storage/" class="list-group-item">Persistent Storage</a>
<a href="/dokku/proxy/" class="list-group-item">Proxy Management</a>
<a href="#" class="list-group-item disabled">Community Contributions</a>
@@ -101,6 +151,46 @@
</div>
</div>
<div class="injected">
<div class="rst-versions rst-badge" data-toggle="rst-versions">
<span class="rst-current-version" data-toggle="rst-current-version" data-doc="{{DOC}}" data-ref="{{REF}}">
<span class="fa fa-book">&nbsp;</span>
v: {{REF}}
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<dl>
<dt>Versions</dt>
</dl>
<dl>
<dt>On GitHub</dt>
<dd>
<a href="https://github.com/{{USER}}/{{NAME}}/blob/master/docs/{{DOC}}" target="_blank">View</a>
</dd>
<dd>
<a href="https://github.com/{{USER}}/{{NAME}}/edit/master/docs/{{DOC}}" target="_blank">Edit</a>
</dd>
</dl>
<!--
<dl>
<dt>Search</dt>
<dd>
<div style="padding: 6px;">
<form id="flyout-search-form" class="wy-form" target="_blank" action="/dokku/search" method="get">
<input type="text" name="q" placeholder="Search docs">
</form>
</div>
</dd>
</dl>
-->
<hr>
Free document hosting provided by <a href="http://progrium.viewdocs.io/viewdocs/">Viewdocs</a>.
</div>
</div>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/1.3.0/anchor.js"></script>
<script>
document.addEventListener("DOMContentLoaded", function (e) {
@@ -115,14 +205,48 @@
var tables = document.querySelectorAll('table'),
blockquotes = document.querySelectorAll('blockquote'),
versionList = document.querySelectorAll('.rst-other-versions dl')[0],
currentVersionEl = document.querySelectorAll('.rst-current-version')[0],
currentVersion = currentVersionEl.getAttribute('data-ref'),
versionContainer = document.querySelectorAll('.rst-versions.rst-badge')[0],
classNames = ['table', 'table-striped', 'table-hover', 'table-condensed'],
localPath = location.pathname.split('/').splice(2).join("/"),
addClass = function (el, className) {
if (el.classList) {
el.classList.add(className);
} else {
el.className += ' ' + className;
}
}
},
hasClass = function(el, className) {
if (el.classList) {
return el.classList.contains(className);
} else {
return new RegExp('(^| )' + className + '( |$)', 'gi').test(el.className);
}
},
removeClass = function(el, className) {
if (el.classList) {
el.classList.remove(className);
} else {
el.className = el.className.replace(new RegExp('(^|\\b)' + className.split(' ').join('|') + '(\\b|$)', 'gi'), ' ');;
}
};
var ls2 = {
save : function(key, jsonData, expirationMS) {
if (typeof (Storage) == "undefined") { return false; }
var record = {value: JSON.stringify(jsonData), timestamp: new Date().getTime()/1000 + expirationMS}
localStorage.setItem(key, JSON.stringify(record));
return jsonData;
},
load : function(key) {
if (typeof (Storage) == "undefined") { return false; }
var record = JSON.parse(localStorage.getItem(key));
if (!record){return false;}
return (new Date().getTime()/1000 < record.timestamp && JSON.parse(record.value));
}
};
Array.prototype.forEach.call(blockquotes, function (el, i) {
if (el.innerHTML.indexOf('New as of') !== -1) {
@@ -134,6 +258,95 @@
addClass(el, className);
});
});
currentVersionEl.addEventListener('click', function() {
if (hasClass(versionContainer, 'shift-up')) {
removeClass(versionContainer, 'shift-up');
} else {
addClass(versionContainer, 'shift-up');
}
});
var range = function(start, count) {
return Array.apply(0, Array(count))
.map(function (element, index) {
return index + start;
});
}
var parseVersions = function(version, versions) {
var pieces = version.split('.'),
prefix = pieces.slice(0, 2).join('.') + '.',
maxPatchVersion = parseInt(pieces.slice(2, 3)[0], 10),
versionRange = range(0, maxPatchVersion + 1);
for (var i in versionRange) {
versions.push(prefix.concat(versionRange[i]));
}
return versions;
}
var addVersionLink = function(version) {
var a = document.createElement('a'),
dd = document.createElement('dd'),
ref = 'dokku~v' + version,
versionName = 'v' + version;
if (version == 'master') {
ref = 'dokku';
versionName = 'master';
}
a.setAttribute('href', "/" + ref + "/" + localPath);
a.appendChild(document.createTextNode(versionName));
if (versionName == currentVersion) {
var strong = document.createElement('strong');
strong.appendChild(a);
dd.appendChild(strong);
} else {
dd.appendChild(a);
}
versionList.appendChild(dd);
};
var processVersions = function(data) {
var versions = [];
for (var key in data['max-versions']) {
if (!data['max-versions'].hasOwnProperty(key)) {
continue;
}
versions = parseVersions(data['max-versions'][key], versions);
}
addVersionLink('master');
Array.prototype.forEach.call(versions, function (version, i) {
addVersionLink(version);
});
};
data = ls2.load('max-versions');
if (!data) {
var request = new XMLHttpRequest();
request.open('GET', '/dokku/assets/versions.json', true);
request.setRequestHeader("Cache-Control", "no-cache, no-store");
request.onload = function() {
if (request.status >= 200 && request.status < 400) {
var data = JSON.parse(request.responseText);
// store for 1 day
ls2.save('max-versions', data, 86400);
processVersions(data);
}
};
request.onerror = function() {
// There was a connection error of some sort
};
request.send();
} else {
processVersions(data);
}
});
</script>
</body>

View File

@@ -6,6 +6,14 @@ This document covers upgrades for the 0.3.0 series and up. If upgrading from old
## Dokku
### Migration Guides
Migration guides contain information regarding the new features introduced in each version and the migration path between versions.
- [0.5 Migration Guide](/dokku/appendices/0.5.0-migration-guide/)
### General Information
If dokku was installed via a debian package, you can upgrade dokku via the following command:
```shell