From 0773a5e7b6a86a1287c50fea68908195b680dcfe Mon Sep 17 00:00:00 2001 From: Vitor Mauricio Date: Thu, 7 Aug 2025 19:19:21 -0300 Subject: [PATCH 1/2] chore: refactor on installation --- docs/intro.md | 1 + docs/labs/getting-started/01-requirements.md | 6 +- docs/labs/getting-started/02-installation.md | 97 ++++++++++++-------- docusaurus.config.ts | 4 + 4 files changed, 66 insertions(+), 42 deletions(-) diff --git a/docs/intro.md b/docs/intro.md index ebddcab..8ca08c3 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -16,5 +16,6 @@ We are building a community of security enthusiasts, developers, and professiona If you are interested in joining our community, you can find us on: - [GitHub](https://github.com/opiasec/) - [Discord](https://discord.gg/hXdwCW7e87) +- [Twitter](https://twitter.com/opiasec) \ No newline at end of file diff --git a/docs/labs/getting-started/01-requirements.md b/docs/labs/getting-started/01-requirements.md index ec78b59..0f61e1a 100644 --- a/docs/labs/getting-started/01-requirements.md +++ b/docs/labs/getting-started/01-requirements.md @@ -2,17 +2,17 @@ sidebar_label: 'Requirements' --- -# 📦 Requirements +# Requirements Before you deploy, make sure you have the following: - [Docker](https://www.docker.com/) - [Docker compose](https://docs.docker.com/compose/) -- [Kind](https://kind.sigs.k8s.io/) (using external cluster is possible too) +- [Kind](https://kind.sigs.k8s.io/) (We recommend using Kind for local development, as it allows you to run Kubernetes clusters in Docker containers.) - [npm](https://www.npmjs.com/) - [nodejs](https://nodejs.org/pt) (> 18) - Makefile :::info[To contribute] -For local development and testing, you also is going to need [Go](https://go.dev/). The frontend is using [Typescript](https://www.typescriptlang.org/). +For local development and testing, you may also need [Go](https://go.dev/). The frontend is using [Angular](https://angular.dev/). ::: \ No newline at end of file diff --git a/docs/labs/getting-started/02-installation.md b/docs/labs/getting-started/02-installation.md index 9db66b1..6d96b8c 100644 --- a/docs/labs/getting-started/02-installation.md +++ b/docs/labs/getting-started/02-installation.md @@ -2,80 +2,99 @@ sidebar_label: 'Install' --- -# ⚙️ Installation +# Installation -1. Clone the project and install the frontend dependencies: +Hello! Welcome to the installation guide for the *opiasec* Labs. This guide will help you set up the Labs environment on your local machine. + +Please see the [Requirements](./01-requirements.md) page before proceeding with the installation. + +## 1. Clone +Clone the [repository](https://github.com/opiasec/labs.git). ```bash -git clone https://github.com/opiasec/opiaseclabs.git -cd opiaseclabs/front-end -npm install +git clone https://github.com/opiasec/labs.git ``` -2. To simplified deployment, we are using Makefile. First, you're going to need to setup the Kubernetes cluster: +## 2. Install Frontend Dependencies +After cloning the repository, navigate to the `front-end` directory and install the necessary dependencies using npm: ```bash -# If you're not in the root -cd ../ - -# In the root -cd kubernetes -make install +cd front-end +npm install ``` -3. Get the kubeconfig content: +## 3. (Optional) Setup Kubernetes Cluster +You need a [Kubernetes](https://kubernetes.io/) cluster to run the Labs. The Labs are designed to run in a Kubernetes environment, which allows for better scalability and management of resources. + +:::danger[Important] +Your Kubernetes cluster **must be accessible from the Docker container of Cluster API**. This is crucial for the Labs to function correctly. + +Additionally, your Kubernetes cluster must have a ingress nginx controller installed. This is necessary for routing traffic to the Labs services. +::: + +:::note[Recommendation] +We recommend to use [Kind](https://kind.sigs.k8s.io/) for local development, as it allows you to run Kubernetes clusters in Docker containers. +::: + +If you want to follow our local setup recomendations, ensure you are in the **root of the project directory** and **have Docker and Kind installed**. Then run the following commands to set up a Kubernetes cluster using Kind: ```bash -cat ~/.kube/kubeconfig > kubeconfig +make -C kubernetes install ``` -4. Open the 'kubeconfig' file with your prefered text editor and edit the *cluster server* value to **https://kind-control-plane:6443**, like the example below. - -```yaml -apiVersion: v1 -clusters: - - cluster: - certificate-authority-data: [...]d2RPK2NvemZXCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K - //highlight-next-line - server: https://kind-control-plane:6443 - name: kind-kind -contexts: - - context: - [...] -``` +## 4. Setup kubeconfig in base64 format: -5. Encode the kubeconfig modified as base64 and insert that value in **.env** (project root), in the variable **KUBECONFIG_BASE64**. +The Cluster API needs a `kubeconfig` to access the Kubernetes cluster. This needs to be a base64 encoded version of your kubeconfig file. + +1. (Optional) If you are using Kind, generate the kubeconfig file by makefile command: ```bash -cat kubeconfig | base64 -w0 +make -C kubernetes get-kubeconfig ``` +This command will create a file named `kubeconfig_base64` in the `kubernetes` directory, with the `server` endpoint setted to `https://kind-control-plane:6443` - ensuring that the Cluster API can access the Kubernetes cluster. + +2. Set the `KUBECONFIG_BASE64` environment variable with the base64 encoded kubeconfig file. You can do this setting the variable in a .env file (see [3. Set environment variables](#3-set-environment-variables)). -:::warning[External clusters] -If you already have a deployed cluster, you need to pay attention in your **kubeconfig** cluster server url and authentication methods. The docker container ***needs to be able to access the Kubernetes cluster API***. -::: -6. Go back to the project's root and update the **.env** (you can rename the .env.example). In addition to **KUBECONFIG_BASE64**, you need to update at least: +## 5. Set environment variables +Go back to the project's root and update the **.env** (you can rename the .env.example). You need to modify at least the following variables: + - **KUBECONFIG_BASE64**: with your base64 encoded kubeconfig file. For more information, see [4. Setup kubeconfig in base64 format](#4-setup-kubeconfig-in-base64-format) - **GITHUB_INIT_CONTAINER_USERNAME**: with your github username - **GITHUB_INIT_CONTAINER_PAT**: with your github personal access token, with permissions *read packages* and *read projects* (that's necessary for pulling labs repositories) +:::warning[Important] +All the variables are documented in the **.env.example** file. Please, read it carefully and set the variables accordingly. :::note[Recommendation] We do recommend to update all the *password* variables. Also, you can setup an auth provider if you want to, in section *'*Auth Provider Configuration*. The basic setup is using the **Auth Password Configuration**. + ::: -7. With all variables set, run the Make command to execute the *Docker compose* and connect the cluster container to the Labs network. +## 6. Setup Local Environment +With all variables set, run the Make command to execute the *Docker compose* and connect the cluster container to the Labs network. ```bash -# In the project's root make install ``` :::tip[External cluster] -if you have used an external cluster, use the command `make docker-compose`. +If you have used an external cluster, use the command `make docker-compose`. ::: -8. The last step is to start the front-end. Go to *front-end* folder and start the service: +## 7. Setup Frontend Environment +The last step is to start the front-end. Go to *front-end* folder and start the service: ```bash cd front-end npm start ``` -9. The project now should be up and running. Navigate to `localhost:4200` and access using the credentials you've setted up in .env. \ No newline at end of file +The project now should be up and running. Navigate to `localhost:4200` and access using the credentials you've setted up in .env. + +Have fun! + +## Extra Tips + +### Help +You can run `make help` to see all available commands and their descriptions. You can also run `make -C kubernetes help` to see the available commands for the Kubernetes setup. + + +### Need more help? +If you have any questions or need further assistance, feel free to reach out to us on our [Discord](https://discord.gg/hXdwCW7e87) or open an issue in the [Labs repository](https://github.com/opiasec/labs/issues). \ No newline at end of file diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 9c0fa0f..3e4ad12 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -125,6 +125,10 @@ const config: Config = { label: 'GitHub', href: 'https://github.com/opiasec', }, + { + label: 'opiasec.com', + href: 'https://opiasec.com', + } ], }, ], From e901f8216611a7094df8eac84f10e63a61c224a0 Mon Sep 17 00:00:00 2001 From: Vitor Mauricio Date: Thu, 7 Aug 2025 19:26:25 -0300 Subject: [PATCH 2/2] fix: changin installation.md name --- .../labs/getting-started/{02-install.md => 02-installation.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename i18n/pt-BR/docusaurus-plugin-content-docs/current/labs/getting-started/{02-install.md => 02-installation.md} (100%) diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/labs/getting-started/02-install.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/labs/getting-started/02-installation.md similarity index 100% rename from i18n/pt-BR/docusaurus-plugin-content-docs/current/labs/getting-started/02-install.md rename to i18n/pt-BR/docusaurus-plugin-content-docs/current/labs/getting-started/02-installation.md