Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update readme #171

Merged
merged 1 commit into from
Mar 13, 2024
Merged

update readme #171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 32 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,23 +25,44 @@ This can be useful in several ways:
* Use within CI to perform integration testing.
* Use as a local development environment for IDP engineers.

## Quickstart:
## Quickstart

### Running the idpbuilder
### Download and install the idpbuilder

To get started, run this command:
Download the latest release with the commands:

```bash
version=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/cnoe-io/idpbuilder/releases/latest)
version=${version##*/}
curl -L -o ./idpbuilder.tar.gz "https://github.com/cnoe-io/idpbuilder/releases/download/${version}/idpbuilder-$(uname | awk '{print tolower($0)}')-$(uname -m | sed 's/x86_64/amd64/').tar.gz"
tar xzf idpbuilder.tar.gz

./idpbuilder version
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 spaces between idpbuilder and version

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry, saw this a tad bit late. will push a quick fix for this.

# example output
# idpbuilder 0.3.0 go1.21.5 linux/amd64
```

Alternatively, you can download the latest binary from [the latest release page](https://github.com/cnoe-io/idpbuilder/releases/latest).

### Using the idpbuilder

```bash
./idpbuilder create
```

This command creates a Kubernetes Cluster (Kind cluster) with core packages installed. Core packages are Gitea, ArgoCD, and ingress-nginx.
This is the most basic command which creates a Kubernetes Cluster (Kind cluster) with the core packages installed.

<details>
<summary>What are the core packages?</summary>

* **ArgoCD** is the GitOps solution to deploy manifests to Kubernetes clusters. In this project, a package is an ArgoCD application.
* **Gitea** server is the in-cluster Git server that ArgoCD can be configured to sync resources from. You can sync from local file systems to this.
* **Ingress-nginx** is used as a method to access in-cluster resources such as ArgoCD UI and Gitea UI.

* ArgoCD is the GitOps solution to deploy manifests to Kubernetes clusters. In this project, a package is an ArgoCD application.
* Gitea server is the in-cluster Git server that ArgoCD can be configured to sync resources from. You can sync from local file systems to this.
* Ingress-nginx is used as a method to access in-cluster resources such as ArgoCD UI and Gitea UI.
See the [Architecture](#Architecture) section for more information on further information on how core packages are installed and configured.

</details>

See the [Architecture](#Architecture) section for more information on further information on how core packages are installed and configured.

Once idpbuilder finishes provisioning cluster and packages, you can access GUIs by going to the following addresses in your browser.

Expand All @@ -60,19 +81,9 @@ kubectl get secrets -n gitea gitea-admin-secret \
-o go-template='{{ range $key, $value := .data }}{{ printf "%s: %s\n" $key ($value | base64decode) }}{{ end }}'
```

### Use

Run the following command to see available flags and sub commands

```bash
# for general command information
./idpbuilder --help

# for sub command specific information
./idpbuilder create --help
```
#### Example commands

#### Examples
**For more advanced use cases, check out the [examples](./examples) directory.**

You can specify the kubernetes version by using the `--kube-version` flag. Supported versions are available [here](https://github.com/kubernetes-sigs/kind/releases).

Expand Down Expand Up @@ -227,7 +238,7 @@ spec:

## Developer notes

If you want to contribute and extend the existing project, make sure that you have installed go (>= 1.20) and cloned this project.
If you want to contribute and extend the existing project, make sure that you have installed go (>= 1.21) and cloned this project.
Next, you can build it `make` or launch the `main.go` within your IDE or locally `./idpbuilder`.

You can override the kind configuration generated by the idpbuilder. For that purpose, look to the
Expand Down
4 changes: 2 additions & 2 deletions examples/ref-implementation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Ensure you have the following tools installed on your computer.

**Required**

- [idpbuilder](https://github.com/cnoe-io/idpbuilder/releases/latest): version `0.0.2` or later
- [idpbuilder](https://github.com/cnoe-io/idpbuilder/releases/latest): version `0.3.0` or later
- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl): version `1.27` or later
- Your computer should have at least 6 GB RAM allocated to Docker. If you are on Docker Desktop, see [this guide](https://docs.docker.com/desktop/settings/mac/).

Expand Down Expand Up @@ -55,7 +55,7 @@ The only package that cannot be removed this way is Keycloak because other packa

#### Accessing UIs
- Argo CD: https://cnoe.localtest.me:8443/argocd
- Argo Workflows: https://cnoe.localtest.me:8443/argo
- Argo Workflows: https://cnoe.localtest.me:8443/argo-workflows
- Backstage: https://cnoe.localtest.me:8443/
- Gitea: https://cnoe.localtest.me:8443/gitea
- Keycloak: https://cnoe.localtest.me:8443/keycloak/admin/master/console/
Expand Down
2 changes: 2 additions & 0 deletions examples/ref-implementation/codespaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ Once idpbuilder finishes bootstrapping, you should have port 8080 forward in the
You may get a 404 page after clicking the port 8080 forwarded address. This is completely normal because Backstage may not be ready yet.
Give it a few more minutes and it should redirect you to a Backstage page.

### Accessing UIs

If you'd like to track progress of deployment, go to `/argocd` path and login with your ArgoCD credentials.
For example run this command to get the URL for Argo CD:
```bash
Expand Down
Loading