From 6895f84525858aafd0bd76ef35eafd28a01b89e4 Mon Sep 17 00:00:00 2001 From: ViktarStarastsenka <99594890+ViktarStarastsenka@users.noreply.github.com> Date: Wed, 31 Jan 2024 21:20:10 +0100 Subject: [PATCH] Docker documentation (#2623) * Create install-on-aws * adding description for RedisInsight on Docker * Update configuration.md * Update configuration.md * Update configuration.md * Update install-on-aws.md * Update install-on-aws.md * Update install-on-aws.md * Update install-on-docker.md * Update install-on-aws.md * Update install-on-docker.md * Update install-on-k8s.md * Update configuration.md * Update and rename configuration.md to env_variables.md * Update env_variables.md * Update and rename env_variables.md to env-variables.md * Update env-variables.md * Update install-on-aws.md * Update install-on-docker.md * Update install-on-k8s.md * Update install-on-k8s.md adding the health check * Update install-on-docker.md * Update install-on-aws.md * Update env-variables.md * Update env-variables.md * Update install-on-docker.md * Update install-on-aws.md * Update install-on-docker.md * Update install-on-k8s.md * Update install-on-k8s.md * Updating RedisInsight on Docker * Updating RedisInsight on Docker * Update install-on-aws.md * Update install-on-aws.md * Update install-on-k8s.md * Update env-variables.md * Update install-on-k8s.md * Update env-variables.md * Update install-on-docker.md * Update install-on-aws.md * Update install-on-docker.md * Update install-on-docker.md * Update install-on-aws.md * Update install-on-docker.md * Update env-variables.md --- docs/install/install-redisinsight/_index.md | 9 + .../install-redisinsight/env-variables.md | 19 ++ .../install-redisinsight/install-on-aws.md | 92 ++++++ .../install-redisinsight/install-on-docker.md | 34 +++ .../install-redisinsight/install-on-k8s.md | 267 ++++++++++++++++++ 5 files changed, 421 insertions(+) create mode 100644 docs/install/install-redisinsight/_index.md create mode 100644 docs/install/install-redisinsight/env-variables.md create mode 100644 docs/install/install-redisinsight/install-on-aws.md create mode 100644 docs/install/install-redisinsight/install-on-docker.md create mode 100644 docs/install/install-redisinsight/install-on-k8s.md diff --git a/docs/install/install-redisinsight/_index.md b/docs/install/install-redisinsight/_index.md new file mode 100644 index 000000000..a45a4defc --- /dev/null +++ b/docs/install/install-redisinsight/_index.md @@ -0,0 +1,9 @@ +--- +title: "Install RedisInsight" +linkTitle: "Install RedisInsight" +weight: 3 +description: > + Install RedisInsite on AWS, Docker, and Kubernetes +--- + +This is a an installation guide. You'll learn how to install RedisInsight on Amazon Web Services (AWS), Docker, and Kubernetes. \ No newline at end of file diff --git a/docs/install/install-redisinsight/env-variables.md b/docs/install/install-redisinsight/env-variables.md new file mode 100644 index 000000000..dbf115bcf --- /dev/null +++ b/docs/install/install-redisinsight/env-variables.md @@ -0,0 +1,19 @@ +--- +title: "Environment variables" +linkTitle: "Environment variables" +weight: 1 +description: > + RedisInsight supported environment variables +--- +You can configure RedisInsight with the following environment variables. + +| Variable | Purpose | Default | Additional info | +| --- | --- | --- | --- | +| RI_APP_PORT | The port that RedisInsight listens on | | See [Express Documentation](https://expressjs.com/en/api.html#app.listen)| +| RI_APP_HOST | The host that RedisInsight connects to | | See [Express Documentation](https://expressjs.com/en/api.html#app.listen)| +| RI_SERVER_TLS_KEY | Private key for HTTPS | n/a | Private key in [PEM format](https://www.ssl.com/guide/pem-der-crt-and-cer-x-509-encodings-and-conversions/#ftoc-heading-3). Can be a path to a file or a string in PEM format.| +| RI_SERVER_TLS_CERT | Certificate for supplied private key | n/a | Public certificate in [PEM format](https://www.ssl.com/guide/pem-der-crt-and-cer-x-509-encodings-and-conversions/#ftoc-heading-3). Can be a path to a file or a string in PEM format.| +| RI_ENCRYPTION_KEY | Key to encrypt data with | n/a | Available only for Docker.
Redisinsight stores sensitive information (database passwords, Workbench history, etc.) locally (using [sqlite3](https://github.com/TryGhost/node-sqlite3)). This variable allows you to store sensitive information encrypted using the specified encryption key.
Note: The same encryption key should be provided for subsequent `docker run` commands with the same volume attached to decrypt the information. | +| RI_LOG_LEVEL | Configures the log level of the application. | `info` | Supported logging levels are prioritized from highest to lowest: | +| RI_FILES_LOGGER | Log to file | `true` | By default, you can find log files in the following folders: | +| RI_STDOUT_LOGGER | Log to STDOUT | `true` | | diff --git a/docs/install/install-redisinsight/install-on-aws.md b/docs/install/install-redisinsight/install-on-aws.md new file mode 100644 index 000000000..93fe59299 --- /dev/null +++ b/docs/install/install-redisinsight/install-on-aws.md @@ -0,0 +1,92 @@ +--- +title: "Install on AWS EC2" +linkTitle: "Install on AWS EC2" +weight: 3 +description: > + How to install RedisInsight on AWS EC2 +--- +This tutorial shows you how to install RedisInsight on an AWS EC2 instance and manage ElastiCache Redis instances using RedisInsight. To complete this tutorial you must have access to the AWS Console and permissions to launch EC2 instances. + +Step 1: Create a new IAM Role (optional) +-------------- + +RedisInsight needs read-only access to S3 and ElastiCache APIs. This is an optional step. + +1. Log in to the AWS Console and navigate to the IAM screen. +1. Create a new IAM Role. +1. Under *Select type of trusted entity*, choose EC2. The role is used by an EC2 instance. +1. Assign the following permissions: + * AmazonS3ReadOnlyAccess + * AmazonElastiCacheReadOnlyAccess + +Step 2: Launch EC2 Instance +-------------- + +Next, launch an EC2 instance. + +1. Navigate to EC2 under AWS Console. +1. Click Launch Instance. +1. Choose 64-bit Amazon Linux AMI. +1. Choose at least a t2.medium instance. The size of the instance depends on the memory used by your ElastiCache instance that you want to analyze. +1. Under Configure Instance: + * Choose the VPC that has your ElastiCache instances. + * Choose a subnet that has network access to your ElastiCache instances. + * Ensure that your EC2 instance has a public IP Address. + * Assign the IAM role that you created in Step 1. +1. Under the storage section, allocate at least 100 GiB storage. +1. Under security group, ensure that: + * Incoming traffic is allowed on port 5540 + * Incoming traffic is allowed on port 22 only during installation +1. Review and launch the ec2 instance. + +Step 3: Verify permissions and connectivity +---------- + +Next, verify that the EC2 instance has the required IAM permissions and can connect to ElastiCache Redis instances. + +1. SSH into the newly launched EC2 instance. +1. Open a command prompt. +1. Run the command `aws s3 ls`. This should list all S3 buckets. + 1. If the `aws` command cannot be found, make sure your EC2 instance is based of Amazon Linux. +1. Next, find the hostname of the ElastiCache instance you want to analyze and run the command `echo info | nc 6379`. +1. If you see some details about the ElastiCache Redis instance, you can proceed to the next step. +1. If you cannot connect to redis, you should review your VPC, subnet, and security group settings. + +Step 4: Install Docker on EC2 +------- + +Next, install Docker on the EC2 instance. Run the following commands: + +1. `sudo yum update -y` +1. `sudo yum install -y docker` +1. `sudo service docker start` +1. `sudo usermod -a -G docker ec2-user` +1. Log out and log back in again to pick up the new docker group permissions. +1. To verify, run `docker ps`. You should see some output without having to run `sudo`. + +Step 5: Run RedisInsight in the Docker container +------- + +Finally, install RedisInsight using one of the options described below. + +1. If you do not want to persist your RedisInsight data: + +```bash +docker run -d --name redisinsight -p 5540:5540 redis/redisinsight:latest +``` +2. If you want to persist your RedisInsight data, first attach the Docker volume to the `/data` path and then run the following command: + +```bash +docker run -d --name redisinsight -p 5540:5540 redis/redisinsight:latest -v redisinsight:/data +``` + +If the previous command returns a permission error, ensure that the user with `ID = 1000` has the necessary permission to access the volume provided (`redisinsight` in the command above). + +Find the IP Address of your EC2 instances and launch your browser at `http://:5540`. Accept the EULA and start using RedisInsight. + +RedisInsight also provides a health check endpoint at `http://:5540/api/health/` to monitor the health of the running container. + +Summary +------ + +In this guide, we installed RedisInsight on an AWS EC2 instance running Docker. As a next step, you should add an ElastiCache Redis Instance and then run the memory analysis. diff --git a/docs/install/install-redisinsight/install-on-docker.md b/docs/install/install-redisinsight/install-on-docker.md new file mode 100644 index 000000000..c73a15ea9 --- /dev/null +++ b/docs/install/install-redisinsight/install-on-docker.md @@ -0,0 +1,34 @@ +--- +title: "Install on Docker" +linkTitle: "Install on Docker" +weight: 2 +description: > + How to install RedisInsight on Docker +--- +This tutorial shows how to install RedisInsight on [Docker](https://www.docker.com/) so you can use RedisInsight in development. +See a separate guide for installing [RedisInsight on AWS](/docs/install/install-redisinsight/install-on-aws/). + +## Install Docker + +The first step is to [install Docker for your operating system](https://docs.docker.com/install/). + +## Run RedisInsight Docker image + +You can install RedisInsight using one of the options described below. + +1. If you do not want to persist your RedisInsight data: + +```bash +docker run -d --name redisinsight -p 5540:5540 redis/redisinsight:latest +``` +2. If you want to persist your RedisInsight data, first attach the Docker volume to the `/data` path and then run the following command: + +```bash +docker run -d --name redisinsight -p 5540:5540 redis/redisinsight:latest -v redisinsight:/data +``` + +If the previous command returns a permission error, ensure that the user with `ID = 1000` has the necessary permissions to access the volume provided (`redisinsight` in the command above). + +Next, point your browser to `http://localhost:5540`. + +RedisInsight also provides a health check endpoint at `http://localhost:5540/api/health/` to monitor the health of the running container. diff --git a/docs/install/install-redisinsight/install-on-k8s.md b/docs/install/install-redisinsight/install-on-k8s.md new file mode 100644 index 000000000..8a42865fe --- /dev/null +++ b/docs/install/install-redisinsight/install-on-k8s.md @@ -0,0 +1,267 @@ +--- +title: "Install on Kubernetes" +linkTitle: "Install on Kubernetes" +weight: 4 +description: > + How to install RedisInsight on Kubernetes +--- +This tutorial shows how to install RedisInsight on [Kubernetes](https://kubernetes.io/) (K8s). +This is an easy way to use RedisInsight with a [Redis Enterprise K8s deployment](https://redis.io/docs/about/redis-enterprise/#:~:text=and%20Multi%2Dcloud-,Redis%20Enterprise%20Software,-Redis%20Enterprise%20Software). + +## Create the RedisInsight deployment and service + +Below is an annotated YAML file that will create a RedisInsight +deployment and a service in a K8s cluster. + +1. Create a new file named `redisinsight.yaml` with the content below. + +```yaml +# RedisInsight service with name 'redisinsight-service' +apiVersion: v1 +kind: Service +metadata: + name: redisinsight-service # name should not be 'redisinsight' + # since the service creates + # environment variables that + # conflicts with redisinsight + # application's environment + # variables `RI_APP_HOST` and + # `RI_APP_PORT` +spec: + type: LoadBalancer + ports: + - port: 80 + targetPort: 5540 + selector: + app: redisinsight +--- +# RedisInsight deployment with name 'redisinsight' +apiVersion: apps/v1 +kind: Deployment +metadata: + name: redisinsight #deployment name + labels: + app: redisinsight #deployment label +spec: + replicas: 1 #a single replica pod + selector: + matchLabels: + app: redisinsight #which pods is the deployment managing, as defined by the pod template + template: #pod template + metadata: + labels: + app: redisinsight #label for pod/s + spec: + containers: + + - name: redisinsight #Container name (DNS_LABEL, unique) + image: redis/redisinsight:latest #repo/image + imagePullPolicy: IfNotPresent #Installs the latest RedisInsight version + volumeMounts: + - name: redisinsight #Pod volumes to mount into the container's filesystem. Cannot be updated. + mountPath: /data + ports: + - containerPort: 5540 #exposed container port and protocol + protocol: TCP + volumes: + - name: redisinsight + emptyDir: {} # node-ephemeral volume https://kubernetes.io/docs/concepts/storage/volumes/#emptydir +``` + +2. Create the RedisInsight deployment and service: + +```sh +kubectl apply -f redisinsight.yaml +``` + +3. Once the deployment and service are successfully applied and complete, access RedisInsight. This can be accomplished by using the `` of the service we created to reach RedisInsight. + +```sh +$ kubectl get svc redisinsight-service +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +redisinsight-service 80:32143/TCP 1m +``` + +4. If you are using minikube, run `minikube list` to list the service and access RedisInsight at `http://:`. +``` +$ minikube list +|-------------|----------------------|--------------|---------------------------------------------| +| NAMESPACE | NAME | TARGET PORT | URL | +|-------------|----------------------|--------------|---------------------------------------------| +| default | kubernetes | No node port | | +| default | redisinsight-service | 80 | http://: | +| kube-system | kube-dns | No node port | | +|-------------|----------------------|--------------|---------------------------------------------| +``` + +## Create the RedisInsight deployment with persistant storage + +Below is an annotated YAML file that will create a RedisInsight +deployment in a K8s cluster. It will assign a peristent volume created from a volume claim template. +Write access to the container is configured in an init container. When using deployments +with persistent writeable volumes, it's best to set the strategy to `Recreate`. Otherwise you may find yourself +with two pods trying to use the same volume. + +1. Create a new file `redisinsight.yaml` with the content below. + +```yaml +# RedisInsight service with name 'redisinsight-service' +apiVersion: v1 +kind: Service +metadata: + name: redisinsight-service # name should not be 'redisinsight' + # since the service creates + # environment variables that + # conflicts with redisinsight + # application's environment + # variables `RI_APP_HOST` and + # `RI_APP_PORT` +spec: + type: LoadBalancer + ports: + - port: 80 + targetPort: 5540 + selector: + app: redisinsight +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: redisinsight-pv-claim + labels: + app: redisinsight +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: default +--- +# RedisInsight deployment with name 'redisinsight' +apiVersion: apps/v1 +kind: Deployment +metadata: + name: redisinsight #deployment name + labels: + app: redisinsight #deployment label +spec: + replicas: 1 #a single replica pod + strategy: + type: Recreate + selector: + matchLabels: + app: redisinsight #which pods is the deployment managing, as defined by the pod template + template: #pod template + metadata: + labels: + app: redisinsight #label for pod/s + spec: + volumes: + - name: redisinsight + persistentVolumeClaim: + claimName: redisinsight-pv-claim + initContainers: + - name: init + image: busybox + command: + - /bin/sh + - '-c' + - | + chown -R 1001 /data + resources: {} + volumeMounts: + - name: redisinsight + mountPath: /data + terminationMessagePath: /dev/termination-log + terminationMessagePolicy: File + containers: + - name: redisinsight #Container name (DNS_LABEL, unique) + image: redis/redisinsight:latest #repo/image + imagePullPolicy: IfNotPresent #Always pull image + volumeMounts: + - name: redisinsight #Pod volumes to mount into the container's filesystem. Cannot be updated. + mountPath: /data + ports: + - containerPort: 5540 #exposed container port and protocol + protocol: TCP +``` + +2. Create the RedisInsight deployment and service. + +```sh +kubectl apply -f redisinsight.yaml +``` + +## Create the RedisInsight deployment without a service. + +Below is an annotated YAML file that will create a RedisInsight +deployment in a K8s cluster. + +1. Create a new file redisinsight.yaml with the content below + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: redisinsight #deployment name + labels: + app: redisinsight #deployment label +spec: + replicas: 1 #a single replica pod + selector: + matchLabels: + app: redisinsight #which pods is the deployment managing, as defined by the pod template + template: #pod template + metadata: + labels: + app: redisinsight #label for pod/s + spec: + containers: + - name: redisinsight #Container name (DNS_LABEL, unique) + image: redis/redisinsight:latest #repo/image + imagePullPolicy: IfNotPresent #Always pull image + env: + # If there's a service named 'redisinsight' that exposes the + # deployment, we manually set `RI_APP_HOST` and + # `RI_APP_PORT` to override the service environment + # variables. + - name: RI_APP_HOST + value: "0.0.0.0" + - name: RI_APP_PORT + value: "5540" + volumeMounts: + - name: redisinsight #Pod volumes to mount into the container's filesystem. Cannot be updated. + mountPath: /data + ports: + - containerPort: 5540 #exposed container port and protocol + protocol: TCP + livenessProbe: + httpGet: + path : /healthcheck/ # exposed RI endpoint for healthcheck + port: 5540 # exposed container port + initialDelaySeconds: 5 # number of seconds to wait after the container starts to perform liveness probe + periodSeconds: 5 # period in seconds after which liveness probe is performed + failureThreshold: 1 # number of liveness probe failures after which container restarts + volumes: + - name: redisinsight + emptyDir: {} # node-ephemeral volume https://kubernetes.io/docs/concepts/storage/volumes/#emptydir +``` + +2. Create the RedisInsight deployment + +```sh +kubectl apply -f redisinsight.yaml +``` + +{{< alert title="Note" >}} +If the deployment will be exposed by a service whose name is 'redisinsight', set `RI_APP_HOST` and `RI_APP_PORT` environment variables to override the environment variables created by the service. +{{< /alert >}} + +3. Once the deployment has been successfully applied and the deployment is complete, access RedisInsight. This can be accomplished by exposing the deployment as a K8s Service or by using port forwarding, as in the example below: + +```sh +kubectl port-forward deployment/redisinsight 5540 +``` + +Open your browser and point to