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

Fix documentation directory structure

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

79
docs/getting-started/advanced-installation.md Normal file
View File

@@ -0,0 +1,79 @@
# Advanced installation
You can always install dokku straight from the latest - potentially unstable - master release via the following bash command:
```shell
# using a branch results in installing from source
wget https://raw.githubusercontent.com/dokku/dokku/master/bootstrap.sh
sudo DOKKU_BRANCH=master bash bootstrap.sh
```
## Development
If you plan on developing dokku, the easiest way to install from your own repository is cloning the repository and calling the install script. Example:
```shell
git clone https://github.com/yourusername/dokku.git
cd dokku
sudo make install
```
The `Makefile` allows source URLs to be overridden to include customizations from your own repositories. The `DOCKER_URL`, `PLUGN_URL`, `SSHCOMMAND_URL` and `STACK_URL` environment variables may be set to override the defaults (see the `Makefile` for how these apply). Example:
```shell
sudo SSHCOMMAND_URL=https://raw.githubusercontent.com/yourusername/sshcommand/master/sshcommand make install
```
## Bootstrap a server from your own repository
The bootstrap script allows the dokku repository URL to be overridden to bootstrap a host from your own clone of dokku using the `DOKKU_REPO` environment variable. Example:
```shell
wget https://raw.githubusercontent.com/dokku/dokku/master/bootstrap.sh
chmod +x bootstrap.sh
sudo DOKKU_REPO=https://github.com/yourusername/dokku.git DOKKU_BRANCH=master ./bootstrap.sh
```
## Custom herokuish build
Dokku ships with a pre-built version of version of the [herokuish](https://github.com/gliderlabs/herokuish) component by default. If you want to build your own version you can specify that with an env variable.
```shell
git clone https://github.com/dokku/dokku.git
cd dokku
sudo BUILD_STACK=true STACK_URL=https://github.com/gliderlabs/herokuish.git make install
```
## Configuring
Once dokku is installed, if you are not using the web-installer, you'll want to configure a the virtualhost setup as well as the push user. If you do not, your installation will be considered incomplete and you will not be able to deploy applications.
*You should also stop and disable the `dokku-installer` service to remove public access to adding SSH keys.*
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.
That's it!
## VMs with less than 1GB of memory
Having less than 1GB of system memory available for dokku and its containers, for example Digital Ocean's small 512MB machines, might result in unexpected errors, such as **! [remote rejected] master -> master (pre-receive hook declined)** during installation of NPM dependencies (https://github.com/npm/npm/issues/3867).
To work around this issue, it might suffice to augment the linux swap file size to a maximum of twice the physical memory size.
To resize the swap file of a 512MB machine to 1GB, follow these steps while in SSH within your machine:
```shell
cd /var
touch swap.img
chmod 600 swap.img
dd if=/dev/zero of=/var/swap.img bs=1024k count=1000
mkswap /var/swap.img
swapon /var/swap.img
free
echo "/var/swap.img none swap sw 0 0" >> /etc/fstab
```
Reference: https://www.digitalocean.com/community/tutorials/how-to-configure-virtual-memory-swap-file-on-a-vps

2
docs/getting-started/install/linode.md
View File

@@ -38,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.

56
docs/getting-started/installation.md Normal file
View File

@@ -0,0 +1,56 @@
# Getting Started with Dokku
## What is Dokku?
Dokku is an extensible, open source Platform as a Service that runs on a single server of your choice.
To start using Dokku, you'll need a system that meets the following minimum requirements:
- A fresh installation of [Ubuntu 14.04 x64](http://www.ubuntu.com/download/) with the FQDN set <sup>[1]</sup>
- At least `1GB` of system memory <sup>[2]</sup>
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
#### 1. Install dokku
To install the latest stable version of dokku, you can run the following shell commands:
```shell
# for debian systems, installs dokku via apt-get
wget https://raw.githubusercontent.com/dokku/dokku/v0.6.4/bootstrap.sh
sudo DOKKU_TAG=v0.6.4 bash bootstrap.sh
```
The installation process takes about 5-10 minutes, depending upon internet connection speed.
#### 2. Setup SSH key and Virtualhost Settings
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.
*If you don't complete setup via the web installer (even if you set up SSH keys and virtual hosts otherwise) your dokku installation will remain vulnerable to anyone finding the setup page and inserting their key.*
#### 3. Deploy your first application
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](/dokku/getting-started/install/digitalocean)
- [Linode Installation Notes](/dokku/getting-started/install/linode/)
- [Microsoft Azure Installation Notes](/dokku/getting-started/install/azure/)
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/getting-started/advanced-installation/)
---
- <sup>[1]: To check whether your system has an fqdn set, run `sudo hostname -f`</sup>
- <sup>[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).</sup>

156
docs/getting-started/troubleshooting.md Normal file
View File

@@ -0,0 +1,156 @@
# Troubleshooting
__Symptom:__ I deployed my app but I am getting the default nginx page
__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:
```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;
(...)
}
```
Note that the `server_names_hash_bucket_size` setting defines the maximum domain name length.
A value of 64 would allow domains with up to 64 characters. Set it to 128 if you need longer ones.
Save the file and try stopping nginx and starting it again:
```shell
/etc/init.d/nginx stop
## * Stopping nginx nginx [ OK ]
/etc/init.d/nginx start
## * Starting nginx nginx [ OK ]
```
***
__Symptom:__ I want to deploy my app, but while pushing I get the following error
! [remote rejected] master -> master (pre-receive hook declined)
__Solution:__
The `remote rejected` error does not give enough information. Anything could have failed.
To enable dokku tracing, simply run the following command:
```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 :
```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.
***
__Symptom:__ I get the aforementioned error in the build phase (after turning on dokku tracing)
Most errors that happen in this phase are due to transient network issues (either locally or remotely) buildpack bugs.
__Solution (Less solution, more helpful troubleshooting steps):__
Find the failed phase's container image (*077581956a92* in this example)
```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)
```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
```shell
resolvconf -u
```
Please see https://github.com/dokku/dokku/issues/841 and https://github.com/dokku/dokku/issues/649
***
__Symptom:__ I want to deploy my app but I am getting asked for the password of the git user and the error message
fatal: 'NAME' does not appear to be a git repository
fatal: Could not read from remote repository.
__Solution:__
You get asked for a password because your ssh secret key can't be found. This may happen if the private key corresponding to the public key you added with `sshcommand acl-add` is not located in the default location `~/.ssh/id_rsa`.
You have to point ssh to the correct secret key for your domain name. Add the following to your `~/.ssh/config`:
```ini
Host DOKKU_HOSTNAME
IdentityFile "~/.ssh/KEYNAME"
```
Also see [issue #116](https://github.com/dokku/dokku/issues/116)
***
__Symptom:__ I successfully deployed my application with no deployment errors and receiving Bad Gateway when attempting to access the application
__Solution:__
In many cases the application will require the a `process.env.PORT` port opposed to a specified port.
When specifying your port you may want to use something similar to:
```javascript
var port = process.env.PORT || 3000
```
Please see https://github.com/dokku/dokku/issues/282
***
__Symptom:__ Deployment fails because of slow internet connection, messages shows `gzip: stdin: unexpected end of file`
__Solution:__
If you see output similar this when deploying:
```
Command: 'set -o pipefail; curl --fail --retry 3 --retry-delay 1 --connect-timeout 3 --max-time 30 https://s3-external-1.amazonaws.com/heroku-buildpack-ruby/ruby-2.0.0-p451-default-cache.tgz -s -o - | tar zxf -' failed unexpectedly:
!
! gzip: stdin: unexpected end of file
! tar: Unexpected EOF in archive
! tar: Unexpected EOF in archive
! tar: Error is not recoverable: exiting now
```
it might that the curl command that is supposed to fetch the buildpack (anything in the low megabyte file size range) takes too long to finish, due to slowish connection. To overwrite the default values (connection timeout: 3 seconds, total maximum time for operation: 30 seconds), set the following environment variables:
```shell
dokku config:set --global CURL_TIMEOUT=600
dokku config:set --global CURL_CONNECT_TIMEOUT=30
```
Please see https://github.com/dokku/dokku/issues/509

50
docs/getting-started/upgrading.md Normal file
View File

@@ -0,0 +1,50 @@
# Upgrading
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
Before upgrading, check the migration guides to get comfortable with new features and prepare your deployment to be upgraded.
- [0.5 Migration Guide](/dokku/appendices/0.5.0-migration-guide/)
- [0.6 Migration Guide](/dokku/appendices/0.6.0-migration-guide/)
## Upgrade Instructions
If dokku was installed via `apt-get install dokku` or `bootstrap.sh` (most common), upgrade with:
```shell
sudo apt-get update
dokku apps
dokku ps:stop <app> # repeat to shut down each running app
sudo apt-get install -qq -y dokku herokuish
dokku ps:rebuildall # restart all applications
```
### Upgrade From Source
If you installed dokku from source (less common), upgrade with:
```shell
dokku apps
dokku ps:stop <app> # repeat to shut down each running app
cd ~/dokku
git pull --tags origin master
# continue to install from source
sudo DOKKU_BRANCH=master make install
# upgrade to debian package-based installation
sudo make install
dokku ps:rebuildall # restart all applications
```
To upgrade herokuish from source, upgrade with:
```shell
cd /tmp
git clone https://github.com/gliderlabs/herokuish.git
cd herokuish
git pull origin master
IMAGE_NAME=gliderlabs/herokuish BUILD_TAG=latest VERSION=master make -e build-in-docker
```

4
docs/getting-started/where-to-get-help.md
View File

@@ -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.