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

docs: clarify installation documentation

Browse Source 
- Simplify first-install instructions
- Move advanced docs around
- Drop references to web installer

Closes #4947
This commit is contained in:
Jose Diaz-Gonzalez
2022-01-23 22:28:17 -05:00
parent 0a2ea6786d
commit 30cd670a16
3 changed files with 74 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/getting-started/advanced-installation.md
View File

@@ -1,5 +1,24 @@
# Advanced 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:
- [DigitalOcean Installation Notes](/docs/getting-started/install/digitalocean.md)
- [DreamHost Cloud Installation Notes](/docs/getting-started/install/dreamhost.md)
- [Microsoft Azure Installation Notes](/docs/getting-started/install/azure.md)
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](/docs/getting-started/install/debian.md)
- [Docker-based Installation Notes](/docs/getting-started/install/docker.md)
- [RPM Package Installation Notes](/docs/getting-started/install/rpm.md)
- [Vagrant Installation Notes](/docs/getting-started/install/vagrant.md)
- [Advanced Install Customization](/docs/getting-started/advanced-installation.md)
- [Automated deployment via ansible](https://github.com/dokku/ansible-dokku)
## Installing from Source
You can always install Dokku straight from the latest - potentially unstable - `master` branch via the following Bash command:
```shell

21
docs/getting-started/install/azure.md
View File

@@ -6,6 +6,23 @@
3. You'll be prompted to enter a few parameters, including a unique storage account name and a unique name for the subdomain used for your public IP address. For the `sshKeyData` parameter, copy and paste the contents of the *public* key file you just created. After a few minutes the Dokku instance will be deployed.
4. In your browser of choice, navigate to `http://[dnsNameForPublicIP].[location].cloudapp.azure.com`. Where `[dnsNameForPublicIP]` and `[location]` are template parameters you used to deploy the template.
4. Once the installation is complete, you should configure an ssh key and set your global domain.
5. Finish your Dokku setup like you normally would by creating a *new* public/private key pair for your deployments using `ssh-keygen` (don't use the same one as you created in the first step). You should select **Use Virtual Host Naming** and set the **Hostname** to a *public DNS name* that you own such as one you would purchase from [Namecheap](http://namecheap.com). Alternatively thanks to [sslip.io](https://sslip.io/) you can just use `[yourAzurePublicIP].sslip.io` for free. For example, if your public IP is `44.44.44.44` then you would set it to `44.44.44.44.sslip.io`.
```shell
# usually your key is already available under the current user's `~/.ssh/authorized_keys` file
cat ~/.ssh/authorized_keys | dokku ssh-keys:add admin
# you can use any domain you already have access to
# this domain should have an A record or CNAME pointing at your server's IP
dokku domains:set-global dokku.me
# you can also use the ip of your server
dokku domains:set-global 10.0.0.2
# finally, you can use sslip.io to get subdomain support
# as you would with a regular domain name
# this would be done by appending `.sslip.io` to your ip address
dokku domains:set-global 10.0.0.2.sslip.io
```
See the [user management](/docs/deployment/user-management.md#adding-ssh-keys) and [domains documentation](/docs/configuration/domains.md#customizing-hostnames) for more information.

77
docs/getting-started/installation.md
View File

@@ -1,18 +1,37 @@
# Getting Started with Dokku
## What is Dokku?
### What is Dokku?
Dokku is an extensible, open source Platform as a Service that runs on a single server of your choice.
Dokku is an extensible, open source Platform as a Service that runs on a single server of your choice. Dokku supports building apps on the fly from a `git push` via either Dockerfile or by auto-detecting the language with Buildpacks, and then starts containers based on your built image. Using technologies such as nginx and cron, Web processes are automatically routed to, while background processes and automated cron tasks are also managed by Dokku.
### System Requirements
To start using Dokku, you'll need a system that meets the following minimum requirements:
- A fresh installation of [Ubuntu 18.04/20.04 x64](https://www.ubuntu.com/download), [Debian 9+ x64](https://www.debian.org/distrib/) or [CentOS 7 x64](https://www.centos.org/download/) *(experimental)* with the FQDN set <sup>[1]</sup>
- At least 1 GB of system memory <sup>[2]</sup>
- A fresh installation of any of the following operating systems:
- [Ubuntu 18.04/20.04 x64](https://www.ubuntu.com/download)
- [Debian 9+ x64](https://www.debian.org/distrib/)
- [CentOS 7 x64](https://www.centos.org/download/) *(experimental)*
- A server with one of the following architectures
- AMD64 (alternatively known as `x86_64`), commonly used for Intel cloud servers
- ARMV7 (alternatively known as `armhf`), commonly used for Raspberry PI
Dokku is designed for usage on a fresh VM installation, and should install all necessary dependencies if installing via the bootstrap method.
To avoid memory pressure during builds or runtime of your applications, we suggest the following:
- At least 1 GB of system memory
- If your system has less than 1GB of memory, you can use [this workaround](/docs/getting-started/advanced-installation.md#vms-with-less-than-1gb-of-memory).
Finally, we recommend attaching at least one domain name to your server. This is not required, but using a domain name will make app access easier. When connecting a domain, either a single domain or a wildcard may be associated to the server's IP.
- Wildcard domain (`*.domain.tld` A Record): will allow access to apps via `$APP.domain.tld`.
- Single domain (`domain.tld` A or CNAME Record): will result in apps being accessed via `domain.tld:$RANDOM_PORT`.
Please see the [dns documentation](/docs/networking/dns.md) and [domains documentation](/docs/configuration/domains.md) for more details.
### Installing the latest stable version
This is the simple method of installing Dokku. For alternative methods of installation, see the [advanced install guide](/docs/getting-started/advanced-installation.md#configuring).
#### 1. Install Dokku
To install the latest stable version of Dokku, you can run the following shell commands:
@@ -25,53 +44,29 @@ sudo DOKKU_TAG=v0.26.7 bash bootstrap.sh
The installation process takes about 5-10 minutes, depending upon internet connection speed.
If you're using Debian 9+ or Ubuntu 18.04, make sure your package manager is configured to install a sufficiently recent version of nginx<sup>[3]</sup>, otherwise, the installation may fail due to `unmet dependencies` relating nginx.
#### 2. Setup SSH key and Virtualhost Settings
#### 2. Optionally connect a domain to your server
Dokku optionally supports one or more domain names. If you do not own a domain name, you may either purchase one or skip this step.
When connecting a domain, either a single domain or a wildcard may be associated to the server's IP. A wildcard domain will allow access to apps via `$APP.domain.tld`, whereas associating only a single domain name will result in apps being access via `domain.tld:$RANDOM_PORT`. Please see the [dns documentation](/docs/networking/dns.md) and [domains documentation](/docs/configuration/domains.md) for more details.
#### 3. Setup SSH key and Virtualhost Settings
Once the installation is complete, you should configure an ssh key and set your global domain:from-archive
Once the installation is complete, you should configure an ssh key and set your global domain.
```shell
# usually your key is already available under the current user's `~/.ssh/authorized_keys` file
cat ~/.ssh/authorized_keys | dokku ssh-keys:add admin
# you can use any domain you already have access to
# this domain should have an A record or CNAME pointing at your server's IP
dokku domains:set-global dokku.me
# you can also use the ip of your server
dokku domains:set-global 10.0.0.2
# finally, you can use sslip.io to get subdomain support
# as you would with a regular domain name
# this would be done by appending `.sslip.io` to your ip address
dokku domains:set-global 10.0.0.2.sslip.io
```
See the [user management](/docs/deployment/user-management.md#adding-ssh-keys) and [domains documentation](/docs/configuration/domains.md#customizing-hostnames) for more information.
Alternatively, instructions for an unattended installation are available in the [advanced install guide](/docs/getting-started/advanced-installation.md#configuring).
#### 4. Deploy your first application
#### 3. Deploy your first application
At this point, you should be able to run or [deploy to the Dokku installation](/docs/deployment/application-deployment.md).
### 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:
- [DigitalOcean Installation Notes](/docs/getting-started/install/digitalocean.md)
- [DreamHost Cloud Installation Notes](/docs/getting-started/install/dreamhost.md)
- [Microsoft Azure Installation Notes](/docs/getting-started/install/azure.md)
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](/docs/getting-started/install/debian.md)
- [Docker-based Installation Notes](/docs/getting-started/install/docker.md)
- [RPM Package Installation Notes](/docs/getting-started/install/rpm.md)
- [Vagrant Installation Notes](/docs/getting-started/install/vagrant.md)
- [Advanced Install Customization](/docs/getting-started/advanced-installation.md)
- [Automated deployment via ansible](https://github.com/dokku/ansible-dokku)
---
- <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](/docs/getting-started/advanced-installation.md#vms-with-less-than-1gb-of-memory).</sup>
- <sup>[3]: nginx >= 1.8.0 can be installed via the [nginx repositories](https://www.nginx.com/resources/admin-guide/installing-nginx-open-source/), or by adding [this PPA](https://launchpad.net/~nginx/+archive/ubuntu/stable) if you're using Ubuntu. nginx >= 1.11.5 is necessary for HTTP/2 support</sup>