|
1 | 1 | # Installation |
2 | | -We will walk you through the steps to set up a functioning local setup using KIND (Kubernetes IN Docker). |
3 | | -OpenMFP leverages [Flux](https://fluxcd.io/), a tool designed to keep Kubernetes clusters synchronized with configuration sources, alongside [Kustomize](https://kustomize.io/), a standalone tool for customizing Kubernetes resources. |
4 | | -Together, these tools enable efficient and automated cluster management. |
5 | | - |
6 | | -We will configure Flux to install, test and upgrade a demo app using |
7 | | -`OCIRepository` and `HelmRelease` custom resources. |
8 | | -Flux will monitor the Helm repository, and it will automatically |
9 | | -upgrade the Helm releases to their latest chart version based on semver ranges. |
10 | | - |
11 | | -By the end, you'll have a working setup ready to explore the full potential of OpenMFP while managing your cluster efficiently. |
12 | | - |
13 | | -## Prerequisites |
14 | | - |
15 | | -1. **Container Runtime** |
16 | | - Install either [Docker](https://www.docker.com) or [Podman](https://podman.io) to run the kind cluster: |
17 | | - - **Docker**: Version `27.0.0` or higher. Installation Guide [Get Docker](https://docs.docker.com/get-docker/) |
18 | | - - **Podman**: Version `5.1.0` or higher. Installation Guide [Install Podman](https://podman.io/get-started) |
19 | | - Ensure Docker or Podman is configured to use at least 12GB of memory. |
20 | | - |
21 | | - For Podman you will need to run: |
22 | | - ```sh |
23 | | - podman machine stop |
24 | | - podman machine init --rootful --memory=12240 |
25 | | - podman machine start |
26 | | - ``` |
27 | | - |
28 | | - For Docker you will need to go to Docker Desktop -> Settings -> Resources -> Advanced and set the memory to 12GB. |
29 | | - |
30 | | -2. **Kind (Kubernetes IN Docker)** |
31 | | - To set up a local Kubernetes cluster, use [Kind](https://kind.sigs.k8s.io/). Follow the [Kind Quick Start](https://kind.sigs.k8s.io/docs/user/quick-start/) guide for more details. For macOS Installation via [Homebrew](https://brew.sh/) run: |
32 | | - ```sh |
33 | | - brew install kind |
34 | | - ``` |
35 | | - |
36 | | -3. **Helm** |
37 | | - [Helm](https://helm.sh/) is required to bootstrap Flux. You can find detailed installation instructions [here](https://helm.sh/docs/intro/install/). For macOS Installation via Homebrew run: |
38 | | - ```sh |
39 | | - brew install helm |
40 | | - ``` |
41 | | - |
42 | | -4. **Kubectl** |
43 | | - [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) is the Kubernetes command-line tool. You can install it using the following command: |
44 | | - ```sh |
45 | | - brew install kubectl |
46 | | - ``` |
47 | | - For more installation options, refer to the [Kubectl Installation Guide](https://kubernetes.io/docs/tasks/tools/install-kubectl/). |
48 | | - |
49 | | -5. **GitHub setup** |
50 | | - Set `GH_USER` or install the [GitHub CLI](https://cli.github.com/) to setup your environment for Flux: |
51 | | - - Specify your GitHub username by setting the `GH_USER` environment variable: |
52 | | - ```sh |
53 | | - export GH_USER=<your-github-username> |
54 | | - ``` |
55 | | - - Alternatively, install the GitHub CLI For macOS Installation via Homebrew run: |
56 | | - ```sh |
57 | | - brew install gh |
58 | | - ``` |
59 | | - |
60 | | - Set a GitHub token to enable pulling OpenMFP Docker images, this token should have the `read:packages` scope. |
61 | | - ```sh |
62 | | - export GH_TOKEN=<your-github-token> |
63 | | - ``` |
64 | | - |
65 | | -6. **Keycloak (Authentication Setup - Optional)** |
66 | | - You only need this step if you plan to use your own [Keycloak](https://www.keycloak.org/) instance. If not, a default Keycloak will be installed automatically during the setup process. |
67 | | - To use your own Keycloak, set up the client secret as an environment variable: |
68 | | - ```sh |
69 | | - export KEYCLOAK_SECRET=<keycloak-client-secret> |
70 | | -
|
71 | | -7. **Free Port 8000** |
72 | | - The local OpenMFP portal will use port `8000`. Ensure this port is not in use by another application before proceeding. |
73 | | - - On Linux/macOS, you can check and free the port with the following commands: |
74 | | - ```sh |
75 | | - lsof -i :8000 |
76 | | - kill -9 <PID> # Replace <PID> with the process ID using the port |
77 | | - ``` |
78 | | -
|
79 | | -## Bootstrap local environment |
80 | | -Once the prerequisites are in place, follow these steps to set up the local environment: |
81 | | -
|
82 | | -1. **Clone the OpenMFP Repository** |
83 | | - Start by cloning the OpenMFP Helm charts repository: |
84 | | -
|
85 | | - ```sh |
86 | | - git clone https://github.com/openmfp/helm-charts |
87 | | - cd helm-charts |
88 | | - ``` |
89 | | -
|
90 | | -2. **Run the Bootstrap Script** |
91 | | - The repository includes a script `local-setup/scripts/start.sh`, it contains all steps needed to bootstrap the local environment. |
92 | | - The script will take some time and it automate the following steps: |
93 | | - - Create kind cluster called `openmfp` |
94 | | - - Install flux |
95 | | - - Prepare secrets |
96 | | - - Apply flux deployment configuration |
97 | | -
|
98 | | - To start the bootstrapping and local installation, run the following command: |
99 | | - ```sh |
100 | | - ./local-setup/scripts/start.sh |
101 | | - ``` |
102 | | -
|
103 | | -3. **Access the Local Environment** |
104 | | -Once the bootstrap process finishes, you can access the local Demo OpenMFP Portal at: http://localhost:8000 |
105 | | -
|
106 | | -## Remove the Cluster |
107 | | -
|
108 | | -If you want to delete the local environment and remove the KIND cluster, run the following command: |
109 | | -
|
110 | | -```sh |
111 | | -kind delete cluster --name openmfp |
112 | | -``` |
113 | | -If the deletion is stuck validate that the container runtime (Docker or Podman) is started and running. |
| 2 | +This guide walks through how to get started creating your very own OpenMFP Portal. |
| 3 | + |
| 4 | +## Summary |
| 5 | +We will walk you through the steps to set up your very own portal. By the end of this guide, you will have a standalone Portal running locally. To be clear, this is not a production-ready installation, and it does not contain information specific to your needs. |
| 6 | + |
| 7 | +:::info Contributors |
| 8 | +If you are planning to contribute a new feature or bug fix to the OpenMFP project, we advise you to follow the Contributors guide. |
| 9 | +::: |
| 10 | + |
| 11 | +## Prerequisites |
| 12 | + |
| 13 | +This guide also assumes that you have some experience with the terminal, specifically, these commands: `npm`, `npx`. |
114 | 14 |
|
115 | | -## Troubleshooting |
| 15 | +- [Node.js](https://nodejs.org/en) installed using one of these |
| 16 | + methods: |
| 17 | + - Using `nvm` (recommended) |
| 18 | + - [Installing nvm](https://github.com/nvm-sh/nvm#install--update-script) |
| 19 | + - [Install and change Node version with nvm](https://nodejs.org/en/download/package-manager/#nvm) |
| 20 | + - Node 24 is a good starting point, this can be installed using `nvm install 24` |
| 21 | + - [Binary Download](https://nodejs.org/en/download/) |
| 22 | + - [Package manager](https://nodejs.org/en/download/package-manager/) |
| 23 | + - [Using NodeSource packages](https://github.com/nodesource/distributions/blob/master/README.md) |
116 | 24 |
|
117 | | -If the bootstrap script does not successfully finish, connect to the `kind-openmfp` cluster, take the following steps to investigate: |
| 25 | +## Create your Portal |
| 26 | +Once the prerequisites are in place, follow these steps to set up your Portal: |
118 | 27 |
|
119 | | -1. Verify the cluster is running and accessible: |
120 | | -```sh |
121 | | -kubectl cluster-info --context kind-openmfp |
| 28 | +To install the Portal, we will make use of `npx`. `npx` is a tool that comes preinstalled with Node.js and lets you run commands straight from `npm` or other registries. Before we run the command, let's discuss what it does. |
| 29 | + |
| 30 | +This command will: |
| 31 | + - create a new directory with a Portal inside. |
| 32 | + - Generate all necessary configuration file |
| 33 | + - Set up frontend and backend structures |
| 34 | + - Display the complete project structure |
| 35 | + - Install all dependencies automatically |
| 36 | + |
| 37 | +```bash |
| 38 | +npx @openmfp/create-portal@latest |
122 | 39 | ``` |
123 | 40 |
|
124 | | -2. Identify any pods that are not in the `Running` status: |
125 | | -```sh |
126 | | -kubectl get pods --all-namespaces | grep -v Running |
| 41 | +Also you can provide a name to your portal by passing it as argument. |
| 42 | + |
| 43 | +```bash |
| 44 | +npx @openmfp/create-portal@latest my-awesome-portal |
127 | 45 | ``` |
128 | 46 |
|
129 | | -3. For pods that are stuck or failing, inspect the events for more details: |
130 | | -```sh |
131 | | -kubectl describe pod <pod-name> -n <namespace> |
| 47 | +This name will be used as subdirectory in your current working directory. |
| 48 | + |
| 49 | +:::info |
| 50 | +If you face any issue with this tool you can visit troubleshoot section in [github](https://github.com/openmfp/create-portal?tab=readme-ov-file#troubleshooting) |
| 51 | +::: |
| 52 | + |
| 53 | +## 2. Run the Portal |
| 54 | + |
| 55 | +Your Portal is fully installed and ready to be run! Now that the installation is complete, you can go to the application directory and start the app using the `npm start` command. The `npm start` command will run both the frontend and backend as separate processes in the same terminal. |
| 56 | + |
| 57 | +```bash |
| 58 | +cd my-portal # your app name |
| 59 | +npm start |
132 | 60 | ``` |
133 | | -Review the `Events` section in the output to pinpoint and address the underlying issue. |
134 | 61 |
|
135 | | -4. If the issue is related to memory constraints, increase the memory allocation for Docker or Podman as described in the Prerequisites section. |
| 62 | + |
| 63 | + |
| 64 | +Then you can visit `localhost:4300` to start exploring Portal immediately. |
| 65 | + |
| 66 | + |
| 67 | + |
| 68 | +## Recap |
| 69 | + |
| 70 | +This tutorial walked through how to create your own Portal using the `npx @openmfp/create-portal@latest` command. That command created a new directory that holds your new Portal. |
| 71 | + |
| 72 | +### Create a Microfrontend |
| 73 | + |
| 74 | +Now when you have your portal running locally, you can create a new micro frontend and connect it to your portal. Follow the steps in the [Create Microfrontend Guide](/documentation/getting-started/create-microfrontend). |
0 commit comments