diff --git a/content/rancher/v2.x/en/installation/single-node/_index.md b/content/rancher/v2.x/en/installation/single-node/_index.md index a78de0d4afa..1d1f2005a45 100644 --- a/content/rancher/v2.x/en/installation/single-node/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/_index.md @@ -75,46 +75,53 @@ Log into your Linux host, and then run the minimum installation command below. In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher. >**Prerequisites:** ->Create a self-signed certificate. +>Create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice. > >- The certificate files must be in [PEM format](#pem). >- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [SSL FAQ / Troubleshooting](#cert-order). -After creating your certificate, run the Docker command to install Rancher. Use the `-v` flag and provide the path to your certificates to mount them in your container. +After creating your certificate, run the Docker command below to install Rancher. Use the `-v` flag and provide the path to your certificates to mount them in your container. - docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -v /etc//:/etc/rancher/ssl/cert.pem \ - -v /etc//:/etc/rancher/ssl/key.pem \ - -v /etc//:/etc/rancher/ssl/cacerts.pem \ - rancher/rancher:latest +- Replace `` with the directory path to your certificate file. +- Replace ``,'', and `` with your certificate names. +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + rancher/rancher:latest +``` {{% /accordion %}} {{% accordion id="option-c" label="Option C—Bring Your Own Certificate: Signed by Recognized CA" %}} -If you're publishing your app publicly, you should ideally be using a certificate signed by a recognized CA. +In production environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings. ->**Prerequisites:** -> ->- The certificate files must be in [PEM format](#pem). ->- Make sure that the container includes your certificate file and the key file. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary. ->- Add `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. +>**Prerequisite:** The certificate files must be in [PEM format](#pem). -**To Install Rancher Using a Certificate Signed by a Recognized CA:** +After obtaining your certificate, run the Docker command below. -1. After obtaining your certificate, run the Docker command to deploy Rancher while pointing toward your certificate files. +- Use the `-v` flag and provide the path to your certificates to mount them in your container. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary. - ``` - docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -v /etc/your_certificate_directory/fullchain.pem:/etc/rancher/ssl/cert.pem \ - -v /etc/your_certificate_directory/privkey.pem:/etc/rancher/ssl/key.pem \ - rancher/rancher:latest --no-cacerts - ``` + - Replace `` with the directory path to your certificate file. + - Replace `` and '' with your certificate names. + +- Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + rancher/rancher:latest --no-cacerts +``` {{% /accordion %}} {{% accordion id="option-d" label="Option D—Bring Your Own Certificate: Private CA Root Certificate" %}} -Services that Rancher needs to access are sometimes configured with a certificate from an custom/internal Certificate Authority (CA) root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error will appear: `x509: certificate signed by unknown authority`. +If you're using Rancher in a internal production environment where you aren't exposing apps publicly, use a certificate from a private certificate authority (CA). + +Services that Rancher needs to access are sometimes configured with a certificate from an custom/internal CA root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error displays: `x509: certificate signed by unknown authority`. To validate the certificate, the CA root certificates need to be added to Rancher. As Rancher is written in Go, we can use the environment variable `SSL_CERT_DIR` to point to the directory where the CA root certificates are located in the container. The CA root certificates directory can be mounted using the Docker volume option (`-v host-source-directory:container-destination-directory`) when starting the Rancher container. @@ -124,14 +131,12 @@ Examples of services that Rancher can access: * Authentication providers * Accessing hosting/cloud API when using Node Drivers -#### Start Rancher Container with custom CA root certificates +Use the the command example to start a Rancher container with you private CA certificates mounted. -The requirements are: - -* Mount the host directory containing the CA root certificates in the container using the volume option. -* Add the environment variable `SSL_CERT_DIR` with as value the mounted CA root certificates directory location inside the container. - -Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`, mounting a host directory inside the container can be done using `-v host-source-directory:container-destination-directory` or `--volume host-source-directory:container-destination-directory`. +- The volume option (`-v`) should specify the host directory containing the CA root certificates. +- The `e` flag in combination with `SSL_CERT_DIR` declares an environment variable that specifies the mounted CA root certificates directory location inside the container. + - Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`. + - Mounting a host directory inside the container can be done using `-v host-source-directory:container-destination-directory` or `--volume host-source-directory:container-destination-directory`. The example below is based on having the CA root certificates in the `/host/certs` directory on the host and mounting this directory on `/container/certs` inside the Rancher container. @@ -145,7 +150,7 @@ docker run -d --restart=unless-stopped \ {{% /accordion %}} {{% accordion id="option-e" label="Option E—Let's Encrypt Certificate" %}} -Rancher supports Let's Encrypt certificates. Let's Encrypt uses an `http-01 challenge` to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS. +For production environments, you also have the options of using [Let's Encrypt](https://letsencrypt.org/) certificates. Let's Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS. >**Prerequisites:** > @@ -154,29 +159,30 @@ Rancher supports Let's Encrypt certificates. Let's Encrypt uses an `http-01 chal >- Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses. -**To Install Rancher Using a Let's Encrypt Certificate:** +After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command. Replace `` with your your domain. -Run the following commands from your Linux host. - -1. Run the Docker command. +<<<<<<< HEAD ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ rancher/rancher:latest \ --acme-domain rancher.mydomain.com ``` +======= + docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + rancher/rancher:latest \ + --acme-domain +>>>>>>> clarifying command line for single-node install -> >**Remember:** Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/). {{% /accordion %}} ## What's Next? -You have a couple of options: - -- Create a backup of your Rancher Server in case of a disaster scenario: [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/). +- **Recommended First:** Create a backup of your Rancher Server in case of a disaster scenario: [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/). - Create a Kubernetes cluster: [Provisioning Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/).
@@ -189,7 +195,7 @@ You have a couple of options: {{< persistentdata >}} -## Running `rancher/rancher` and `rancher/rancher-agent` on the same node +## Running `rancher/rancher` and `rancher/rancher-agent` on the Same Node In the situation where you want to use a single node to run Rancher and to be able to add the same node to a cluster, you have to adjust the host ports mapped for the `rancher/rancher` container.