diff --git a/README.md b/README.md index b1f6c7855..d019ba63a 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ To install the latest stable release, you can run the following commands as a us ### Upgrading -[View the docs for upgrading](http://dokku.viewdocs.io/dokku/upgrading) from an older version of Dokku. +[View the docs for upgrading](http://dokku.viewdocs.io/dokku/getting-started/upgrading/) from an older version of Dokku. ## Documentation @@ -26,11 +26,11 @@ Full documentation - including advanced installation docs - are available online ## Support -You can use [Github Issues](https://github.com/dokku/dokku/issues), check [Troubleshooting](http://dokku.viewdocs.io/dokku/troubleshooting) in the documentation, or join us on [freenode in #dokku](https://webchat.freenode.net/?channels=%23dokku) +You can use [Github Issues](https://github.com/dokku/dokku/issues), check [Troubleshooting](http://dokku.viewdocs.io/dokku/getting-started/troubleshooting/) in the documentation, or join us on [freenode in #dokku](https://webchat.freenode.net/?channels=%23dokku) ## Contribution -After checking [Github Issues](https://github.com/dokku/dokku/issues), the [Troubleshooting Guide](http://dokku.viewdocs.io/dokku/troubleshooting) or having a chat with us on [freenode in #dokku](https://webchat.freenode.net/?channels=%23dokku), feel free to fork and create a Pull Request. +After checking [Github Issues](https://github.com/dokku/dokku/issues), the [Troubleshooting Guide](http://dokku.viewdocs.io/dokku/getting-started/troubleshooting/) or having a chat with us on [freenode in #dokku](https://webchat.freenode.net/?channels=%23dokku), feel free to fork and create a Pull Request. While we may not merge your PR as is, they serve to start conversations and improve the general dokku experience for all users. diff --git a/contrib/dokku-installer.py b/contrib/dokku-installer.py index 21234a6b2..6c29011d4 100755 --- a/contrib/dokku-installer.py +++ b/contrib/dokku-installer.py @@ -218,7 +218,7 @@ PAGE = """ $.post('/setup', data) .done(function() { $("#result").html("Success!") - window.location.href = "http://progrium.viewdocs.io/dokku/application-deployment"; + window.location.href = "http://progrium.viewdocs.io/dokku/deployment/application-deployment/"; }) .fail(function(data) { $("#result").html("Something went wrong...") diff --git a/docs/advanced-usage/backup-recovery.md b/docs/advanced-usage/backup-recovery.md new file mode 100644 index 000000000..1310da765 --- /dev/null +++ b/docs/advanced-usage/backup-recovery.md @@ -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 +``` diff --git a/docs/deployment/deployment-tasks.md b/docs/advanced-usage/deployment-tasks.md similarity index 89% rename from docs/deployment/deployment-tasks.md rename to docs/advanced-usage/deployment-tasks.md index 4ae65fa0f..cb1c20d37 100644 --- a/docs/deployment/deployment-tasks.md +++ b/docs/advanced-usage/deployment-tasks.md @@ -11,14 +11,14 @@ Common use cases include: ## `app.json` and `scripts.dokku` -Dokku accomplishes this by using an `app.json` file. We (mostly) use the same format as Heroku's [app.json](https://devcenter.heroku.com/articles/app-json-schema). +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.", diff --git a/docs/docker-options.md b/docs/advanced-usage/docker-options.md similarity index 81% rename from docs/docker-options.md rename to docs/advanced-usage/docker-options.md index 523e3eab3..cd6261ae8 100644 --- a/docs/docker-options.md +++ b/docs/advanced-usage/docker-options.md @@ -5,14 +5,14 @@ Pass [options](https://docs.docker.com/engine/reference/run/) to Docker during Dokku's `build`, `deploy` and `run` phases ``` -docker-options [phase(s)] Display app's Docker options for all phases (or comma separated phase list) -docker-options:add OPTION Add Docker option to app for phase (comma-separated phase list) -docker-options:remove OPTION Remove Docker option from app for phase (comma-separated phase list) +docker-options [phase(s)] # Display app's Docker options for all phases (or comma separated phase list) +docker-options:add OPTION # Add Docker option to app for phase (comma-separated phase list) +docker-options:remove 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" > ``` @@ -28,7 +28,7 @@ Dokku deploys your application in multiple "phases" and the `docker-options` plu ### Add Docker options -Add some options for the deployed/running app and when executing [`dokku run`](deployment/one-off-processes/): +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" @@ -42,10 +42,13 @@ dokku docker-options:add myapp run "-v /home/dokku/logs/myapp:/app/logs" ```shell dokku docker-options myapp -# Deploy options: -# -v /home/dokku/logs/myapp:/app/logs -# Run options: -# -v /home/dokku/logs/myapp:/app/logs +``` + +``` +Deploy options: + -v /home/dokku/logs/myapp:/app/logs +Run options: + -v /home/dokku/logs/myapp:/app/logs ``` ### Remove a Docker option diff --git a/docs/dokku-events-logs.md b/docs/advanced-usage/event-logs.md similarity index 80% rename from docs/dokku-events-logs.md rename to docs/advanced-usage/event-logs.md index c93d82a1e..524a6423e 100644 --- a/docs/dokku-events-logs.md +++ b/docs/advanced-usage/event-logs.md @@ -5,22 +5,29 @@ 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 Enable the plugin: +```shell +dokku events:on +``` + ``` -$ 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`: +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 ) @@ -42,6 +49,11 @@ 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 diff --git a/docs/dokku-storage.md b/docs/advanced-usage/persistent-storage.md similarity index 86% rename from docs/dokku-storage.md rename to docs/advanced-usage/persistent-storage.md index a2cfd61d5..a3e35fa65 100644 --- a/docs/dokku-storage.md +++ b/docs/advanced-usage/persistent-storage.md @@ -1,14 +1,14 @@ -# Dokku Core Storage Plugin +# 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. -```shell -storage:list , List bind mounts for app's container(s) (host:container) -storage:mount , Create a new bind mount -storage:unmount , Remove an existing bind mount +``` +storage:list # List bind mounts for app's container(s) (host:container) +storage:mount # Create a new bind mount +storage:unmount # Remove an existing bind mount ``` ## Ideology and Background @@ -19,11 +19,11 @@ The storage plugin requires explicit paths on the host side. This is intentional 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 +```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. +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. @@ -61,8 +61,9 @@ Your app may have services that are running in memory and need to be backed up l ### 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. -``` -$ dokku docker-options:add "-v /tmp/python-test:/opt/test" + +```shell +dokku docker-options:add "-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. diff --git a/docs/proxy.md b/docs/advanced-usage/proxy-management.md similarity index 59% rename from docs/proxy.md rename to docs/advanced-usage/proxy-management.md index 692cba32d..50ccd243d 100644 --- a/docs/proxy.md +++ b/docs/advanced-usage/proxy-management.md @@ -1,16 +1,16 @@ -# Proxy plugin +# Proxy Management > New as of 0.5.0, Enhanced in 0.6.0 ``` -proxy Show proxy settings for app -proxy:disable Disable proxy for app -proxy:enable Enable proxy for app -proxy:ports List proxy port mappings for app -proxy:ports-add :: [::...] Set proxy port mappings for app -proxy:ports-clear Clear all proxy port mappings for app -proxy:ports-remove [|::...] Unset proxy port mappings for app -proxy:set Set proxy type for app +proxy # Show proxy settings for app +proxy:disable # Disable proxy for app +proxy:enable # Enable proxy for app +proxy:ports # List proxy port mappings for app +proxy:ports-add :: [::...] # Set proxy port mappings for app +proxy:ports-clear # Clear all proxy port mappings for app +proxy:ports-remove [|::...] # Unset proxy port mappings for app +proxy:set # 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. @@ -23,21 +23,37 @@ By default, the deployed docker container running your app's web process will bi > 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 -# container bound to docker interface -$ docker ps +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 +``` -# internal IP address for the container -$ docker inspect --format '{{ .NetworkSettings.IPAddress }}' 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 +``` -# disable the proxy so it listens on a host ip address -$ dokku proxy:disable node-js-app +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 +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 ``` @@ -48,33 +64,79 @@ d6499edb0edb dokku/node-js-app:latest "/bin/bash -c '/star About a mi 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 +dokku proxy:ports node-js-app +``` + +``` -----> Port mappings for node-js-app -----> scheme host port container port http 80 5000 +``` -$ curl http://node-js-app.dokku.me +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! +``` -$ curl http://node-js-app.dokku.me:8080 +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 +``` -$ dokku proxy:ports-add node-js-app http:8080:5000 +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 +``` -$ curl http://node-js-app.dokku.me -Hello World! +We can now test that port 80 still responds properly: -$ curl http://node-js-app.dokku.me:8080 +```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. diff --git a/docs/appendices/0.5.0-migration-guide.md b/docs/appendices/0.5.0-migration-guide.md index 0890507ae..58f1d1424 100644 --- a/docs/appendices/0.5.0-migration-guide.md +++ b/docs/appendices/0.5.0-migration-guide.md @@ -5,11 +5,11 @@ - 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 }} - - A detailed list of template variables can be found [here](/dokku/nginx#available-template-variables) + - A detailed list of template variables can be found [here](/dokku/configuration/nginx/#available-template-variables) - A custom nginx-vhosts template must be named `nginx.conf.sigil` - The default path for this custom template is the root of your repo (i.e. `/app` in the container or `WORKDIR` if defined in a dockerfile app) - Dokku no longer looks for this file in `/home/dokku/myapp` on the dokku server - - Check out an example template [here](/dokku/nginx/) + - Check out an example template [here](/dokku/configuration/nginx/) - Support for server-wide SSL certs have been dropped in favor of using the `certs` plugin - `dokku certs:add myapp < certs.tar` - All domains for an SSL-enabled app will be redirected to https by default @@ -22,4 +22,4 @@ - Dockerfiles with `EXPOSE` clauses will get [all **tcp** ports proxied by default](/dokku/deployment/dockerfiles/#exposed-ports) - Note that nginx will proxy the same port numbers to listen publicly - - UDP ports can be exposed by disabling the [nginx proxy](/dokku/proxy/) with `dokku proxy:disable myapp` + - UDP ports can be exposed by disabling the [nginx proxy](/dokku/advanced-usage/proxy-management/) with `dokku proxy:disable myapp` diff --git a/docs/appendices/0.6.0-migration-guide.md b/docs/appendices/0.6.0-migration-guide.md index 6b69d87a9..e1c5b0272 100644 --- a/docs/appendices/0.6.0-migration-guide.md +++ b/docs/appendices/0.6.0-migration-guide.md @@ -7,26 +7,26 @@ - `DOKKU_CHECKS_ENABLED` has been migrated to `DOKKU_CHECKS_SKIPPED` - `DOKKU_CHECKS_DISABLED` is now a thing - The values for the above can be a comma-separated list of process-types or the literal string `_all_` - - See the [updated `checks`](/dokku/checks-examples/) docs for more info + - See the [updated `checks`](/dokku/deployment/zero-downtime-deploys/) docs for more info ## proxy port mapping - You can now configure host -> container proxy port mappings - - The UI is handled by the [proxy](/dokku/proxy/) interface plugin by setting the `DOKKU_PROXY_PORT_MAP` config variable in the format of `scheme:host-port:container-port`. The default `nginx-vhosts` proxy plugin supports both the `http` and `https` schemes. + - The UI is handled by the [proxy](/dokku/advanced-usage/proxy-management/) interface plugin by setting the `DOKKU_PROXY_PORT_MAP` config variable in the format of `scheme:host-port:container-port`. The default `nginx-vhosts` proxy plugin supports both the `http` and `https` schemes. - Default port mappings - buildpack apps will be set to `http:80:5000` and will also include `https:443:5000` if SSL is enabled. - dockerfile apps with explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on each exposed port that proxies to the same port of the deployed application container. - - You may override this behavior with the [`proxy:ports-*` commands](/dokku/proxy/) or by directly setting `DOKKU_PROXY_PORT_MAP` with the `config:set` command + - You may override this behavior with the [`proxy:ports-*` commands](/dokku/advanced-usage/proxy-management/) or by directly setting `DOKKU_PROXY_PORT_MAP` with the `config:set` command - dockerfile apps without explicitly exposed ports will behave the same as a buildpack app - NOTE: These defaults **are not** automatically changed on subsequent pushes and must be manipulated with the aforementioned commands ## calling the dokku binary - Plugins should *not* call the dokku binary directly. Clients using the `--app` argument are potentially broken, amongst others, when doing so. Instead, please source the `functions` file for a given plugin when attempting to call dokku internal functions. As a result, the following dokku commands are no longer publicly exposed: - - dokku build - - dokku receive - - dokku release - - dokku tar:build - - dokku tar:build-locked - - dokku git:build - - dokku git:build-locked + - `dokku build` + - `dokku receive` + - `dokku release` + - `dokku tar:build` + - `dokku tar:build-locked` + - `dokku git:build` + - `dokku git:build-locked` diff --git a/docs/assets/style.css b/docs/assets/style.css index 72c3c6083..ddbbb7127 100644 --- a/docs/assets/style.css +++ b/docs/assets/style.css @@ -282,6 +282,39 @@ a.list-group-item { .markdown-body h1 + h2 { margin-top: 1em; } +.highlight-show-language { + position: relative; +} +.highlight-show-language-label { + color: black; + background-color: #CFCFCF; + display: inline-block; + position: absolute; + bottom: auto; + left: auto; + top: 0; + right: 0; + width: auto; + height: auto; + font-size: 0.9em; + border-radius: 0 0 0 5px; + padding: 0 0.5em; + text-shadow: none; + z-index: 1; + -webkit-box-shadow: none; + -moz-box-shadow: none; + box-shadow: none; + -webkit-transform: none; + -moz-transform: none; + -ms-transform: none; + -o-transform: none; + transform: none; +} +.highlight-output pre { + color: #fff; + background-color: #000; + padding: 10px; +} code { padding: 0; padding-top: 0.2em; diff --git a/docs/backup-recovery.md b/docs/backup-recovery.md deleted file mode 100644 index 593068fc1..000000000 --- a/docs/backup-recovery.md +++ /dev/null @@ -1,45 +0,0 @@ -# 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. - -``` -$ 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] plugin, have built-in commands that allow non-volatile data be exported and imported. - -For [dokku-postgres], use: -``` -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] 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. - -``` -storage:list , List bind mounts for app's container(s) (host:container) -storage:mount , Create a new bind mount -storage:unmount , Remove an existing bind mount -``` - -## 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). - -``` -mkdir [app-name] ; cd !$ -git init && git remote add dokku dokku@[dokku.me:app-name] -git pull dokku/master && git checkout dokku/master -``` - -[dokku-postgres]: -[300mb]: diff --git a/docs/plugins.md b/docs/community/plugins.md similarity index 99% rename from docs/plugins.md rename to docs/community/plugins.md index 3158df591..be7f248ff 100644 --- a/docs/plugins.md +++ b/docs/community/plugins.md @@ -26,7 +26,7 @@ dokku plugins-install ## Creating your own plugin -[See the full documentation](/dokku/development/plugin-creation). +[See the full documentation](/dokku/development/plugin-creation/). ## Official Plugins (Beta) @@ -86,6 +86,8 @@ Note: The following plugins have been supplied by our community and may not have [hughfletcher]: https://github.com/hughfletcher [iamale]: https://github.com/iamale [ignlg]: https://github.com/ignlg +[iloveitaly]: https://github.com/iloveitaly +[investtools]: https://github.com/investtools [iskandar]: https://github.com/iskandar [jagandecapri]: https://github.com/jagandecapri [jeffutter]: https://github.com/jeffutter diff --git a/docs/components.md b/docs/components.md deleted file mode 100644 index 91ee33ecc..000000000 --- a/docs/components.md +++ /dev/null @@ -1,8 +0,0 @@ -# Components - - * [Docker](https://github.com/dotcloud/docker) - Container runtime and manager - * [Herokuish](https://github.com/gliderlabs/herokuish) - Buildpack builder - * [plugn](https://github.com/dokku/plugn) - Shell based plugins and hooks - * [sshcommand](https://github.com/dokku/sshcommand) - Fixed commands over SSH - -Looking to keep codebase as simple and hackable as possible, so try to keep your line count down. diff --git a/docs/dns.md b/docs/configuration/dns.md similarity index 97% rename from docs/dns.md rename to docs/configuration/dns.md index bcee9ddab..5cbbf612e 100644 --- a/docs/dns.md +++ b/docs/configuration/dns.md @@ -70,7 +70,7 @@ If everything is working correctly, you should also be able to query for any oth 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/dokku/dokku/blob/master/README.md) +Proceed with the setup instructions in the [installation documentation](/dokku/getting-started/installation/) #### Using the root of your domain (myapp.example.tld) diff --git a/docs/deployment/domain-configuration.md b/docs/configuration/domains.md similarity index 82% rename from docs/deployment/domain-configuration.md rename to docs/configuration/domains.md index 8669475bb..9c83b64c4 100644 --- a/docs/deployment/domain-configuration.md +++ b/docs/configuration/domains.md @@ -2,14 +2,14 @@ > New as of 0.3.10 -```shell -domains:add DOMAIN Add a domain to app -domains [] List domains -domains:clear Clear all domains for app -domains:disable Disable VHOST support -domains:enable Enable VHOST support -domains:remove DOMAIN Remove a domain from app -domains:set-global Set global domain name +``` +domains:add DOMAIN # Add a domain to app +domains [] # List domains +domains:clear # Clear all domains for app +domains:disable # Disable VHOST support +domains:enable # Enable VHOST support +domains:remove DOMAIN # Remove a domain from app +domains:set-global # Set global domain name ``` ## Customizing hostnames @@ -71,7 +71,7 @@ dokku domains:remove myapp example.com 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). -``` +```nginx server { listen 80 default_server; listen [::]:80 default_server; @@ -84,7 +84,7 @@ server { You may also wish to use a separate vhost in your `/etc/nginx/sites-enabled` directory. To do so, create the vhost in that directory as `/etc/nginx/sites-enabled/00-default.conf`. You will also need to change two lines in the main `nginx.conf`: -``` +```nginx # Swap both conf.d include line and the sites-enabled include line. From: include /etc/nginx/conf.d/*.conf; include /etc/nginx/sites-enabled/*; diff --git a/docs/configuration-management.md b/docs/configuration/environment-variables.md similarity index 100% rename from docs/configuration-management.md rename to docs/configuration/environment-variables.md diff --git a/docs/nginx.md b/docs/configuration/nginx.md similarity index 87% rename from docs/nginx.md rename to docs/configuration/nginx.md index 09d03c29c..2c4f441cd 100644 --- a/docs/nginx.md +++ b/docs/configuration/nginx.md @@ -3,9 +3,9 @@ Dokku uses nginx as its 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 [-t] Show the nginx access logs for an application (-t follows) -nginx:build-config (Re)builds nginx config for given app -nginx:error-logs [-t] Show the nginx error logs for an application (-t follows) +nginx:access-logs [-t] # Show the nginx access logs for an application (-t follows) +nginx:build-config # (Re)builds nginx config for given app +nginx:error-logs [-t] # Show the nginx error logs for an application (-t follows) ``` ## Customizing the nginx configuration @@ -24,7 +24,8 @@ Dokku uses a templating library by the name of [sigil](https://github.com/glider ### Example Custom Template Use case: add an `X-Served-By` header to requests -``` + +```go server { listen [::]:{{ .NGINX_PORT }}; listen {{ .NGINX_PORT }}; @@ -64,6 +65,7 @@ upstream {{ .APP }} { ``` ### Available template variables + ``` {{ .APP }} Application name {{ .APP_SSL_PATH }} Path to SSL certificate and key @@ -84,7 +86,8 @@ upstream {{ .APP }} { ### Example HTTP to HTTPS Custom Template Use case: a simple dockerfile app that includes `EXPOSE 80` -``` + +```go server { listen [::]:80; listen 80; @@ -130,7 +133,8 @@ upstream {{ .APP }} { ``` ### Example using new proxy port mapping -``` + +```go {{ range $port_map := .PROXY_PORT_MAP | split " " }} {{ $port_map_list := $port_map | split ":" }} {{ $scheme := index $port_map_list 0 }} @@ -181,7 +185,7 @@ upstream {{ $.APP }}-{{ $upstream_port }} { The default nginx.conf template will include everything from your apps `nginx.conf.d/` subdirectory in the main `server {}` block (see above): -``` +```go include {{ .DOKKU_ROOT }}/{{ .APP }}/nginx.conf.d/*.conf; ``` @@ -198,36 +202,36 @@ The example above uses additional configuration files directly on the dokku host ## Domains plugin -See the [domain-configuration documentation](/dokku/deployment/domain-configuration/). +See the [domain configuration documentation](/dokku/configuration/domains/). ## Customizing hostnames -See the [customizing hostnames documentation](/dokku/deployment/domain-configuration/#customizing-hostnames). +See the [customizing hostnames documentation](/dokku/configuration/domains/#customizing-hostnames). ## Disabling VHOSTS -See the [disabling vhosts documentation](/dokku/deployment/domain-configuration/#disabling-vhosts). +See the [disabling vhosts documentation](/dokku/configuration/domains/#disabling-vhosts). ## Default site -See the [default site documentation](/dokku/deployment/domain-configuration/#default-site). +See the [default site documentation](/dokku/configuration/domains/#default-site). ## Running behind a load balancer -See the [load balancer documentation](/dokku/deployment/ssl-configuration/#running-behind-a-load-balancer). +See the [load balancer documentation](/dokku/configuration/ssl/#running-behind-a-load-balancer). ## HSTS Header -See the [HSTS documentation](/dokku/deployment/ssl-configuration/#hsts-header). +See the [HSTS documentation](/dokku/configuration/ssl/#hsts-header). ## SSL Configuration -See the [ssl documentation](/dokku/deployment/ssl-configuration/). +See the [ssl documentation](/dokku/configuration/ssl/). ## Disabling Nginx -See the [proxy documentation](/dokku/proxy/). +See the [proxy documentation](/dokku/advanced-usage/proxy-management/). ## Managing Proxy Port mappings -See the [proxy documentation](/dokku/proxy/#proxy-port-mapping). +See the [proxy documentation](/dokku/advanced-usage/proxy-management/#proxy-port-mapping). diff --git a/docs/deployment/ssl-configuration.md b/docs/configuration/ssl.md similarity index 89% rename from docs/deployment/ssl-configuration.md rename to docs/configuration/ssl.md index adcd5b83d..9a5cfc18c 100644 --- a/docs/deployment/ssl-configuration.md +++ b/docs/configuration/ssl.md @@ -5,12 +5,14 @@ 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 CRT KEY Add an ssl endpoint to an app. Can also import from a tarball on stdin. -certs:generate DOMAIN Generate a key and certificate signing request (and self-signed certificate) -certs:info Show certificate information for an ssl endpoint. -certs:remove Remove an SSL Endpoint from an app. -certs:update CRT KEY Update an SSL Endpoint on an app. Can also import from a tarball on stdin +certs:add CRT KEY # Add an ssl endpoint to an app. Can also import from a tarball on stdin. +certs:generate DOMAIN # Generate a key and certificate signing request (and self-signed certificate) +certs:info # Show certificate information for an ssl endpoint. +certs:remove # Remove an SSL Endpoint from an app. +certs:update CRT KEY # Update an SSL Endpoint on an app. Can also import from a tarball on stdin +``` +```shell # for 0.3.x dokku nginx:import-ssl < certs.tar ``` @@ -37,9 +39,9 @@ cat yourdomain_com.crt yourdomain_com.ca-bundle > server.crt #### SSL and Multiple Domains -When an SSL certificate is associated to an application, the certificate will be associated with *all* domains currently associated with said application. Your certificate _should_ be associated with all of those domains, otherwise accessing the application will result in SSL errors. If you wish to remove one of the domains from the application, refer to the [domain configuration documentation](/dokku/deployment/domain-configuration/). +When an SSL certificate is associated to an application, the certificate will be associated with *all* domains currently associated with said application. Your certificate _should_ be associated with all of those domains, otherwise accessing the application will result in SSL errors. If you wish to remove one of the domains from the application, refer to the [domain configuration documentation](/dokku/configuration/domains/). -Note that with the default nginx template, requests will be redirected to the `https` version of the domain. If this is not the desired state of request resolution, you may customize the nginx template in use. For more details, see the [nginx documentation](/dokku/nginx/). +Note that with the default nginx template, requests will be redirected to the `https` version of the domain. If this is not the desired state of request resolution, you may customize the nginx template in use. For more details, see the [nginx documentation](/dokku/configuration/nginx/). ### Certificate generation @@ -53,8 +55,11 @@ If you decide to obtain a CA signed certficate, you can import that certificate The `certs:info` command will simply inspect the install SSL cert and print out details. NOTE: The server-wide certificate will be inspect if installed and no app-specific certificate exists. +```shell +dokku certs:info node-js-app +``` + ``` -$ dokku certs:info node-js-app -----> Fetching SSL Endpoint info for node-js-app... -----> Certificate details: =====> Common Name(s): @@ -81,9 +86,9 @@ Beware that if you enable the header and a subsequent deploy of your application Your application has access to the HTTP headers `X-Forwarded-Proto`, `X-Forwarded-For` and `X-Forwarded-Port`. These headers indicate the protocol of the original request (HTTP or HTTPS), the port number, and the IP address of the client making the request, respectively. The default configuration is for Nginx to set these headers. -If your server runs behind an HTTP/S load balancer, then Nginx will see all requests as coming from the load balancer. If your load balancer sets the `X-Forwarded-` headers, you can tell Nginx to pass these headers from load balancer to your application by using the following [nginx custom template](/dokku/nginx/#customizing-the-nginx-configuration) +If your server runs behind an HTTP/S load balancer, then Nginx will see all requests as coming from the load balancer. If your load balancer sets the `X-Forwarded-` headers, you can tell Nginx to pass these headers from load balancer to your application by using the following [nginx custom template](/dokku/configuration/nginx/#customizing-the-nginx-configuration) -```shell +```go server { listen [::]:{{ .NGINX_PORT }}; listen {{ .NGINX_PORT }}; diff --git a/docs/application-deployment.md b/docs/deployment/application-deployment.md similarity index 87% rename from docs/application-deployment.md rename to docs/deployment/application-deployment.md index 1e2d0a2e5..7babf2e8c 100644 --- a/docs/application-deployment.md +++ b/docs/deployment/application-deployment.md @@ -20,7 +20,7 @@ dokku apps:create ruby-rails-sample ### Create the backing services -When you create a new app, Dokku by default *does not* provide any datastores such as MySQL or PostgreSQL. You will need to install plugins to handle that, but fortunately [Dokku has official plugins](/dokku/plugins/#official-plugins-beta) for common datastores. Our sample app requires a PostgreSQL service: +When you create a new app, Dokku by default *does not* provide any datastores such as MySQL or PostgreSQL. You will need to install plugins to handle that, but fortunately [Dokku has official plugins](/dokku/community/plugins/#official-plugins-beta) for common datastores. Our sample app requires a PostgreSQL service: ```shell # on your dokku host @@ -56,8 +56,6 @@ git remote add dokku dokku@dokku.me:ruby-rails-sample git push dokku master ``` -You should see output similar to the following: - ``` Counting objects: 231, done. Delta compression using up to 8 threads. @@ -78,15 +76,13 @@ Total 231 (delta 93), reused 147 (delta 53) Using rake 10.4.2 ... -``` -When the deploy finishes, the application's URL will be shown. - -```shell =====> Application deployed: http://ruby-rails-sample.dokku.me ``` +When the deploy finishes, the application's URL will be shown as seen above. + Dokku supports deploying applications via [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) with [Herokuish](https://github.com/gliderlabs/herokuish#buildpacks) or using a project's [dockerfile](https://docs.docker.com/reference/builder/). ### Removing a deployed app @@ -152,28 +148,34 @@ Note that if the buildpack or dockerfile build process require ssh key access fo The name of remote repository is used as the name of application to be deployed, as for example above: - $ git remote add dokku dokku@dokku.me:ruby-rails-sample - $ git push dokku master +```shell +git remote add dokku dokku@dokku.me:ruby-rails-sample +git push dokku master +``` -Is deployed to, - - remote: -----> Application deployed: - remote: http://ruby-rails-sample.dokku.me +``` +remote: -----> Application deployed: +remote: http://ruby-rails-sample.dokku.me +``` You can also specify fully qualified names, say `app.dokku.me`, as - $ git remote add dokku dokku@dokku.me:app.dokku.me - $ git push dokku master +```shell +git remote add dokku dokku@dokku.me:app.dokku.me +git push dokku master +``` -So, after deployment the application will be available at, - - remote: -----> Application deployed: - remote: http://app.dokku.me +``` +remote: -----> Application deployed: +remote: http://app.dokku.me +``` This is in particular useful, then you want to deploy to root domain, as - $ git remote add dokku dokku@dokku.me:dokku.me - $ git push dokku master +```shell +git remote add dokku dokku@dokku.me:dokku.me +git push dokku master +``` ... deployment ... @@ -192,7 +194,7 @@ See the [user management documentation](/dokku/deployment/user-management). ## Default vhost -See the [nginx documentation](/dokku/nginx/#default-site). +See the [nginx documentation](/dokku/configuration/nginx/#default-site). ## Dockerfile deployment @@ -204,8 +206,8 @@ See the [buildpack documentation](/dokku/deployment/buildpacks/). ## Image tagging -See the [image tagging documentation](/dokku/deployment/images). +See the [image tagging documentation](/dokku/deployment/images/). ## Zero downtime deploy -See the [zero-downtime deploy documentation](/dokku/checks-examples/). +See the [zero-downtime deploy documentation](/dokku/deployment/zero-downtime-deploys/). diff --git a/docs/deployment/buildpacks.md b/docs/deployment/buildpacks.md index 50821523e..44130b2c3 100644 --- a/docs/deployment/buildpacks.md +++ b/docs/deployment/buildpacks.md @@ -4,7 +4,7 @@ Dokku normally defaults to using [heroku buildpacks](https://devcenter.heroku.co - Use `dokku config:set` to set the `BUILDPACK_URL` environment variable. - Add `BUILDPACK_URL` to a committed `.env` file in the root of your repository. - - See the [environment variable documentation](/dokku/configuration-management/) for more details. + - See the [environment variable documentation](/dokku/configuration/environment-variables/) for more details. - Create a `.buildpacks` file in the root of your repository. ## Specifying a custom buildpack @@ -59,7 +59,7 @@ dokku config:set APP BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-no ## Specifying commands via Procfile -While many buildpacks have a default command that is run when a detected repository is pushed, it is possible to override this command via a Procfile. A Procfile can also be used to specify multiple commands, each of which is subject to process scaling. See the [process scaling documentation](/dokku/process-management/) for more details around scaling individual processes. +While many buildpacks have a default command that is run when a detected repository is pushed, it is possible to override this command via a Procfile. A Procfile can also be used to specify multiple commands, each of which is subject to process scaling. See the [process scaling documentation](/dokku/deployment/process-management/) for more details around scaling individual processes. A Procfile is a file named `Procfile`. It should be named `Procfile` exactly, and not anything else. For example, `Procfile.txt` is not valid. The file should be a simple text file. @@ -75,12 +75,12 @@ The syntax for declaring a `Procfile` is as follows. Note that the format is one If, for example, you have multiple queue workers and wish to scale them separately, the following would be a valid way to work around the requirement of not duplicating process types: -``` +```Procfile worker: env QUEUE=* bundle exec rake resque:work importantworker: env QUEUE=important bundle exec rake resque:work ``` -The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/dokku/process-management/) for more details around scaling individual processes. +The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/dokku/deployment/process-management/) for more details around scaling individual processes. ## Clearing buildpack cache diff --git a/docs/deployment/dockerfiles.md b/docs/deployment/dockerfiles.md index 165b3931f..6cc58da2a 100644 --- a/docs/deployment/dockerfiles.md +++ b/docs/deployment/dockerfiles.md @@ -21,19 +21,19 @@ Dokku will extract all tcp ports exposed using the `EXPOSE` directive (one port If you do not explicitly `EXPOSE` a port in your `Dockerfile`, dokku will configure the nginx proxy to listen on port 80 (and 443 for TLS) and forward traffic to your app listening on port 5000 inside the container. Just like buildpack apps, you can also use the `$PORT` environment variable in your app to maintain portability. -When ports are exposed through the default nginx proxy, they are proxied externally as HTTP ports. At this time, in no case do we proxy plain TCP or UDP ports. If you'd like to investigate alternative proxy methods, please refer to our [proxy documentation](/dokku/proxy/). +When ports are exposed through the default nginx proxy, they are proxied externally as HTTP ports. At this time, in no case do we proxy plain TCP or UDP ports. If you'd like to investigate alternative proxy methods, please refer to our [proxy management documentation](/dokku/advanced-usage/proxy-management/). ## Customizing the run command By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker ability of overriding the `CMD` or passing parameters to your `ENTRYPOINT` setting `$DOKKU_DOCKERFILE_START_CMD`. Let's say for example you are deploying a base nodejs image, with the following `ENTRYPOINT`: -``` +```Dockerfile ENTRYPOINT ["node"] ``` You can do: -``` +```shell dokku config:set APP DOKKU_DOCKERFILE_START_CMD="--harmony server.js" ``` @@ -52,14 +52,14 @@ When you deploy your app a Docker image will be built, the `Procfile` will be ex (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`: -``` +```Procfile web: bin/run-prod.sh worker: bin/run-worker.sh ``` And `Dockerfile`: -``` +```Dockerfile FROM debian:jessie WORKDIR /app COPY . ./ diff --git a/docs/deployment/images.md b/docs/deployment/images.md index 47c5de0c3..6bd3d4b8c 100644 --- a/docs/deployment/images.md +++ b/docs/deployment/images.md @@ -5,35 +5,59 @@ The dokku tags plugin allows you to add docker image tags to the currently deployed app image for versioning and subsequent deployment. ``` -tags List all app image tags -tags:create Add tag to latest running app image -tags:deploy Deploy tagged app image -tags:destroy Remove app image tag +tags # List all app image tags +tags:create # Add tag to latest running app image +tags:deploy # Deploy tagged app image +tags:destroy # Remove app image tag ``` -Example: +For exampple, you can list all tags for a given application: + +```shell +dokku tags node-js-app +``` ``` -$ dokku tags node-js-app =====> Image tags for dokku/node-js-app REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE dokku/node-js-app latest 936a42f25901 About a minute ago 1.025 GB +``` -$ dokku tags:create node-js-app v0.9.0 -=====> Added v0.9.0 tag to dokku/node-js-app +You can also create new tags for that app using the `tags:create` function. Tags should conform to the docker tagging specification for your docker version. As of 1.10, that specification is available [here](https://github.com/docker/docker/blob/master/image/spec/v1.1.md), while users of older versions can check the documentation [here](https://github.com/docker/docker/blob/master/image/spec/v1.md). -$ dokku tags node-js-app +```shell +dokku tags:create node-js-app v1 +``` + +``` +=====> Added v1 tag to dokku/node-js-app +``` + +Once the tag is created, you can see the output by running the `tags` command again. + +```shell +dokku tags node-js-app +``` + +``` =====> Image tags for dokku/node-js-app REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE dokku/node-js-app latest 936a42f25901 About a minute ago 1.025 GB -dokku/node-js-app v0.9.0 936a42f25901 About a minute ago 1.025 GB +dokku/node-js-app v1 936a42f25901 About a minute ago 1.025 GB +``` -$ dokku tags:deploy node-js-app v0.9.0 ------> Releasing node-js-app (dokku/node-js-app:v0.9.0)... ------> Deploying node-js-app (dokku/node-js-app:v0.9.0)... +Finally, you can also deploy a local image using the `tags:deploy` command. + +```shell +dokku tags:deploy node-js-app v1 +``` + +``` +-----> Releasing node-js-app (dokku/node-js-app:v1)... +-----> Deploying node-js-app (dokku/node-js-app:v1)... -----> Running pre-flight checks For more efficient zero downtime deployments, create a file CHECKS. - See http://dokku.viewdocs.io/dokku/checks-examples.md for examples + See http://dokku.viewdocs.io/dokku/deployment/zero-downtime-deploys/ for examples CHECKS file not found in container: Running simple container check... -----> Waiting for 10 seconds ... -----> Default container check successful! @@ -53,7 +77,6 @@ $ dokku tags:deploy node-js-app v0.9.0 =====> 025eec3fa3b442fded90933d58d8ed8422901f0449f5ea0c23d00515af5d3137 =====> Application deployed: http://node-js-app.dokku.me - ``` ## Deploying from a Docker Registry diff --git a/docs/deployment/one-off-processes.md b/docs/deployment/one-off-processes.md index 1e622be63..dac0cedc0 100644 --- a/docs/deployment/one-off-processes.md +++ b/docs/deployment/one-off-processes.md @@ -95,7 +95,7 @@ dokku enter node-js-app web python script/background-worker.py Your procfile can have the following entry: -``` +```Procfile cron: sleep infinity ``` @@ -138,7 +138,7 @@ Regularly scheduled tasks can be a bit of a pain with dokku. The following are g The following is a sample cronfile that you can use for your applications: -``` +```cron # server cron jobs MAILTO="mail@example.com" PATH=/usr/local/bin:/usr/bin:/bin diff --git a/docs/process-management.md b/docs/deployment/process-management.md similarity index 74% rename from docs/process-management.md rename to docs/deployment/process-management.md index 120a7269f..51e477f4a 100644 --- a/docs/process-management.md +++ b/docs/deployment/process-management.md @@ -5,14 +5,14 @@ Dokku supports rudimentary process (really container) management via the `ps` plugin. ``` -ps List processes running in app container(s) -ps:rebuildall Rebuild all apps -ps:rebuild Rebuild an app -ps:restartall Restart all deployed app containers -ps:restart Restart app container(s) -ps:scale = [=] Set how many processes of a given process to run -ps:start Start app container(s) -ps:stop Stop app container(s) +ps # List processes running in app container(s) +ps:rebuildall # Rebuild all apps +ps:rebuild # Rebuild an app +ps:restartall # Restart all deployed app containers +ps:restart # Restart app container(s) +ps:scale = [=] # Set how many processes of a given process to run +ps:start # Start app container(s) +ps:stop # Stop app container(s) ``` ## Scaling @@ -24,7 +24,8 @@ Dokku allows you to run multiple process types at different container counts. Fo You can optionally create a `DOKKU_SCALE` file in the root of your repository. Dokku expects this file to contain one line for every process defined in your Procfile. Example: -``` + +```Procfile web=1 worker=2 ``` @@ -33,7 +34,7 @@ worker=2 Dokku can also manage scaling itself via the `ps:scale` command. This command can be used to scale multiple process types at the same time. -``` +```shell dokku ps:scale app_name web=1 worker=2 ``` diff --git a/docs/remote-commands.md b/docs/deployment/remote-commands.md similarity index 97% rename from docs/remote-commands.md rename to docs/deployment/remote-commands.md index f13c94535..18a63f81c 100644 --- a/docs/remote-commands.md +++ b/docs/deployment/remote-commands.md @@ -4,9 +4,9 @@ Dokku commands can be run over ssh. Anywhere you would run `dokku `, ju 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: -``` +```ini Host dokku.me -RequestTTY yes + RequestTTY yes ``` ## Behavioral modifiers @@ -14,7 +14,7 @@ RequestTTY yes Dokku also supports certain command-line arguments that augment it's behavior. If using these over ssh, you must use the form `ssh -t dokku@dokku.me -- ` in order to avoid ssh interpretting dokku arguments for itself. -```shell +``` --quiet suppress output headers --trace enable DOKKU_TRACE for current execution only --rm|--rm-container remove docker container after successful dokku run diff --git a/docs/deployment/user-management.md b/docs/deployment/user-management.md index c6c7f3b1e..0c6cd4eb1 100644 --- a/docs/deployment/user-management.md +++ b/docs/deployment/user-management.md @@ -33,13 +33,13 @@ At it's base, the `sshcommand` *must* be run under a user with sudo access, as i For instance, if you stored your public key at `~/.ssh/id_rsa.pub-open` and are deploying to EC2 where the default root-enabled user is `ubuntu`, you can run the following command to add your key under the `superuser` username: -``` +```shell cat ~/.ssh/id_rsa.pub-open | ssh ubuntu@dokku.me "sudo sshcommand acl-add dokku superuser" ``` If you are using the vagrant installation, you can also use the `make vagrant-acl-add` target to add your public key to dokku (it will use your host username as the `USER`): -``` +```shell cat ~/.ssh/id_rsa.pub | make vagrant-acl-add ``` diff --git a/docs/checks-examples.md b/docs/deployment/zero-downtime-deploys.md similarity index 89% rename from docs/checks-examples.md rename to docs/deployment/zero-downtime-deploys.md index c448a9224..9d97385eb 100644 --- a/docs/checks-examples.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -3,41 +3,44 @@ > New as of 0.5.0 ``` -checks Show zero-downtime status -checks:disable [process-type(s)] Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments*** -checks:enable [process-type(s)] Enable zero-downtime deployment for all processes (or comma-separated process-type list) -checks:skip [process-type(s)] Skip zero-downtime checks for all processes (or comma-separated process-type list) +checks # Show zero-downtime status +checks:disable [process-type(s)] # Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments*** +checks:enable [process-type(s)] # Enable zero-downtime deployment for all processes (or comma-separated process-type list) +checks:skip [process-type(s)] # Skip zero-downtime checks for all processes (or comma-separated process-type list) ``` Following a deploy, dokku will wait `10` seconds before routing traffic to the new container to give your application time to boot up. If the application is not running after this time, then the deploy is failed and your old container will continue serving traffic. You can modify this value globally or on a per-application basis: ```shell dokku config:set --global DOKKU_DEFAULT_CHECKS_WAIT=30 -dokku config:set DOKKU_DEFAULT_CHECKS_WAIT=30 +dokku config:set node-js-app DOKKU_DEFAULT_CHECKS_WAIT=30 ``` -You can also choose to skip checks or disable zero-downtime completely on a per-application/per-process basis: +You can also choose to skip checks or disable zero-downtime completely on a per-application/per-process basis -```shell -dokku checks:skip worker,web -``` - -```shell -dokku checks:disable worker,web -``` > Note that `checks:disable` will now (as of 0.6.0) cause downtime for that process-type during deployments. -Additionally, any given process can only be configured to skip OR disable zero-downtime. example: - ```shell -$ dokku checks:skip testapp worker,web ------> Skipping zero downtime for app's (testapp) proctypes (worker,web) ------> Unsetting testapp +dokku checks:skip node-js-app worker,web +``` + +``` +-----> Skipping zero downtime for app's (node-js-app) proctypes (worker,web) +-----> Unsetting node-js-app -----> Unsetting DOKKU_CHECKS_DISABLED -----> Setting config vars DOKKU_CHECKS_SKIPPED: worker,web -$ dokku checks:disable testapp worker ------> Disabling zero downtime for app's (testapp) proctypes (worker) +``` + +Additionally, any given process can only be configured to disable zero-downtime. example: + + +```shell +dokku checks:disable node-js-app worker +``` + +``` +-----> Disabling zero downtime for app's (node-js-app) proctypes (worker) -----> Setting config vars DOKKU_CHECKS_DISABLED: worker -----> Setting config vars @@ -61,10 +64,10 @@ Checks are run against the detected `web` process from your application's `Procf To specify checks, add a `CHECKS` file to the root of your project directory. The `CHECKS` file should be plain text and may contain: - * Check instructions - * Settings (NAME=VALUE) - * Comments (lines starting with #) - * Empty lines +* Check instructions +* Settings (NAME=VALUE) +* 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. @@ -127,31 +130,41 @@ If your application runs multiple processes (a background worker configured in y dokku config:set DOKKU_DEFAULT_CHECKS_WAIT=0 ``` +### Configuring docker stop timeout + +[By default](https://docs.docker.com/engine/reference/commandline/stop/), docker will wait 10 seconds from the time the `stop` command is passed to a container before it attempts to kill said container. This timeout can be configured on a per-app basis in dokku by setting the `DOKKU_DOCKER_STOP_TIMEOUT` configuration variable. This timeout applies to normal zero-downtime deployments as well as the `ps:stop` and `apps:destroy` commands. + +```shell +dokku config:set $APP DOKKU_DOCKER_STOP_TIMEOUT=20 +``` + ## Example: Successful Rails Deployment In this example, a Rails application is successfully deployed to dokku. The initial round of checks fails while the server is starting, but once it starts they succeed and the deployment is successful. `WAIT` is set to `10` because our application takes a while to boot up. `ATTEMPTS` is set to `6`, but the third attempt succeeds. ### CHECKS file -```` +``` WAIT=10 ATTEMPTS=6 /check.txt simple_check -```` +``` For this check to work, we've added a line to `config/routes.rb` that simply returns a string: -```` +``` get '/check.txt', to: proc {[200, {}, ['simple_check']]} -```` +``` ### Deploy Output > Note: The output has been trimmed for brevity -```` +```shell git push dokku master +``` +``` -----> Cleaning up... -----> Building myapp from herokuish... -----> Adding BUILD_ENV to build environment... @@ -199,7 +212,7 @@ curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused -----> Shutting down old container in 60 seconds =====> Application deployed: http://myapp.dokku.example.com -```` +``` ## Example: Failing Rails Deployment @@ -209,11 +222,11 @@ Once the attempts have been exceeded, the deployment fails and we see the contai ### CHECKS file -```` +``` WAIT=10 ATTEMPTS=6 / -```` +``` > The check to the root url '/' would normally access the database. @@ -221,9 +234,11 @@ ATTEMPTS=6 > Note: The output has been trimmed for brevity -```` +```shell git push dokku master +``` +``` -----> Cleaning up... -----> Building myapp from herokuish... -----> Adding BUILD_ENV to build environment... @@ -301,11 +316,4 @@ Could not start due to 1 failed checks. To dokku@dokku.example.com:myapp ! [remote rejected] dokku -> master (pre-receive hook declined) error: failed to push some refs to 'dokku@dokku.example.com:myapp' -```` - -### Configuring docker stop timeout - -[By default](https://docs.docker.com/engine/reference/commandline/stop/), docker will wait 10 seconds from the time the `stop` command is passed to a container before it attempts to kill said container. This timeout can be configured on a per-app basis in dokku by setting the `DOKKU_DOCKER_STOP_TIMEOUT` configuration variable. This timeout applies to normal zero-downtime deployments as well as the `ps:stop` and `apps:destroy` commands. -``` -$ dokku config:set $APP DOKKU_DOCKER_STOP_TIMEOUT=20 ``` diff --git a/docs/development/plugin-creation.md b/docs/development/plugin-creation.md index 26c717f70..c37b73aba 100644 --- a/docs/development/plugin-creation.md +++ b/docs/development/plugin-creation.md @@ -5,7 +5,7 @@ If you create your own plugin: 1. Take a look at the plugins shipped with dokku and hack away! 2. Check out the [list of triggers](/dokku/development/plugin-triggers) your plugin can implement. 3. Upload your plugin to github with a repository name in form of `dokku-` (e.g. `dokku-mariadb`) -4. Edit [this page](/dokku/plugins) and add a link to it. +4. Edit [this page](/dokku/community/plugins/) and add a link to it. 5. Subscribe to the [dokku development blog](http://progrium.com) to be notified about API changes and releases @@ -110,7 +110,7 @@ esac Each plugin requires a `plugin.toml` descriptor file with the following required fields: -```shell +```toml [plugin] description = "dokku hello plugin" version = "0.1.0" diff --git a/docs/development/testing.md b/docs/development/testing.md index db2638492..b694e2daf 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -18,15 +18,22 @@ Example apps can be found here: - Test setup and execution ```shell - $ vagrant ssh - $ sudo su - - $ cd ~/dokku - $ make ci-dependencies setup-deploy-tests - $ make test # execute the entire test suite (linter, bats tests, and app deployment tests) - $ - $ make lint copyfiles # run linter & update vagrant dokku install from local git clone - $ make unit-tests # execute all bats tests - $ make deploy-tests # execute all app deployment tests + vagrant ssh + sudo su - + cd ~/dokku + make ci-dependencies setup-deploy-tests + + # execute the entire test suite (linter, bats tests, and app deployment tests) + make test + + # run linter & update vagrant dokku install from local git clone + make lint copyfiles + + # execute all bats tests + make unit-tests + + # execute all app deployment tests + make deploy-tests ``` - Additionally you may run a specific app deployment tests with a target similar to: diff --git a/docs/advanced-installation.md b/docs/getting-started/advanced-installation.md similarity index 98% rename from docs/advanced-installation.md rename to docs/getting-started/advanced-installation.md index 601f863d0..97e66db60 100644 --- a/docs/advanced-installation.md +++ b/docs/getting-started/advanced-installation.md @@ -52,7 +52,7 @@ Once dokku is installed, if you are not using the web-installer, you'll want to 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). -Follow the [user management documentation](/dokku/deployment/user-management) in order to add users to dokku. +Follow the [user management documentation](/dokku/deployment/user-management/) in order to add users to dokku. That's it! diff --git a/docs/getting-started/install/linode.md b/docs/getting-started/install/linode.md index 38d1d8933..f63ce5d10 100644 --- a/docs/getting-started/install/linode.md +++ b/docs/getting-started/install/linode.md @@ -24,9 +24,11 @@ __Warning__: These steps will delete *everything* on your Linode. 5. SSH into your Linode as root and run the following commands: - apt-get update - apt-get -qq upgrade - apt-get -qq install linux-image-virtual linux-image-extra-virtual + ```shell + apt-get update + apt-get -qq upgrade + apt-get -qq install linux-image-virtual linux-image-extra-virtual + ``` 6. When prompted, install Grub onto the first hard drive. @@ -36,4 +38,4 @@ __Warning__: These steps will delete *everything* on your Linode. 9. Lastly, reboot the Linode. -Once your server comes back online, you'll be running Ubuntu's default kernel. You can now follow Dokku's [normal installation instructions](/dokku/installation) and `bootstrap.sh` will take care of everything else. +Once your server comes back online, you'll be running Ubuntu's default kernel. You can now follow Dokku's [normal installation instructions](/dokku/getting-started/installation/) and `bootstrap.sh` will take care of everything else. diff --git a/docs/getting-started/install/vagrant.md b/docs/getting-started/install/vagrant.md index 3fb497105..d6116be84 100644 --- a/docs/getting-started/install/vagrant.md +++ b/docs/getting-started/install/vagrant.md @@ -4,12 +4,13 @@ - Download and install [Vagrant](http://www.vagrantup.com/downloads.html) - Clone Dokku - ``` + ```shell git clone https://github.com/dokku/dokku.git ``` - Create VM - ``` + + ```shell # Optional ENV arguments: # - `BOX_NAME` # - `BOX_URI` @@ -22,7 +23,7 @@ ``` - Setup SSH Config in `~/.ssh/config`. The port listed here is usually correct, though you may want to verify that it is the same as the one listed in the output of `vagrant ssh-config dokku` - ``` + ```ini Host dokku.me Port 22 ``` diff --git a/docs/installation.md b/docs/getting-started/installation.md similarity index 92% rename from docs/installation.md rename to docs/getting-started/installation.md index b67ecb1cc..4020fa6bd 100644 --- a/docs/installation.md +++ b/docs/getting-started/installation.md @@ -46,11 +46,11 @@ For various reasons, certain hosting providers may have other steps that should As well, you may wish to customize your installation in some other fashion. or experiment with vagrant. The guides below should get you started: -- [Debian Package Installation Notes](/dokku/getting-started/install/debian) -- [Vagrant Installation Notes](/dokku/getting-started/install/vagrant) -- [Advanced Install Customization](/dokku/advanced-installation) +- [Debian Package Installation Notes](/dokku/getting-started/install/debian/) +- [Vagrant Installation Notes](/dokku/getting-started/install/vagrant/) +- [Advanced Install Customization](/dokku/getting-started/advanced-installation/) --- - [1]: To check whether your system has an fqdn set, run `sudo hostname -f` -- [2]: If your system has less than 1GB of memory, you can use [this workaround](/dokku/advanced-installation/#vms-with-less-than-1gb-of-memory). +- [2]: If your system has less than 1GB of memory, you can use [this workaround](/dokku/getting-started/advanced-installation/#vms-with-less-than-1gb-of-memory). diff --git a/docs/troubleshooting.md b/docs/getting-started/troubleshooting.md similarity index 79% rename from docs/troubleshooting.md rename to docs/getting-started/troubleshooting.md index 5a6da26c6..767ff2cb6 100644 --- a/docs/troubleshooting.md +++ b/docs/getting-started/troubleshooting.md @@ -6,14 +6,14 @@ __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: -``` -$ nginx -t -nginx: [emerg] could not build the server_names_hash, you should increase server_names_hash_bucket_size: 32 +```shell +nginx -t +## 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: -``` +```nginx http { (... existing content ...) server_names_hash_bucket_size 64; @@ -26,11 +26,11 @@ A value of 64 would allow domains with up to 64 characters. Set it to 128 if you Save the file and try stopping nginx and starting it again: -``` -$ /etc/init.d/nginx stop - * Stopping nginx nginx [ OK ] -$ /etc/init.d/nginx start - * Starting nginx nginx [ OK ] +```shell +/etc/init.d/nginx stop +## * Stopping nginx nginx [ OK ] +/etc/init.d/nginx start +## * Starting nginx nginx [ OK ] ``` *** @@ -45,12 +45,16 @@ The `remote rejected` error does not give enough information. Anything could hav To enable dokku tracing, simply run the following command: - # Since 0.3.9 - dokku trace on +```shell +# since 0.3.9 +dokku trace on +``` In versions older than 0.3.9, you can create a `/home/dokku/dokkurc` file containing the following : - export DOKKU_TRACE=1 +```shell +export DOKKU_TRACE=1 +``` This will trace all of dokku's activity. If this does not help you, create a [gist](https://gist.github.com) containing the full log, and create an issue. @@ -64,28 +68,28 @@ __Solution (Less solution, more helpful troubleshooting steps):__ Find the failed phase's container image (*077581956a92* in this example) - ``` - $ docker ps -a | grep build - 94d9515e6d93 077581956a92 "/build" 29 minutes ago Exited (0) 25 minutes ago cocky_bell - ``` +```shell +docker ps -a | grep build +## 94d9515e6d93 077581956a92 "/build" 29 minutes ago Exited (0) 25 minutes ago cocky_bell +``` Start a new container with the failed image and poke around (i.e. ensure you can access the internet from within the container or attempt the failed command, if known) - ``` - $ docker run -ti 077581956a92 /bin/bash - root@9763ab86e1b4:/# curl -s -S icanhazip.com - 192.168.0.1 - curl http://s3pository.heroku.com/node/v0.10.30/node-v0.10.30-linux-x64.tar.gz -o node-v0.10.30-linux-x64.tar.gz - tar tzf node-v0.10.30-linux-x64.tar.gz - ... - ``` +```shell +docker run -ti 077581956a92 /bin/bash +curl -s -S icanhazip.com +## 192.168.0.1 +curl http://s3pository.heroku.com/node/v0.10.30/node-v0.10.30-linux-x64.tar.gz -o node-v0.10.30-linux-x64.tar.gz +tar tzf node-v0.10.30-linux-x64.tar.gz +## ... +``` Sometimes (especially on DO) deploying again seems to get past these seemingly transient issues Additionally we've seen issues if changing networks that have different DNS resolvers. In this case, you can run the following to update your resolv.conf - ``` - $ resolvconf -u - ``` +```shell +resolvconf -u +``` Please see https://github.com/dokku/dokku/issues/841 and https://github.com/dokku/dokku/issues/649 @@ -102,8 +106,10 @@ You get asked for a password because your ssh secret key can't be found. This ma 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" +```ini +Host DOKKU_HOSTNAME + IdentityFile "~/.ssh/KEYNAME" +``` Also see [issue #116](https://github.com/dokku/dokku/issues/116) @@ -117,7 +123,9 @@ In many cases the application will require the a `process.env.PORT` port opposed When specifying your port you may want to use something similar to: - var port = process.env.PORT || 3000 +```javascript +var port = process.env.PORT || 3000 +``` Please see https://github.com/dokku/dokku/issues/282 @@ -145,6 +153,4 @@ dokku config:set --global CURL_TIMEOUT=600 dokku config:set --global CURL_CONNECT_TIMEOUT=30 ``` -References -* https://github.com/dokku/dokku/issues/509 -* https://github.com/dokku-alt/dokku-alt/issues/169 +Please see https://github.com/dokku/dokku/issues/509 diff --git a/docs/upgrading.md b/docs/getting-started/upgrading.md similarity index 93% rename from docs/upgrading.md rename to docs/getting-started/upgrading.md index b0c140a52..08745c84f 100644 --- a/docs/upgrading.md +++ b/docs/getting-started/upgrading.md @@ -1,6 +1,6 @@ # Upgrading -If your version of dokku is pre 0.3.0 (check with `dokku version`), we recommend [a fresh install](/dokku/installation) on a new server. +If your version of dokku is pre 0.3.0 (check with `dokku version`), we recommend [a fresh install](/dokku/getting-started/installation/) on a new server. ## Migration Guides diff --git a/docs/getting-started/where-to-get-help.md b/docs/getting-started/where-to-get-help.md index ce9ab1490..b0f6fb591 100644 --- a/docs/getting-started/where-to-get-help.md +++ b/docs/getting-started/where-to-get-help.md @@ -4,7 +4,7 @@ If you’re stuck, there are a number of places you can get help: ## The Official Dokku Website -[http://dokku.viewdocs.io/dokku](/dokku) +- [http://dokku.viewdocs.io/dokku/](/dokku/) The Official Dokku website is always a great place to visit. It features links to oft-used developer tools, community plugins, and guides on using dokku. @@ -17,6 +17,6 @@ If you’re stumped, give us a holler in the Dokku IRC or Slack channels. Someon ## Stack Overflow -http://stackoverflow.com/ +- [https://stackoverflow.com/questions/tagged/dokku](https://stackoverflow.com/questions/tagged/dokku) Tag your questions with `dokku` to enable existing users of Stack Overflow to find your questions. diff --git a/docs/home.html b/docs/home.html index f224a6d25..1ce1ba483 100644 --- a/docs/home.html +++ b/docs/home.html @@ -44,7 +44,7 @@

- Dokku + Dokku

diff --git a/docs/template.html b/docs/template.html index 9623772ad..652d3b51b 100644 --- a/docs/template.html +++ b/docs/template.html @@ -47,6 +47,39 @@ @@ -58,7 +91,7 @@

- Dokku + Dokku

@@ -172,6 +205,35 @@