diff --git a/docs/application-deployment.md b/docs/application-deployment.md index 61268bfabc9..02f55450e56 100644 --- a/docs/application-deployment.md +++ b/docs/application-deployment.md @@ -1,105 +1,158 @@ -# Deploy an App +# Deploying to Dokku -Now you can deploy apps on your Dokku. Let's deploy the [Heroku Node.js sample app](https://github.com/heroku/node-js-sample). All you have to do is add a remote to name the app. It's created on-the-fly. +## Deploy tutorial -``` -$ cd node-js-sample -$ git remote add dokku dokku@dokku.me:node-js-app -$ git push dokku master -Counting objects: 296, done. -Delta compression using up to 4 threads. -Compressing objects: 100% (254/254), done. -Writing objects: 100% (296/296), 193.59 KiB, done. -Total 296 (delta 25), reused 276 (delta 13) ------> Building node-js-app ... - Node.js app detected ------> Resolving engine versions - -... blah blah blah ... - ------> Application deployed: - http://node-js-app.dokku.me +Once dokku has been configured with at least one user, applications can be deployed via a `git push` command. To quickly see dokku deployment in action, you can use the heroku Ruby on Rails example app. + +```shell +git clone git@github.com:heroku/ruby-rails-sample.git ``` -You're done! +### Create the app -Dokku only supports deploying from its master branch, so if you'd like to deploy a different local branch use: ```git push dokku :master``` +Create the application on the dokku host. You will need to ssh onto the host to run this command. -Right now Herokuish supports buildpacks for Node.js, Ruby, Python, [and more](https://github.com/gliderlabs/herokuish#buildpacks). -Please check the documentation for your particular build pack as you may need to include configuration files (such as a Procfile) in your project root. +```shell +dokku apps:create ruby-rails-sample +``` -## Deploying to server over SSH +### Create the backing services -Pushing to the dokku remote may prompt you to input a password for the dokku user. It's preferable, however, to use key-based authentication, and you can add your public key to the dokku user's authorized_keys file with: +When you create a new app, Dokku by default *does not* provide any datastores such as mysql or postgres. 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 Postgres service: +```shell +# install the postgres plugin +# plugin installation requires root, hence the user change +sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git + +# create a postgres service with the name rails-database +dokku postgres:create rails-database ``` -cat ~/.ssh/id_rsa.pub | ssh [sudouser]@[yourdomain].com "sudo sshcommand acl-add dokku [description]" + +> Each services may take a few moments to create. + +### Linking backing services to applications + +Once the service creation is complete, set the `POSTGRES_URL` environment variable by linking the service. + +```shell +# each official datastore offers a `link` method to link a service to any application +dokku postgres:link rails-database ruby-rails-sample ``` -## Deploying with private git submodules +> You can link a single service to multiple applications or use one service per application. + +### Deploy the app -Dokku uses git locally (i.e. not a docker image) to build its own copy of your app repo, including submodules. This is done as the `dokku` user. Therefore, in order to deploy private git submodules, you'll need to drop your deploy key in `~dokku/.ssh` and potentially add github.com (or your VCS host key) into `~dokku/.ssh/known_hosts`. A decent test like this should help confirm you've done it correctly. +Now you can deploy the `ruby-rails-sample` app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the dokku server. +```shell +git remote add dokku dokku@dokku.me:ruby-rails-sample +git push dokku master ``` -su - dokku -ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts -ssh -T git@github.com + +You should see output similar to the following: + ``` +Counting objects: 231, done. +Delta compression using up to 8 threads. +Compressing objects: 100% (162/162), done. +Writing objects: 100% (231/231), 36.96 KiB | 0 bytes/s, done. +Total 231 (delta 93), reused 147 (delta 53) +-----> Cleaning up... +-----> Building ruby-rails-sample from herokuish... +-----> Adding BUILD_ENV to build environment... +-----> Ruby app detected +-----> Compiling Ruby/Rails +-----> Using Ruby version: ruby-2.2.1 +-----> Installing dependencies using 1.9.7 + Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment + Fetching gem metadata from https://rubygems.org/........... + Fetching version metadata from https://rubygems.org/... + Fetching dependency metadata from https://rubygems.org/.. + Using rake 10.4.2 -## Specifying a custom buildpack +... +``` -If buildpack detection isn't working well for you or you want to specify a custom buildpack for one repository you can create & commit a file in the root of your git repository named `.env` containing `export BUILDPACK_URL=` before pushing. This will tell herokuish to fetch the specified buildpack and use it instead of relying on the built-in buildpacks & their detection methods. +When the deploy finishes, the application's url will be shown. -## Dockerfile deployment +```shell +=====> Application deployed: + http://ruby-rails-sample.dokku.me +``` -Deployment of `Dockerfile` repos is supported as of v0.3.15. Simply place a Dockerfile in the root of your repo and push to dokku. If you are converting from a heroku/dokku buildpack deployment, ensure you are not setting `$BUILDPACK_URL` or including a `.buildpacks` file in the root of your repo. +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/). -By default, we will extract the first `EXPOSE` port and tell nginx to proxy your app to that port. Alternatively, you can set `$DOKKU_DOCKERFILE_PORT` in your app's dokku configuration. +### Removing a deployed app -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`: +You can also remove an application from your dokku installation. This will unlink all linked services and destroy any config related to the application. Note that linked services will retain their data for later use (or removal). -``` -ENTRYPOINT ["node"] +```shell +# replace APP with the name of your application +dokku apps:destroy APP ``` -You can do: +This will prompt you to verify the application's name before destroying it. You may also use the `--force` flag to circumvent this verification process: +```shell +# replace APP with the name of your application +dokku --force apps:destroy APP ``` -dokku config:set DOKKU_DOCKERFILE_START_CMD="--harmony server.js" + +### Adding deploy users + +While it is possible to use password-based authorization to push to dokku, it is preferable to use key-based authentication for security. You can add your public key to the dokku user's `authorized_keys` file with the following command: + +```shell +# replace dokku.me with your domain name or the host's IP +# replace root with your server's root user +cat ~/.ssh/id_rsa.pub | ssh root@dokku.com "sudo sshcommand acl-add dokku [description]" ``` -To tell docker what to run. +### Deploying non-master branch -Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disable docker's image layer cache. Lastly, for more granular build control, you may also pass any `docker build` option to `docker`, by setting `$DOKKU_DOCKER_BUILD_OPTS`. +Dokku only supports deploying from its master branch, so if you'd like to deploy a different local branch use: ```git push dokku :master``` -## Default vhost +You can also support pushing multiple branches using the [receive-branch](/dokku/development/plugin-triggers/#receive-branch) plugin trigger in a custom plugin. -You might notice the default vhost for Nginx will be one of the apps. If an app doesn't exist, it will use this vhost and it may be confusing for it to go to another app. You can create a default vhost using a configuration under `sites-enabled`. You just have to change one thing in the main nginx.conf: +### Deploying with private git submodules -Swap both conf.d include line and the sites-enabled include line. From: -``` -include /etc/nginx/conf.d/*.conf; -include /etc/nginx/sites-enabled/*; -``` -to +Dokku uses git locally (i.e. not a docker image) to build its own copy of your app repo, including submodules. This is done as the `dokku` user. Therefore, in order to deploy private git submodules, you'll need to drop your deploy key in `/home/dokku/.ssh` and potentially add github.com (or your VCS host key) into `/home/dokku/.ssh/known_hosts`. The following test should help confirm you've done it correctly. + +```shell +su - dokku +ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts +ssh -T git@github.com ``` -include /etc/nginx/sites-enabled/*; -include /etc/nginx/conf.d/*.conf; + +Note that if the buildpack or dockerfile build process require ssh key access for other reasons, the above may not always apply. + +### Specifying a custom buildpack + +In certain cases you may want to specify a custom buildpack. While dokku uses herokuish to support all the [official heroku buildpacks](https://github.com/gliderlabs/herokuish#buildpacks), it is possible that the buildpack detection does not work well for your application. As well, you may wish to use a custom buildpack to handle specific application logic. + +To use a specific buildpack, you can run the following dokku command: + +```shell +# replace APP with the name of your application +# replace REPOSITORY_URL with your buildpack's url +dokku config:set APP BUILDPACK_URL=REPOSITORY_URL ``` -Alternatively, you may push an app to your dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost. +Please check the documentation for your particular build pack as you may need to include configuration files (such as a Procfile) in your project root. ## Deploying to subdomains The name of remote repository is used as the name of application to be deployed, as for example above: - $ git remote add dokku dokku@dokku.me:node-js-app + $ git remote add dokku dokku@dokku.me:ruby-rails-sample $ git push dokku master Is deployed to, remote: -----> Application deployed: - remote: http://node-js-app.dokku.me + remote: http://ruby-rails-sample.dokku.me You can also specify fully qualified names, say `app.dokku.me`, as @@ -121,95 +174,22 @@ This is in particular useful, then you want to deploy to root domain, as remote: -----> Application deployed: remote: http://dokku.me -## Zero downtime deploy - -Following a deploy, dokku will now wait `DOKKU_DEFAULT_CHECKS_WAIT` seconds (default: `10`), and if the container is still running, then route traffic to the new container. - -This can be problematic for applications whose boot up time can vary and can lead to `502 Bad Gateway` errors. - -Dokku provides a way to run a set of more precise checks against the new container, and only switch traffic over if all checks complete successfully. - -To specify checks, add a `CHECKS` file to the root of your project directory. This is a text file with one line per check. Empty lines and lines starting with `#` are ignored. - -A check is a relative URL and may be followed by expected content from the page, for example: - -``` -/about Our Amazing Team -``` - -Dokku will wait `DOKKU_CHECKS_WAIT` seconds (default: `5`) before running the checks to give server time to start. For shorter/longer wait, change the `DOKKU_CHECKS_WAIT` environment variable. This can also be overridden in the CHECKS file by setting WAIT=nn. +## Dokku/Docker Container Management Compatibility -Dokku will wait `DOKKU_WAIT_TO_RETIRE` seconds (default: `60`) before stopping the old container such that no existing connections to it are dropped. +Dokku is, at it's core, a docker container manager. Thus, it does not necessarily play well with other out-of-band processes interacting with the docker daemon. One thing to note as in [issue #1220](https://github.com/progrium/dokku/issues/1220), dokku executes a cleanup function prior to every deployment. This function removes all exited containers and all 'unattached' images. -Dokku will retry the checks DOKKU_CHECKS_ATTEMPTS times until the checks are successful or DOKKU_CHECKS_ATTEMPTS is exceeded. In the latter case, the deployment is considered failed. This can be overridden in the CHECKS file by setting ATTEMPTS=nn. +## Default vhost -Checks can be skipped entirely by setting `DOKKU_SKIP_ALL_CHECKS` to `true` either globally or per application. You can choose to skip only default checks by setting `DOKKU_SKIP_DEFAULT_CHECKS` to `true` either globally or per application. +See the [nginx documentation](/dokku/nginx/#default-site). -See [checks-examples.md](checks-examples.md) for examples and output. +## Dockerfile deployment -## Removing a deployed app +See the [dockerfile documentation](/dokku/deployment/dockerfiles/). -SSH onto the server, then execute: +## Zero downtime deploy -```shell -dokku apps:destroy myapp -``` +See the [zero-downtime deploy documentation](/dokku/checks-examples/). ## Image tagging -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 -``` - -Example: -``` -root@dokku:~# 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 - -root@dokku:~# dokku tags:create node-js-app v0.9.0 -=====> Added v0.9.0 tag to dokku/node-js-app - -root@dokku:~# 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 - -root@dokku:~# 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)... ------> Running pre-flight checks - For more efficient zero downtime deployments, create a file CHECKS. - See http://progrium.viewdocs.io/dokku/checks-examples.md for examples - CHECKS file not found in container: Running simple container check... ------> Waiting for 10 seconds ... ------> Default container check successful! -=====> node-js-app container output: - Detected 512 MB available memory, 512 MB limit per process (WEB_MEMORY) - Recommending WEB_CONCURRENCY=1 - > node-js-sample@0.1.0 start /app - > node index.js - Node app is running at localhost:5000 -=====> end node-js-app container output ------> Running post-deploy ------> Configuring node-js-app.dokku.me... ------> Creating http nginx.conf ------> Running nginx-pre-reload - Reloading nginx ------> Shutting down old containers in 60 seconds -=====> 025eec3fa3b442fded90933d58d8ed8422901f0449f5ea0c23d00515af5d3137 -=====> Application deployed: - http://node-js-app.dokku.me - -``` - -## Dokku/Docker Container Management Compatibility - -Dokku is, at it's core, a docker container manager. Thus, it does not necessarily play well with other out-of-band processes interacting with the docker daemon. One thing to note as in [issue #1220](https://github.com/progrium/dokku/issues/1220), dokku executes a cleanup function prior to every deployment. This function removes all exited containers and all 'unattached' images. +See the [image tagging documentation](/dokku/deployment/images). diff --git a/docs/assets/style.css b/docs/assets/style.css index b32ae72973e..efd2d0c4dfb 100644 --- a/docs/assets/style.css +++ b/docs/assets/style.css @@ -228,6 +228,16 @@ pre { color: #4d4d4c; margin: 2em 0; } +blockquote { + border-left: 4px solid #5bc0de; + background-color: #f4f8fa; + padding: 15px 15px 1px; + margin-bottom: 30px; +} +blockquote.new-as-of { + border-left: 4px solid #ef5b58; + background-color: #f9ad76; +} @media (min-width: 768px) { .quickstart-code { font-size: 14px; diff --git a/docs/checks-examples.md b/docs/checks-examples.md index 70aca9be22e..dc9ce44588c 100644 --- a/docs/checks-examples.md +++ b/docs/checks-examples.md @@ -1,4 +1,54 @@ -# Checks Examples +# Zero Downtime Deploys + +> New as of 0.3.0 + +Following a deploy, dokku will now wait `10` seconds before routing traffic to the nwe container. If the container is not running after this time, then the deploy is failed and your old container will continue serving traffic. You can configure this time using the following command: + +```shell +dokku config:set --global DOKKU_DEFAULT_CHECKS_WAIT=30 +``` + +If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use dokku's `checks` functionality to more precisely check whether an application can serve traffic or not. + +To specify checks, add a `CHECKS` file to the root of your project directory. This is a text file with one line per check. Empty lines and lines starting with `#` are ignored. + +A check is a relative URL and may be followed by expected content from the page, for example: + +``` +/about Our Amazing Team +``` + +Dokku will wait `5` seconds before running the checks to give server time to start. This time can be overridden on a per-app basis in the `CHECKS` file by setting `WAIT=nn`. You may also override this for the global dokku installation: + +```shell +dokku config:set --global DOKKU_CHECKS_WAIT=15 +``` + +Dokku will wait `60` seconds before stopping the old container so that existing connections are given a chance to complete. This time is also configurable globally: + +```shell +dokku config:set --global DOKKU_WAIT_TO_RETIRE=120 +``` + +> Note that during this time, multiple containers may be running on your server, which can be an issue for memory-hungry applications on memory-constrained servers. + +Dokku will retry the checks `5` times until the checks are successful. If all 5 checks fail, the deployment is considered failed. This can be overridden in the `CHECKS` file by setting `ATTEMPTS=nn`. This number is also configurable globally: + +```shell +dokku config:set --global DOKKU_CHECKS_ATTEMPTS=2 +``` + +You can also choose to skip checks completely either globally or on a per-application basis: + +```shell +# globally +dokku config:set --global DOKKU_SKIP_ALL_CHECKS=true + +# for APP +dokku config:set APP DOKKU_SKIP_ALL_CHECKS=true +``` + +## Checks Examples The CHECKS file may contain empty lines, comments (lines starting with #), settings (NAME=VALUE) and check instructions. @@ -6,36 +56,49 @@ settings (NAME=VALUE) and check instructions. The format of a check instruction is a path, optionally followed by the expected content. For example: - / My Amazing App - /stylesheets/index.css .body - /scripts/index.js $(function() - /images/logo.png +``` +/ My Amazing App +/stylesheets/index.css .body +/scripts/index.js $(function() +/images/logo.png +``` To check an application that supports multiple hostnames, use relative URLs that include the hostname, for example: - //admin.example.com Admin Dashboard - //static.example.com/logo.png +``` +//admin.example.com Admin Dashboard +//static.example.com/logo.png +``` You can also specify the protocol to explicitly check HTTPS requests. -The default behavior is to wait for 5 seconds before running the first check, -and timeout each check to 30 seconds. + +``` +https://admin.example.com Admin Dashboard +https://static.example.com/logo.png +``` + +The default behavior is to wait for 5 seconds before running the first check, and timeout each check to 30 seconds. By default, checks will be attempted 5 times. (Retried 4 times) -You can change these by setting WAIT, TIMEOUT and ATTEMPTS to different values, for +You can change these by setting `WAIT`, `TIMEOUT` and `ATTEMPTS` to different values, for example: - WAIT=30 # Wait 1/2 minute - TIMEOUT=60 # Timeout after a minute - ATTEMPTS=10 # attempt checks 10 times +``` +WAIT=30 # Wait 1/2 minute +TIMEOUT=60 # Timeout after a minute +ATTEMPTS=10 # attempt checks 10 times + +/ My Amazing App +``` + +## Example: Successful Rails Deployment -# Example: Successful Rails Deployment -In this example, a rails applicaiton 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. -ATTEMPTS is set to 6, but the third attempt succeeds. +In this example, a rails applicaiton 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. `ATTEMPTS` is set to 6, but the third attempt succeeds. -## CHECKS file +### CHECKS file ```` WAIT=5 @@ -45,7 +108,7 @@ ATTEMPTS=6 > check.txt is a text file returning the string 'simple_check' -## Deploy Output +### Deploy Output > Note: The output has been trimmed for brevity @@ -101,12 +164,12 @@ curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused http://myapp.dokku.example.com ```` -# Example: Failing Rails Deployment +## Example: Failing Rails Deployment In this example, a Rails application fails to deploy. The reason for the failure is that the postgres database connection fails. The initial checks will fail while we wait for the server to start up, just like in the above example. However, once the server does start accepting connections, we will see an error 500 due to the postgres database connection failure. Once the attempts have been exceeded, the deployment fails and we see the container output, which shows the Postgres connection errors. -## CHECKS file +### CHECKS file ```` WAIT=5 @@ -116,7 +179,7 @@ ATTEMPTS=6 > The check to the root url '/' would normally access the database. -## Deploy Output +### Deploy Output > Note: The output has been trimmed for brevity diff --git a/docs/configuration-management.md b/docs/configuration-management.md index d7daf678c02..320450d69bb 100644 --- a/docs/configuration-management.md +++ b/docs/configuration-management.md @@ -1,16 +1,57 @@ -# Configuration management +# Environment Variables Typically an application will require some configuration to run properly. Dokku supports application configuration via environment variables. Environment variables may contain private data, such as passwords or API keys, so it is not recommended to store them in your application's repository. The `config` plugin provides the following commands to manage your variables: ``` -config - display the config vars for an app -config:get KEY - display a config value for an app -config:set KEY1=VALUE1 [KEY2=VALUE2 ...] - set one or more config vars -config:unset KEY1 [KEY2 ...] - unset one or more config vars +config (|--global) Display all global or app-specific config vars +config:get (|--global) KEY Display a global or app-specific config value +config:set (|--global) KEY1=VALUE1 [KEY2=VALUE2 ...] Set one or more config vars +config:unset (|--global) KEY1 [KEY2 ...] Unset one or more config vars ``` -The variables are available both at run time and during the application build/compilation step. You no longer need a `user-env` plugin as Dokku handles this functionality in a way equivalent to how Heroku handles it. +The variables are available both at run time and during the application build/compilation step. -> Note: Global `BUILD_ENV` files are currently migrated into a global `ENV` file and sourced before app-specific variables. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications. +> Note: Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications. + +You can set multiple environment variables at once: + +```shell +dokku config:set node-js-app ENV=prod COMPILE_ASSETS=1 +``` + +When setting variables with whitespace, you need to escape the whitespace: + +```shell +dokku config:set node-js-app KEY=\"VAL\ WITH\ SPACES\" +``` + +When setting or unsetting environment variables, you may wish sometimes to avoid an application restart. This is useful when developing plugins or when setting multiple environment variables in a scripted manner. To do so, use the `--no-restart` flag: + +```shell +dokku --no-restart config:set node-js-app ENV=prod +``` + +If you wish to have the variables output in an `eval`-compatible form, you can use the `--export` flag: + +```shell +dokku config node-js-app --export +# outputs variables in the form: +# +# export ENV='prod' +# export COMPILE_ASSETS='1' + +# source in all the node-js-app app environment variables +eval $(dokku config node-js-app --export) +``` + +You can also output the variables in a single-line for usage in command-line utilities with the `--shell` flag: + +```shell +dokku config node-js-app --shell + +# outputs variables in the form: +# +# ENV='prod' COMPILE_ASSETS='1' +``` diff --git a/docs/deployment/dockerfiles.md b/docs/deployment/dockerfiles.md new file mode 100644 index 00000000000..0ef2559fdf4 --- /dev/null +++ b/docs/deployment/dockerfiles.md @@ -0,0 +1,41 @@ +# Dockerfile Deployment + +> New as of 0.3.15 + +While Dokku normally defaults to using [heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, you can also use docker's native `Dockerfile` system to define a container. + +To use a dockerfiles for deployment, commit a valid `Dockerfile` to the root of your repository and push the repository to your Dokku installation. If this file is detected, Dokku will default to using it to construct containers **except** in the following two cases: + +- The application has a `BUILDPACK_URL` environment variable set via the `dokku config:set` command or in a committed `.env` file. In this case, Dokku will use your specified buildpack. +- The application has a `.buildpacks` file in the root of the repository. In this case, Dokku will use your specified buildpack(s). + +## Exposed ports + +By default, Dokku will extract the first `EXPOSE` tcp port and use said port with nginx to proxy your app to that port. For applications that have multiple ports exposed, you may override this port via the following command: + +```shell +# replace APP with the name of your application +dokku config:set APP DOKKU_DOCKERFILE_PORT=8000 +``` + +Dokku will not expose other ports on your application without a [custom docker-option](/dokku/configuration/docker-options/). + +If you do not have a port explicitly exposed, Dokku will automatically expose port `5000` for your application. + +## 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`: + +``` +ENTRYPOINT ["node"] +``` + +You can do: + +``` +dokku config:set APP DOKKU_DOCKERFILE_START_CMD="--harmony server.js" +``` + +To tell docker what to run. + +Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disable docker's image layer cache. Lastly, for more granular build control, you may also pass any `docker build` option to `docker`, by setting `$DOKKU_DOCKER_BUILD_OPTS`. diff --git a/docs/deployment/images.md b/docs/deployment/images.md new file mode 100644 index 00000000000..98890f55b43 --- /dev/null +++ b/docs/deployment/images.md @@ -0,0 +1,57 @@ +# Image Tagging + +> New as of 0.4.0 + +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 +``` + +Example: + +``` +root@dokku:~# 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 + +root@dokku:~# dokku tags:create node-js-app v0.9.0 +=====> Added v0.9.0 tag to dokku/node-js-app + +root@dokku:~# 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 + +root@dokku:~# 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)... +-----> Running pre-flight checks + For more efficient zero downtime deployments, create a file CHECKS. + See http://progrium.viewdocs.io/dokku/checks-examples.md for examples + CHECKS file not found in container: Running simple container check... +-----> Waiting for 10 seconds ... +-----> Default container check successful! +=====> node-js-app container output: + Detected 512 MB available memory, 512 MB limit per process (WEB_MEMORY) + Recommending WEB_CONCURRENCY=1 + > node-js-app@0.1.0 start /app + > node index.js + Node app is running at localhost:5000 +=====> end node-js-app container output +-----> Running post-deploy +-----> Configuring node-js-app.dokku.me... +-----> Creating http nginx.conf +-----> Running nginx-pre-reload + Reloading nginx +-----> Shutting down old containers in 60 seconds +=====> 025eec3fa3b442fded90933d58d8ed8422901f0449f5ea0c23d00515af5d3137 +=====> Application deployed: + http://node-js-app.dokku.me + +``` diff --git a/docs/deployment/one-off-processes.md b/docs/deployment/one-off-processes.md new file mode 100644 index 00000000000..46c32d3b834 --- /dev/null +++ b/docs/deployment/one-off-processes.md @@ -0,0 +1,147 @@ +# One-off Processes + +Sometimes you need to either inspect running containers or run a one-off command under an application. In those cases, Dokku makes it easy to either connect to a running container or run a fresh container. + +## Run a command in an app environment + +``` +run Run a command in the environment of an application +``` + +The `run` command can be used to run a one-off process for a specific command. This will start a new container and run the desired command within that container. Note that this container will be stay around even after command completes. The container will be the same container as was used to start the currently deployed application. + +```shell +# runs `ls -lah` in the `/app` directory of the application `node-js-app` +dokku run node-js-app ls -lah +``` + +If you want to remove the container after a command has started, you can run the following command: + +```shell +# keep `run` containers around +dokku config:set --global DOKKU_RM_CONTAINER=1 + +# revert the above setting and keep containers around +dokku config:unset --global DOKKU_RM_CONTAINER +``` + +You may also use the `--rm-container` or `--rm` dokku flags to remove the containers automatically: + +```shell +dokku --rm-container run node-js-app ls -lah +dokku --rm run node-js-app ls -lah +``` + +### Using `run` for cron tasks + +You can always use a one-off container to run an application task: + +```shell +dokku --rm run node-js-app some-command +dokku --rm-container run node-js-app some-command +``` + +For tasks that should not be interrupted, run is the **preferred** method of handling cron tasks, as the container will continue running even during a deploy or scaling event. The trade-off is that there will be an increase in memory usage if there are multiple concurrent tasks running. + +## Entering existing containers + +> New as of 0.4.0 + +``` +enter [ || --container-id ] Connect to a specific app container +``` + +The `enter` command can be used to enter a running container. The following variations of the command exist: + +```shell +dokku enter node-js-app web +dokku enter node-js-app web.1 +dokku enter node-js-app --container-id ID +``` + +By default, it runs a `/bin/bash`, but can also be used to run a custom command: + +```shell +# just echo hi +dokku enter node-js-app web echo hi + +# run a long-running command, as one might for a cron task +dokku enter node-js-app web python script/background-worker.py +``` + +### Using `enter` for cron tasks + +Your procfile can have the following entry: + +``` +cron: while true; do sleep 10; done +``` + +With the `cron` process scaled to `1`: + +```shell +dokku ps:scale node-js-app cron=1 +``` + +You can now run all your commands in that container: + +```shell +dokku enter api cron some-command +``` + +Note that you can also run multiple commands at the same time to reduce memory usage, though that may result in polluting the container environment. + +For tasks that will properly resume, you **should** use the above method, as running tasks will be interrupted during deploys and scaling events, and subsequent commands will always run with the latest container. Note that if you scale the cron container down, this may interrupt proper running of the task. + +## General Cron Recommendations + +Regularly scheduled tasks can be a bit of a pain with dokku. The following are general recommendations to follow to help ensure successful task runs. + +- Add a `MAILTO` environment variable to ship cron emails to yourself. +- Add a `PATH` environment variable or specify the full path to binaries on the host. +- Add a `SHELL` environment variable to specify bash when running commands. +- Keep your cron tasks in time-sorted order. +- Keep your server time in UTC so you don't need to translate daylight saving's time when reading the cronfile. +- Run tasks at the lowest traffic times if possible. +- Use cron to **trigger** jobs, not run them. Use a real queuing system such as rabbitmq to actually process jobs. +- Try to keep tasks quiet so that mails only send on errors. +- Do not silence standard error or standard out. If you silence the former, you will miss failures. Silencing the latter means you should actually make application changes to handle log levels. +- Use a service such as [Dead Man's Snitch](https://deadmanssnitch.com) to verify that cron tasks completed successfully. +- Add lots of comments to your cronfile, including what a task is doing, so that you don't spend time deciphering the file later. +- Place your cronfiles in a pattern such as `/etc/cron.d/APP`. +- Do not use non-ascii characters in your cronfile names. Cron is finicky. +- Remember to have trailing newlines in your cronfile! Cron is finicky. + +The following is a sample cronfile that you can use for your applications: + +``` +# server cron jobs +MAILTO="mail@example.com" +PATH=/usr/local/bin:/usr/bin:/bin +SHELL=/bin/bash + +# m h dom mon dow username command +# * * * * * dokku command to be executed +# - - - - - +# | | | | | +# | | | | +----- day of week (0 - 6) (Sunday=0) +# | | | +------- month (1 - 12) +# | | +--------- day of month (1 - 31) +# | +----------- hour (0 - 23) +# +----------- min (0 - 59) + +### HIGH TRAFFIC TIME IS B/W 00:00 - 04:00 AND 14:00 - 23:59 +### RUN YOUR TASKS FROM 04:00 - 14:00 +### KEEP SORTED IN TIME ORDER + +### PLACE ALL CRON TASKS BELOW + +# removes unresponsive users from the subscriber list to decrease bounce rates +0 0 * * * dokku dokku --rm run node-js-app some-command + +# sends out our email alerts to users +0 1 * * * dokku dokku ps:scale node-js-app cron=1 && dokku enter node-js-app cron some-other-command && dokku ps:scale node-js-app cron=0 + +### PLACE ALL CRON TASKS ABOVE, DO NOT REMOVE THE WHITESPACE AFTER THIS LINE + +``` diff --git a/docs/deployment/ssl-configuration.md b/docs/deployment/ssl-configuration.md index 5526b8ccbc0..df33c566042 100644 --- a/docs/deployment/ssl-configuration.md +++ b/docs/deployment/ssl-configuration.md @@ -5,11 +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 + +# for 0.3.x +dokku nginx:import-ssl < certs.tar ``` ## Per-application certificate management @@ -22,7 +25,7 @@ The `certs:add` command can be used to push a `tar` containing a certificate `.c ```shell tar cvf cert-key.tar server.crt server.key -# replace APP with your app name +# replace APP with the name of your application dokku certs:add < cert-key.tar ``` @@ -89,3 +92,23 @@ Once TLS is enabled, the application will be accessible by `https://` (redirecti The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. dokku does not, by default, enable this header. It is thus left up to you, the user, to enable it for your site. Beware that if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails. + +## Running behind a load balancer + +> New as of 0.3.17 + +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 setting the `DOKKU_SSL_TERMINATED` environment variable: + +```shell +dokku config:set myapp DOKKU_SSL_TERMINATED=1 +``` + +Only use this option if: +1. All requests are terminated at the load balancer, and forwarded to Nginx +2. The load balancer is configured to send the `X-Forwarded-` headers (this may be off by default) + +If it's possible to make HTTP/S requests directly to Nginx, bypassing the load balancer, or if the load balancer is not configured to set these headers, then it becomes possible for a client to set these headers to arbitrary values. + +This could result in security issue, for example, if your application looks at the value of the `X-Forwarded-Proto` to determine if the request was made over HTTPS. diff --git a/docs/dns.md b/docs/dns.md index c771147f898..1c0293c9050 100644 --- a/docs/dns.md +++ b/docs/dns.md @@ -1,52 +1,52 @@ -# Overview +# DNS Configuration This is a work in progress. -## DNS Versions +### DNS Versions There are many different DNS servers 'in the wild'. Some of the popular ones on Linux are BIND, dnsmasq, and pdns. Windows has its own built-in DNS server as well as Unbound, Posadis, and more. A full list of DNS packages can be found on Wikipedia under [Comparison of DNS Server Software](http://en.wikipedia.org/wiki/Comparison_of_DNS_server_software). In addition to the various DNS packages, there are tens of thousands of [Managed DNS Providers](http://en.wikipedia.org/wiki/List_of_managed_DNS_providers) out that all have different DNS interfaces. -## Focus +### Focus Because there are so many different DNS server packages out there as well as a tremendous number of Managed DNS Providers, we will focus on the concepts of DNS as well as providing examples in the 'BIND' format so you can adapt the information to your own server package or managed DNS provider. -## Assumptions +### Assumptions * We assume you have a passing familiarity with DNS. If not, you can read an [in-depth article](http://www.diaryofaninja.com/blog/2012/03/03/devops-dns-for-developers-ndash-now-therersquos-no-excuse-not-to-know) on DNS. But basically you need to know that DNS changes names (like example.tld) into addresses (like 127.0.0.1) * We assume you already have a domain name registered and pointed to your favorite Managed DNS Provider or have your own BIND DNS server running. * You have a server on the internet and are about to follow the instructions in the [README](https://github.com/progrium/dokku/blob/master/README.md) to get dokku installed. Don't do the install just yet though. -## HELP! +### HELP! Don't be afraid to ask if you need help. Create a [new issue](https://github.com/progrium/dokku/issues) and someone will be glad to assist you. # Getting started -For the examples, we will use the domain name 'example.tld' and the IP address '127.0.0.1'. +For the examples, we will use the domain name `example.tld` and the IP address `127.0.0.1`. -Dokku uses a DNS to differentiate between apps on your dokku-powered server. If you are using the domain 'example.tld', and you have two apps 'myapp1' and 'myapp2', dokku will make them available at 'myapp1.example.tld' and 'myapp2.example.tld'. +Dokku uses a DNS to differentiate between apps on your dokku-powered server. If you are using the domain `example.tld`, and you have two apps `myapp1` and `myapp2`, dokku will make them available at `myapp1.example.tld` and `myapp2.example.tld`. -To get started, you need to know the IP address of your dokku server. Connect in to it and run 'ifconfig' or 'ip addr' to see the IP address. +To get started, you need to know the IP address of your dokku server. Connect in to it and run `ifconfig` or `ip addr` to see the IP address. # Caching -Please remember that DNS relies heavily on _caching_. Changes you make to DNS could take anywhere from a few seconds to a few *days* to 'propagate'. If you tried surfing to example.tld, then changed the IP address in DNS, it could be a while before your computer picks up on the changes. +Please remember that DNS relies heavily on _caching_. Changes you make to DNS could take anywhere from a few seconds to a few *days* to propagate. If you tried surfing to example.tld, then changed the IP address in DNS, it could be a while before your computer picks up on the changes. ## The two methods -Now you have to make a decision about your domain. Do you want everything and anything at example.tld to go to your dokku server, or would you rather use a 'sub domain' for your dokku server? +Now you have to make a decision about your domain. Do you want everything and anything at `example.tld` to go to your dokku server, or would you rather use a 'sub domain' for your dokku server? -In other words, do you want your applications on your dokku server accessible via myapp.example.tld or via myapp.myserver.example.tld? +In other words, do you want your applications on your dokku server accessible via `myapp.example.tld` or via `myapp.myserver.example.tld`? ### Using a sub-domain (myapp.myserver.example.tld) -Using a sub-domain is easy. When you set up your server, you probably gave it a name like myserver.example.tld. +Using a sub-domain is easy. When you set up your server, you probably gave it a name like `myserver.example.tld`. -Go in to your Managed DNS provider and create an 'A' record named 'myserver' and put in the IP address you got from your server a few moments ago. +Go in to your Managed DNS provider and create an `A` record named `myserver` and put in the IP address you got from your server a few moments ago. -Hopefully your managed DNS provider also supports wildcards. Create a second 'A' record named '*.myserver' along with the IP address you got from your server a few moments ago. +Hopefully your managed DNS provider also supports wildcards. Create a second `A` record named `*.myserver` along with the IP address you got from your server a few moments ago. If you are using BIND, your zone file will look similar to this: @@ -55,26 +55,23 @@ $ORIGIN example.tld $TTL 5m myserver IN A 127.0.0.1 -*.myserver IN A 127.0.0.1 +*.myserver IN A 127.0.0.1 ``` You can verify your changes in Linux by trying one or more of the following commands: -* host myserver.example.tld - -* dig -t A myserver.example.tld - -* nslookup myserver.example.tld +* `host myserver.example.tld` +* `dig -t A myserver.example.tld` +* `nslookup myserver.example.tld` Now is a good time to remind you that the answers you get MAY BE CACHED. -If everything is working correctly, you should also be able to query for any other name 'under' myserver.example.tld and get back the IP address of your server. Try: - -* host test.myserver.example.tld +If everything is working correctly, you should also be able to query for any other name under `myserver.example.tld` and get back the IP address of your server. Try: -* host xyzzy.myserver.example.tld +* `host test.myserver.example.tld` +* `host xyzzy.myserver.example.tld` -If they all return your IP address, you have set DNS up properly for dokku. You should also be able to 'ssh root@myserver.example.tld' and access your server. +If they all return your IP address, you have set DNS up properly for dokku. You should also be able to `ssh root@myserver.example.tld` and access your server. Proceed with the setup instructions in the [README](https://github.com/progrium/dokku/blob/master/README.md) @@ -84,5 +81,5 @@ This section is a work in progress. It is incomplete. Using the 'root' of your domain is nearly identical to the previous example. -* hostname is under example.tld, still needs A record -* Need to modify /home/dokku/HOSTNAME and /home/dokku/VHOST +* hostname is under `example.tld`, still needs `A` record +* Need to modify `/home/dokku/HOSTNAME` and `/home/dokku/VHOST` diff --git a/docs/docker-options.md b/docs/docker-options.md index 7ce76869945..dfb1f9e836b 100644 --- a/docs/docker-options.md +++ b/docs/docker-options.md @@ -1,57 +1,52 @@ -docker-options -======================== - -Usage ------ - -```bash -$ dokku help -... - docker-options Display apps docker options for all phases - docker-options Display apps docker options for phase (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) -... -```` - -Add some options (first, for the deployed/running app and second when executing `dokku run`) - -```bash -$ dokku docker-options:add myapp deploy "-v /host/path:/container/path" -$ dokku docker-options:add myapp run "-v /another/container/path" +# Docker Container Options + +> New as of 0.3.17 + +``` +docker-options Display apps docker options for all phases +docker-options Display apps docker options for phase (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) +``` + +Add some options (first, for the deployed/running app and second when executing `dokku run`): + +``` +dokku docker-options:add myapp deploy "-v /host/path:/container/path" +dokku docker-options:add myapp run "-v /another/container/path" ``` Check what we added -```bash -$ dokku docker-options myapp -Deploy options: - -v /host/path:/container/path -Run options: - -v /another/container/path +```shell +dokku docker-options myapp +# Deploy options: +# -v /host/path:/container/path +# Run options: +# -v /another/container/path ``` Remove an option -```bash -$ dokku docker-options:remove myapp run "--link container_name:alias" + +```shell +dokku docker-options:remove myapp run "--link container_name:alias" ``` -Note about `dokku` phases and `docker-options` ------------- -`dokku` deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to the underlying docker container in the following 3 phases/containers +### Note about `dokku` phases and `docker-options` + +`dokku` deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to the underlying docker container in the following 3 phases/containers: + - `build`: the container that executes the appropriate buildpack - `deploy`: the container that executes your running/deployed application - `run`: the container that executes any arbitrary command via `dokku run myapp` - -Advanced Usage (avoid if possible) ------------- +## Advanced Usage (avoid if possible) In your applications folder (`/home/dokku/app_name`) create a file called `DOCKER_OPTIONS_RUN` (or `DOCKER_OPTIONS_BUILD` or `DOCKER_OPTIONS_DEPLOY`). Inside this file list one docker option per line. For example: -```bash +```shell --link container_name:alias -v /host/path:/container/path -v /another/container/path @@ -59,7 +54,7 @@ Inside this file list one docker option per line. For example: The above example will result in the following options being passed to docker during `dokku run`: -```bash +```shell --link container_name:alias -v /host/path:/container/path -v /another/container/path ``` diff --git a/docs/dokku-events-logs.md b/docs/dokku-events-logs.md index 462855d53b4..6c9b5f1d247 100644 --- a/docs/dokku-events-logs.md +++ b/docs/dokku-events-logs.md @@ -1,12 +1,14 @@ # 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 +events [-t] Show the last events (-t follows) +events:list List logged events +events:on Enable events logger +events:off Disable events logger ``` ## Usage diff --git a/docs/home.html b/docs/home.html index f56e9117369..3577590805e 100644 --- a/docs/home.html +++ b/docs/home.html @@ -52,7 +52,7 @@

Dokku

The smallest PaaS implementation you've ever seen

Docker powered mini-Heroku in around 200 lines of Bash

- View Documentation + View Documentation

diff --git a/docs/index.md b/docs/index.md index 9122259b532..0d0fb38d39a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,7 @@

The smallest PaaS implementation you've ever seen

Docker powered mini-Heroku in around 200 lines of Bash

- View Documentation + View Documentation

diff --git a/docs/installation.md b/docs/installation.md index 31dbbad11b2..bb3ca88ff55 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,26 +1,36 @@ -# Installation +# Getting Started with Dokku -## Requirements +## What is Dokku? -- A fresh VM running Ubuntu `14.04 x64` -- At least `1GB` of system memory ([workaround for 512MB machines](http://progrium.viewdocs.io/dokku/advanced-installation)) -- The VM should have a FQDN set before installation (check by running `sudo hostname -f`). +Dokku is an extensible, open source Platform as a Service that runs on a single server of your choice. -Ubuntu 14.04 x64. Ideally have a domain ready to point to your host. It's designed for and is probably best to use a fresh VM. The bootstrapper will install everything it needs. +To start using Dokku, you'll need a system with that meets the following minimum requirements: -## Installing the latest Stable version +- A fresh installation of [Ubuntu 14.04 x64](http://www.ubuntu.com/download/) with the FQDN set ^[1] +- At least `1GB` of system memory ^[2] -To install the latest stable version of dokku, you can run the following bootstrapper command: +You can *optionally* have a domain name pointed at the host's IP, though this is not necessary. + +Dokku is designed for usage on a fresh installation of Ubuntu, and should install all necessary dependencies if installing via the bootstrap method. + +### Installing the latest stable version + +To install the latest stable version of dokku, you can run the following shell commands: ```shell # installs dokku via apt-get wget https://raw.githubusercontent.com/progrium/dokku/v0.4.2/bootstrap.sh sudo DOKKU_TAG=v0.4.2 bash bootstrap.sh - -# By default, this will start the web-based installer on your server's IP -# You may *instead* follow the debian packaging notes for a more automated installation ``` +The installation process takes about 5-10 minutes, depending upon internet connection speed. + +Once the installation is complete, you can open a browser to setup your SSH key and virtualhost settings. Open your browser of choice and navigate to the host's IP address - or the domain you assigned to that IP previously - and configure dokku via the web admin. + +Once you save your settings, the web admin will self-terminate and you should be able to run or deploy to the dokku installation. + +### Installing via other methods + For various reasons, certain hosting providers may have other steps that should be preferred to the above. If hosted on any of the following popular hosts, please follow the linked to instructions: - [Digital Ocean Installation Notes](http://progrium.viewdocs.io/dokku/getting-started/install/digitalocean) @@ -31,3 +41,8 @@ As well, you may wish to customize your installation in some other fashion. or e - [Debian Package Installation Notes](http://progrium.viewdocs.io/dokku/getting-started/install/debian) - [Vagrant Installation Notes](http://progrium.viewdocs.io/dokku/getting-started/install/vagrant) - [Advanced Install Customization](http://progrium.viewdocs.io/dokku/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](http://progrium.viewdocs.io/dokku/advanced-installation)).} diff --git a/docs/nginx.md b/docs/nginx.md index a27347ab1cd..71b34471245 100644 --- a/docs/nginx.md +++ b/docs/nginx.md @@ -1,99 +1,28 @@ -# Nginx +# Nginx Configuration Dokku uses nginx as it's server for routing requests to specific applications. By default, access and error logs are written for each app to `/var/log/nginx/${APP}-access.log` and `/var/log/nginx/${APP}-error.log` respectively ``` -nginx:access-logs [-t] Show the nginx access logs for an application (-t follows) -nginx:build-config (Re)builds nginx config for given app -nginx:disable disable nginx for an application (forces container binding to external interface) -nginx:enable enable nginx for an application -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:disable Disable nginx for an application (forces container binding to external interface) +nginx:enable Enable nginx for an application +nginx:error-logs [-t] Show the nginx error logs for an application (-t follows) ``` -## TLS/SPDY support - -Dokku provides easy TLS/SPDY support out of the box. This can be done app-by-app or for all subdomains at once. Note that whenever TLS support is enabled SPDY is also enabled. - -### SSL Configuration - -In 0.4.0, SSL Configuration has been replaced by the [`certs` plugin](http://progrium.viewdocs.io/dokku/deployment/ssl-configuration)). For users of dokku 0.3.x, please refer to the following sections. - -### Per App - -To enable TLS connections to to one of your applications, do the following: - -* Create a key file and a cert file. - * You can find detailed steps for generating a self-signed certificate at https://devcenter.heroku.com/articles/ssl-certificate-self - * If you are not paranoid and need it just for a DEV or STAGING app, you can use http://www.selfsignedcertificate.com/ to generate your 2 files more easily. -* Rename your files to server.key and server.crt -* tar these 2 files together, *without* subdirectories. Example: tar cvf cert-key.tar server.crt server.key -* Install the pair for your app, like this: ssh dokku@ip-of-your-dokku-server nginx:import-ssl < cert-key.tar - -You will need to repeat the steps above for each domain used to serve your app. You can't simply create a single tar with all key/cert files in it (see https://github.com/progrium/dokku/issues/1195). - - -### All Subdomains - -To enable TLS connections for all your applications at once you will need a wildcard TLS certificate. - -To enable TLS across all apps, copy or symlink the `.crt` and `.key` files into the `/home/dokku/tls` folder (create this folder if it doesn't exist) as `server.crt` and `server.key` respectively. Then, enable the certificates by editing `/etc/nginx/conf.d/dokku.conf` and uncommenting these two lines (remove the #): - -``` -ssl_certificate /home/dokku/tls/server.crt; -ssl_certificate_key /home/dokku/tls/server.key; -``` - -The nginx configuration will need to be reloaded in order for the updated TLS configuration to be applied. This can be done either via the init system or by re-deploying the application. Once TLS is enabled, the application will be accessible by `https://` (redirection from `http://` is applied as well). - -**Note**: TLS will not be enabled unless the application's VHOST matches the certificate's name. (i.e. if you have a cert for *.example.com TLS won't be enabled for something.example.org or example.net) - -### HSTS Header - -The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. dokku does not, by default, enable this header. It is thus left up to you, the user, to enable it for your site. - -Beware that if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails. - -### Importing ssl certificates - -You can import ssl certificates via tarball using the following command: - -``` bash -dokku nginx:import-ssl myapp < archive-of-certs.tar -``` - -This archive is expanded via `tar xvf`. It should contain `server.crt` and `server.key`. - - -## Running behind a load balancer - -> New as of 0.3.17 - -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 setting the `DOKKU_SSL_TERMINATED` environment variable: - -```shell -dokku config:set myapp DOKKU_SSL_TERMINATED=1 -``` - -Only use this option if: -1. All requests are terminated at the load balancer, and forwarded to Nginx -2. The load balancer is configured to send the `X-Forwarded-` headers (this may be off by default) - -If it's possible to make HTTP/S requests directly to Nginx, bypassing the load balancer, or if the load balancer is not configured to set these headers, then it becomes possible for a client to set these headers to arbitrary values. - -This could result in security issue, for example, if your application looks at the value of the `X-Forwarded-Proto` to determine if the request was made over HTTPS. - - ## Customizing the nginx configuration -> New as of 0.4.0. +> New as of 0.3.10. -Dokku currently templates out an nginx configuration that is included in the `nginx-vhosts` plugin. If you'd like to provide a custom template for your application, you should copy the existing template - ssl or non-ssl - into your application repository's root directory as the file `nginx.conf.template`. The next time you deploy, Nginx will use your template instead of the default. +Dokku currently templates out an nginx configuration that is included in the `nginx-vhosts` plugin. If you'd like to provide a custom template for your application, there are a few options: -> New as of 0.3.10. +- Copy the existing template - ssl or non-ssl - into your application repository's root directory as the file `nginx.conf.template`. +- Create a template file in `/home/dokku/APP` named one of the following: + - `nginx.conf.template` (since 0.3.10) + - `nginx.conf.ssl_terminated.template` (since 0.4.0) + - `nginx.ssl.conf.template` (since 0.4.2) -You may also place this file on disk at the path `/home/dokku/myapp/nginx.conf.template`. If placed on disk on the dokku server, the template file **must** be owned by the user `dokku:dokku`. +> If placed on disk on the dokku server, the template file **must** be owned by the user `dokku:dokku`. For instance - assuming defaults - to customize the nginx template in use for the `myapp` application, create the file `nginx.conf.template` in your repo or on disk with the with the following contents: @@ -137,14 +66,18 @@ After your changes a `dokku deploy myapp` will regenerate the `/home/dokku/myapp The default nginx.conf- templates will include everything from your apps `nginx.conf.d/` subdirectory in the main `server {}` block (see above): - include $DOKKU_ROOT/$APP/nginx.conf.d/*.conf; +``` +include $DOKKU_ROOT/$APP/nginx.conf.d/*.conf; +``` . That means you can put additional configuration in separate files, for example to limit the uploaded body size to 50 megabytes, do - mkdir /home/dokku/myapp/nginx.conf.d/ - echo 'client_max_body_size 50M;' > /home/dokku/myapp/nginx.conf.d/upload.conf - chown dokku:dokku /home/dokku/myapp/nginx.conf.d/upload.conf - service nginx reload +```shell +mkdir /home/dokku/myapp/nginx.conf.d/ +echo 'client_max_body_size 50M;' > /home/dokku/myapp/nginx.conf.d/upload.conf +chown dokku:dokku /home/dokku/myapp/nginx.conf.d/upload.conf +service nginx reload +``` ## Customizing hostnames @@ -186,6 +119,13 @@ On subsequent deploys, the nginx virtualhost will be discarded. This is useful w > New as of 0.3.10 +```shell +domains:add DOMAIN Add a custom domain to app +domains List custom domains for app +domains:clear Clear all custom domains for app +domains:remove DOMAIN Remove a custom domain from app +``` + The domains plugin allows you to specify custom domains for applications. This plugin is aware of any ssl certificates that are imported via `nginx:import-ssl`. Be aware that setting `NO_VHOST` will override any custom domains. Custom domains are also backed up via the built-in `backup` plugin @@ -206,7 +146,7 @@ dokku domains:clear myapp dokku domains:remove myapp example.com ``` -### Container network interface binding +## Container network interface binding > New as of 0.3.13 @@ -225,12 +165,11 @@ root@dokku:~/dokku# docker inspect --format '{{ .NetworkSettings.IPAddress }}' g root@dokku:/home/dokku# 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 nostalgic_tesla - ``` -# Default site +## Default site -By default, dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. If this is not the desired behavior, you may want to add the following configuration to nginx. 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). +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). ``` server { @@ -242,3 +181,30 @@ server { log_not_found off; } ``` + +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`: + +``` +# Swap both conf.d include line and the sites-enabled include line. From: +include /etc/nginx/conf.d/*.conf; +include /etc/nginx/sites-enabled/*; + +# to the following + +include /etc/nginx/sites-enabled/*; +include /etc/nginx/conf.d/*.conf; +``` + +Alternatively, you may push an app to your dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost. + +## Running behind a load balancer + +See the [load balancer documentation](/dokku/deployment/ssl-configuration/#running-behind-a-load-balancer). + +## HSTS Header + +See the [HSTS documentation](/dokku/deployment/ssl-configuration/#hsts-header). + +## SSL Configuration + +See the [ssl documentation](/dokku/deployment/ssl-configuration/). diff --git a/docs/process-management.md b/docs/process-management.md index 7a138047719..120a7269f24 100644 --- a/docs/process-management.md +++ b/docs/process-management.md @@ -1,16 +1,18 @@ # Process/Container management +> New as of 0.3.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 diff --git a/docs/remote-commands.md b/docs/remote-commands.md index 943ebfa47ea..837138ed4a2 100644 --- a/docs/remote-commands.md +++ b/docs/remote-commands.md @@ -1,4 +1,4 @@ -# Remote commands +# Remote Commands Dokku commands can be run over ssh. Anywhere you would run `dokku `, just run `ssh -t dokku@dokku.me ` The `-t` is used to request a pty. It is highly recommended to do so. @@ -9,15 +9,6 @@ Host dokku.me RequestTTY yes ``` -## Run a command in the app environment - -It's possible to run commands in the environment of the deployed application: - -```shell -dokku run node-js-app ls -alh -dokku run -``` - ## Behavioral modifiers 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 -- ` @@ -29,3 +20,9 @@ in order to avoid ssh interpretting dokku arguments for itself. --rm|--rm-container remove docker container after successful dokku run --force force flag. currently used in apps:destroy ``` + +## Clients + +You may optionally use a client to connect to your dokku server. Most clients use the configured `git remote` to locate the dokku server, though some allow for overriding this via an environment variable or flag. + +Please refer to the [clients](/dokku/community/clients/) list for more details. diff --git a/docs/template.html b/docs/template.html index 6a9e3ce2c96..eccc9bc96de 100644 --- a/docs/template.html +++ b/docs/template.html @@ -17,6 +17,16 @@ word-break: normal; word-wrap: normal; } + blockquote { + border-left: 4px solid #5bc0de; + background-color: #f4f8fa; + padding: 15px 15px 1px; + margin-bottom: 30px; + } + blockquote.new-as-of { + border-left: 4px solid #ef5b58; + background-color: #f9ad76; + } @@ -40,34 +50,41 @@