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

Fix documentation directory structure

Browse Source 
Also ensure there is a trailing slash on all urls
This commit is contained in:
Jose Diaz-Gonzalez
2016-07-04 22:59:50 -04:00
parent 8c7a031061
commit edc0961e19
35 changed files with 126 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/advanced-usage/backup-recovery.md Normal file
View File

@@ -0,0 +1,40 @@
# Backup and Recovery
> The backup plugin was deprecated in 0.4.x, below are backup recommendations for 0.5.x and later.
## Backup and Migration Tutorial
Because Dokku is git based, rebuilding a deployed app is as easy as pushing from git. You can push to a new server by updating the dokku remote in you local app's repo.
```shell
git remote rm dokku
git remote add dokku dokku@[dokku.me:dokku.me]
git push dokku [master]
```
## Databases
Some plugins, like the official [dokku-postgres](https://github.com/dokku/dokku-postgres) plugin, have built-in commands that allow non-volatile data be exported and imported.
For [dokku-postgres](https://github.com/dokku/dokku-postgres), use:
```shell
dokku postgres:export [db_name] > [db_name].dump
dokku postgres:import [db_name] < [db_name].dump
```
## Volumes and Static Assets
Dokku doesn't enforce a [300mb](https://devcenter.heroku.com/articles/slug-compiler#slug-size) limit on apps, but it's best practice to keep binary assets outside of git. Since containers are considered volatile in Dokku, external stores like s3 or storage mounts should be used for non-volatile items like user uploads. The dokku storage core plugin can be used to mount local directories / volumes inside the docker container.
See the [persistent storage documentation](/dokku/advanced-usage/persistent-storage/) for more details.
## Disaster Recovery
The best plan for disaster recovery is to always keep multiple (remote) copies of your local repo, static assets and periodic database dumps. In case of an emergency when your git repo and backups are completely lost, you can recover the last pushed copy from your remote dokku server (assuming you still have the ssh key).
```shell
mkdir [app-name] ; cd !$
git init && git remote add dokku dokku@[dokku.me:app-name]
git pull dokku/master && git checkout dokku/master
```

57
docs/advanced-usage/deployment-tasks.md Normal file
View File

@@ -0,0 +1,57 @@
# 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:
* Checking a database is initialised
* Running database migrations
* Any commands required to set up the server (e.g. something like a Django `collectstatic`)
## `app.json` and `scripts.dokku`
Dokku accomplishes this by using an `app.json` file. The format in use is similar to format of Heroku's [app.json](https://devcenter.heroku.com/articles/app-json-schema).
However, dokku currently only supports the nodes `scripts.dokku.predeploy` and `scripts.dokku.postdeploy`.
Simply place an `app.json` file in the root of your repository or for dockerfile apps, `ADD` it to /app.
>NOTE: postdeploy changes are *NOT* committed to the app image.
### Example app.json
```json
{
"name": "barebones nodejs",
"description": "A barebones Node.js app using Express 4.",
"keywords": [
"nodejs",
"express"
],
"repository": "https://github.com/michaelshobbs/node-js-sample",
"scripts": {
"dokku": {
"predeploy": "touch /app/predeploy.test",
"postdeploy": "curl https://some.external.api.service.com/deployment?state=success"
}
},
"env": {
"SECRET_TOKEN": {
"description": "A secret key for verifying the integrity of signed cookies.",
"value": "secret"
},
"WEB_CONCURRENCY": {
"description": "The number of processes to run.",
"generator": "echo 5"
}
},
"image": "gliderlabs/herokuish",
"addons": [
"dokku-postgres",
"dokku-redis"
],
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-nodejs"
}
]
}
```

80
docs/advanced-usage/docker-options.md Normal file
View File

@@ -0,0 +1,80 @@
# Docker Container Options
> New as of 0.3.17
Pass [options](https://docs.docker.com/engine/reference/run/) to Docker during Dokku's `build`, `deploy` and `run` phases
```
docker-options <app> [phase(s)] # Display app's Docker options for all phases (or 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)
```
> When specifying multiple phases, they **must** be comma-separated _without_ spaces in between each phase, like so:
>
> ```shell
> dokku docker-options:add myapp deploy,run "-v /home/dokku/logs/myapp:/app/logs"
> ```
## About Dokku phases
Dokku deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to their underlying docker container:
- `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`
## Examples
### Add Docker options
Add some options for the deployed/running app and when executing [`dokku run`](/dokku/deployment/one-off-processes/):
```shell
# Mount a host volume in a Docker container: "-v /host/path:/container/path"
dokku docker-options:add myapp deploy "-v /home/dokku/logs/myapp:/app/logs"
dokku docker-options:add myapp run "-v /home/dokku/logs/myapp:/app/logs"
```
> Note: When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory.
### Output Docker options
```shell
dokku docker-options myapp
```
```
Deploy options:
-v /home/dokku/logs/myapp:/app/logs
Run options:
-v /home/dokku/logs/myapp:/app/logs
```
### Remove a Docker option
```shell
dokku docker-options:remove myapp run "-v /home/dokku/logs/myapp:/app/logs"
```
## Advanced usage
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:
```shell
--link container_name:alias
-v /host/path:/container/path
-v /another/container/path
```
The above example will result in the following options being passed to Docker during `dokku run`:
```shell
--link container_name:alias -v /host/path:/container/path -v /another/container/path
```
You may also include comments (lines beginning with a #) and blank lines in the DOCKER_OPTIONS file.
Move information on Docker options can be found here: http://docs.docker.io/en/latest/reference/run/ .

84
docs/advanced-usage/event-logs.md Normal file
View File

@@ -0,0 +1,84 @@
# Dokku Event Logs
> New as of 0.3.21
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
```
## Usage
Enable the plugin:
```shell
dokku events:on
```
```
Enabling dokku events logger
```
Dokku will then write log entries to `/var/log/syslog` as well as a Dokku-specific logs sub-directory `/var/log/dokku/events.log`, which can be easily displayed with the command `dokku events`:
```shell
dokku events
```
```
Jul 3 16:09:48 dokku.me dokku[127630]: INVOKED: pre-release-buildpack( pythonapp )
Jul 3 16:10:02 dokku.me dokku[128095]: INVOKED: docker-args-run( rubyapp )
Jul 3 16:10:02 dokku.me dokku[128114]: INVOKED: docker-args-run( nhl )
Jul 3 16:10:03 dokku.me dokku[128136]: INVOKED: post-release-buildpack( pythonapp )
Jul 3 16:10:03 dokku.me dokku[128195]: INVOKED: pre-deploy( pythonapp )
Jul 3 16:10:23 dokku.me dokku[129253]: INVOKED: docker-args-deploy( pythonapp )
Jul 3 16:10:24 dokku.me dokku[129337]: INVOKED: bind-external-ip( pythonapp )
Jul 3 16:10:24 dokku.me dokku[129451]: INVOKED: check-deploy( pythonapp 6274ced0d4be11af4490cd18abaf77cdd593f025133f403d984e80d86a39acec web 5000 10.0.16.80 )
Jul 3 16:10:35 dokku.me dokku[129561]: INVOKED: docker-args-deploy( pythonapp )
Jul 3 16:10:35 dokku.me dokku[129649]: INVOKED: bind-external-ip( pythonapp )
Jul 3 16:10:36 dokku.me dokku[129760]: INVOKED: check-deploy( pythonapp ac88a56ee4161ff37e4b92d1498c3eadc91f0aa7c8b81b44fc077e2a51d54cc0 worker )
Jul 3 16:10:46 dokku.me dokku[129851]: INVOKED: post-deploy( pythonapp )
Jul 3 16:10:46 dokku.me dokku[129945]: INVOKED: nginx-pre-reload( pythonapp )
Jul 3 16:15:02 dokku.me dokku[130397]: INVOKED: docker-args-run( goapp )
Jul 3 16:21:02 dokku.me dokku[130796]: INVOKED: docker-args-run( rubyapp )
Jul 3 16:30:02 dokku.me dokku[131384]: INVOKED: docker-args-run( rubyapp )
```
You can list all events that are currently being recorded via `dokku events:list`:
```shell
dokku events:list
```
```
=====> Events currently logged
docker-args-build
pre-delete
post-deploy
receive-app
pre-release-buildpack
nginx-pre-reload
docker-args-deploy
post-build-buildpack
post-domains-update
post-release-dockerfile
check-deploy
git-pre-pull
git-post-pull
nginx-hostname
bind-external-ip
pre-deploy
post-delete
dependencies
pre-build-buildpack
docker-args-run
pre-build-dockerfile
post-release-buildpack
post-build-dockerfile
pre-release-dockerfile
update
```

73
docs/advanced-usage/persistent-storage.md Normal file
View File

@@ -0,0 +1,73 @@
# Persistent Storage
> New as of 0.5.0
The preferred method to mount external containers to a dokku managed container, is to use the dokku storage plugin.
```
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:
```shell
dokku storage:mount app-name /var/lib/dokku/data/storage:/storage
```
Dokku will then mount the shared contents of `/var/lib/dokku/data/storage` to `/storage` inside the container.
A more complete workflow may require making a custom directory for your application and mounting it within your `/app/storage` directory instead. The mount point is *not* relative to your application's working directory, and is instead relative to the root of the container.
```shell
# creating storage for the app 'ruby-rails-sample'
mkdir -p /var/lib/dokku/data/storage/ruby-rails-sample
# ensure the dokku user has access to this directory
chown -R dokku:dokku /var/lib/dokku/data/storage/ruby-rails-sample
# mount the directory into your container's /app/storage directory, relative to root
dokku storage:mount app-name /var/lib/dokku/data/storage/app-name:/app/storage
```
You can mount one or more directories as desired by following the above pattern.
## Use Cases
### 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
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
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
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.
### Build phase
By default, dokku will only bind storage mounts during the deploy and run phases. Under certain conditions, one might want to bind a storage mount during the build phase. This can be accomplished by using the `docker-options` plugin directly.
```shell
dokku docker-options:add <app> "-v /tmp/python-test:/opt/test"
```
NOTE: **This can cause data loss** if you bind a mount under `/app` in buildpack apps as herokuish will attempt to remove the original app path during the build phase.
## Docker-Options Note
The storage plugins is compatible with storage mounts created with the docker-options. The storage plugin will only list mounts from the deploy phase.

142
docs/advanced-usage/proxy-management.md Normal file
View File

@@ -0,0 +1,142 @@
# Proxy Management
> New as of 0.5.0, Enhanced in 0.6.0
```
proxy <app> # Show proxy settings for app
proxy:disable <app> # Disable proxy for app
proxy:enable <app> # Enable proxy for app
proxy:ports <app> # List proxy port mappings for app
proxy:ports-add <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Set proxy port mappings for app
proxy:ports-clear <app> # Clear all proxy port mappings for app
proxy:ports-remove <app> <host-port> [<host-port>|<scheme>:<host-port>:<container-port>...] # Unset proxy port mappings for app
proxy:set <app> <proxy-type> # Set proxy type for app
```
In Dokku 0.5.0, port proxying was decoupled from the `nginx-vhosts` plugin into the proxy plugin. Dokku 0.6.0 introduced the ability to map host ports to specific container ports. In the future this will allow other proxy software - such as HAProxy or Caddy - to be used in place of nginx.
## Container network interface binding
> New as of 0.5.0
By default, the deployed docker container running your app's web process will bind to the internal docker network interface (i.e. `docker inspect --format '{{ .NetworkSettings.IPAddress }}' $CONTAINER_ID`). This behavior can be modified per app by disabling the proxy (i.e. `dokku proxy:disable <app>`). In this case, the container will bind to an external interface (i.e. `0.0.0.0`) and your app container will be directly accessible by other hosts on your network.
> If a proxy is disabled, dokku will bind your container's port to a random port on the host for every deploy, e.g. `0.0.0.0:32771->5000/tcp`.
By way of example, in the default case, each container is bound to the docker interface:
```shell
docker ps
```
```
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1b88d8aec3d1 dokku/node-js-app:latest "/bin/bash -c '/star About a minute ago Up About a minute node-js-app.web.1
```
As such, the container's IP address will be an internal IP, and thus it is only accessible on the host itself:
```
docker inspect --format '{{ .NetworkSettings.IPAddress }}' node-js-app.web.1
```
```
172.17.0.6
```
However, you can disable the internal proxying via the `proxy:disable` command so that it will listen on the host's IP address:
```shell
dokku proxy:disable node-js-app
# container bound to all interfaces
docker ps
```
```
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d6499edb0edb dokku/node-js-app:latest "/bin/bash -c '/star About a minute ago Up About a minute 0.0.0.0:49153->5000/tcp node-js-app.web.1
```
## Proxy port mapping
> New as of 0.6.0
You can now configure `host -> container` port mappings with the `proxy:ports-*` commands. This mapping is currently supported by the built-in nginx-vhosts plugin.
To inspect the port mapping for a given application, use the `proxy:ports` command:
```shell
dokku proxy:ports node-js-app
```
```
-----> Port mappings for node-js-app
-----> scheme host port container port
http 80 5000
```
The above application is listening on the host's port `80`, which we can test via curl:
```shell
curl http://node-js-app.dokku.me
```
```
Hello World!
```
There are cases where we may wish for the service to be listening on more than one port, such as port 8080. Normally, this would not be possible:
```shell
curl http://node-js-app.dokku.me:8080
```
```
curl: (7) Failed to connect to node-js-app.dokku.me port 8080: Connection refused
```
However, we can use the `proxy:ports-add` command to add a second external port mapping - `8080` - to our application's port `5000`.
```shell
dokku proxy:ports-add node-js-app http:8080:5000
```
```
-----> Setting config vars
DOKKU_PROXY_PORT_MAP: http:80:5000 http:8080:5000
-----> Configuring node-js-app.dokku.me...(using built-in template)
-----> Creating http nginx.conf
-----> Running nginx-pre-reload
Reloading nginx
```
We can now test that port 80 still responds properly:
```shell
curl http://node-js-app.dokku.me
```
```
Hello World!
```
And our new listening port of `8080` also works:
```shell
curl http://node-js-app.dokku.me:8080
```
```
Hello World!
```
You can also remove a port mapping that is no longer necessary:
```shell
dokku proxy:ports-remove node-js-app http:80:5000
```
By default, buildpack apps and dockerfile apps **without** explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on port `80` (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port `5000`. Dockerfile apps **with** explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container.
> NOTE: This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `proxy:ports-*` syntax detailed above.