Skip to content

Commit

Permalink
Merge branch 'develop'
Browse files Browse the repository at this point in the history
  • Loading branch information
@axisofentropy
axisofentropy committed May 15, 2022
2 parents eb597a9 + 6ca9aaf commit c8bd8bd
Show file tree
Hide file tree
Showing 4 changed files with 195 additions and 89 deletions.
78 changes: 69 additions & 9 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,77 @@
## Contributing uffizzi_app
# Contributing to `uffizzi_app`

Thanks for your interest we are actively working to release uffizzi_app and define how you can contribute - please follow for updates!
Thanks for your interest! We are actively working to release `uffizzi_app` and define how you can contribute - please follow for updates!

Uffizzi welcomes contributions from everyone -
Uffizzi welcomes contributions from everyone!

## Procedures:
## Communication:

-Fork the project on Github
If you need any help contributing, several maintainers are on the Uffizzi Users Slack group https://join.slack.com/t/uffizzi/shared_invite/zt-ffr4o3x0-J~0yVT6qgFV~wmGm19Ux9A.

-Make any changes you want to uffizzi_app, commit them, and push them to your fork
## Releases

-Create a pull request against main, and a maintainer will come by and review your inputs. They may ask for some changes or more information, and hopefully your contribution will be merged to the main branch!
We're using Semantic Versioning 2.0.0 to name our release tags: https://semver.org/

## Communication:
Be sure to update the `appVersion` within `charts/uffizzi-app/Chart.yaml` whenever you create a new release! And also update the tag for `image` within `charts/uffizzi-app/values.yaml`.

## Helm Chart Releases

When you change the Helm chart, even if it's just bumping the `appVersion` and `image` tag, also increment the `version` within `charts/uffizzi-app/Chart.yaml`. This chart version does not need to match the app version, and it's probably better if it does not.

When the new `Chart.yaml` makes it into the default branch, then the `chart-releaser` GitHub Action will create a new tag with a `uffizzi-app-` prefix. It will also update our Helm repo within the `gh-pages` branch. Let the automation handle this.

# Procedures for outside collaborators:

- Fork the project on Github.

- Make any changes you want to `uffizzi_app`, commit them, and push them to your fork.

- Create a Pull Request against `UffizziCloud/uffizzi_app:main`, and a maintainer will come by and review your inputs. They may ask for some changes or more information, and hopefully your contribution will be merged to the `main` branch!

# Procedures for Uffizzi team members:

1. Clone the repository and checkout to `develop` branch.

2. Pull repository to ensure you have the latest changes.

```bash
git pull --rebase develop
```

3. Start new branch from `develop`

```bash
git checkout -b feature/ISSUE_NUMBER_short_issue_description (e.g. feature/53_add_domain_settings)
```

4. Make changes you need for the feature, commit them to the repo

```bash
git add .
git commit -m '[#ISSUE_NUMBER] short commit description' (e.g. git commit -m '[#53] added domain settings')
git push origin BRANCH_NAME
```

5. You already can create PR with develop branch as a target. Once the feature is ready let us know in the channel - we will review

6. Merge your feature to `qa` branch and push. Ensure your pipeline is successful.

```bash
git checkout qa
git pull --rebase qa
git merge --no-ff BRANCH_NAME
git push origin qa
```

# Running linter

```bash
docker-compose run --rm web bundle exec rubocop -A
```

# Running test

If you need any help contributing, several maintainers are on the uffizzi users slack group https://join.slack.com/t/uffizzi/shared_invite/zt-ffr4o3x0-J~0yVT6qgFV~wmGm19Ux9A. You'll see the channel #cp_manifesto-contributing.
```bash
docker-compose run --rm core bash
bin/rails test
```
94 changes: 28 additions & 66 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,39 @@
# Uffizzi App
# Uffizzi App

**The primary REST API for creating and managing Previews**

While it provides a documented REST API for anyone to use, it's most valuable when used with the open-source [`uffizzi_cli`](https://github.com/UffizziCloud/uffizzi_cli).
While it provides a documented REST API for anyone to use, it's most valuable when used with the open-source [`uffizzi_cli`](https://github.com/UffizziCloud/uffizzi_cli).

## Uffizzi Overview

Uffizzi is an open-source engine for creating lightweight, ephemeral preview environments for APIs and full-stack applications. Uffizzi enables teams to preview new features before merging and to mitigate the risk of introducing regressions into a codebase. Each preview gets a shareable URL that's updated when you push new commits or image tags, so teams can provide continual feedback during the iterative development process. Previews can be configured to expire at a set time or be destroyed when a pull request is closed, so environments exist only as long as they are needed. Uffizzi helps to parallelize new feature efforts by overcoming the bottleneck of shared development environments.

While Uffizzi depends on Kubernetes, it does not require end-users to interface with Kubernetes directly. Uffizzi leverages Docker Compose as its configuration file format, so developers do not need modify Kubernetes manifests or even know about Kubernetes.
While Uffizzi depends on Kubernetes, it does not require end-users to interface with Kubernetes directly. Uffizzi leverages Docker Compose as its configuration file format, so developers need not write Kubernetes manifests nor even know about Kubernetes.

Uffizzi is designed to integrate with any CI/CD system.

## Uffizzi Architecture
<img src="docs/images/uffizzi-architecture.png" description="Uffizzi Architecture" width="320"/>
## Quick Start

Uffizzi consists of the following components:
If you just want to evaluate Uffizzi, follow the [installation guide for our Helm chart](charts/uffizzi-app/README.md).

* Uffizzi App (this repository) - The primary REST API for creating and managing Previews
* [Uffizzi Controller](https://github.com/UffizziCloud/uffizzi_controller) - A smart proxy service that handles requests from Uffizzi App to the Kubernetes API
* [Uffizzi CLI](https://github.com/UffizziCloud/uffizzi_cli) - A command-line interface for Uffizzi App
In addition to the [Uffizzi CLI](https://github.com/UffizziCloud/uffizzi_cli), you can then continuously deploy previews using [our GitHub Action](https://github.com/UffizziCloud/preview-action).

Uffizzi requires the following external dependencies:
## Uffizzi Architecture
<img src="docs/images/uffizzi-architecture.png" description="Uffizzi Architecture" width="320"/>

* Kubernetes (k8s) cluster
* PostgresSQL database
* Redis cache
Uffizzi consists of the following components:

## Controller Design
* Uffizzi App (this repository) - The primary REST API for creating and managing Previews
* [Uffizzi Controller](https://github.com/UffizziCloud/uffizzi_controller) - A smart proxy service that handles requests from Uffizzi App to the Kubernetes API
* [Uffizzi CLI](https://github.com/UffizziCloud/uffizzi_cli) - A command-line interface for Uffizzi App

Uffizzi App requires the following external dependencies:

* Kubernetes (k8s) cluster
* PostgreSQL database
* Redis cache

## Controller Design

This `uffizzi_app` acts as a REST API for [`uffizzi_cli`](https://github.com/UffizziCloud/uffizzi_app) interface. It requires [`uffizzi_controller`](https://github.com/UffizziCloud/uffizzi_controller) as a supporting service.

Expand All @@ -53,6 +59,10 @@ This `uffizzi_app` acts as a REST API for [`uffizzi_cli`](https://github.com/Uff
- `CONTROLLER_LOGIN` - the login of the controller application (default: '')
- `CONTROLLER_PASSWORD` - the password of the controller application (default: '')

# Test Uffizzi App Locally

If you want to run Uffizzi on your workstation instead of using [the Helm chart](charts/uffizzi-app/README.md), then you can run it using Docker Compose.

## Prepare

```bash
Expand Down Expand Up @@ -85,8 +95,6 @@ docker-compose run --rm gem bash
bundle exec uffizzi login --hostname http://web:7000 -u [email protected]
```

password - `password`

## API Documentation

* [Development](http://lvh.me:7000/api-docs/index.html)
Expand All @@ -98,58 +106,12 @@ docker-compose run --rm core bash
bundle exec rake core:generate_docs
```

## Git workflow for the app:

1. Clone the repository and checkout to `develop` branch

2. Pull repository to ensure you have the latest changes

```bash
git pull --rebase develop
```

1. Start new branch from `develop`

```bash
git checkout -b feature/ISSUE_NUMBER_short_issue_description (e.g. feature/53_add_domain_settings)
```

1. Make changes you need for the feature, commit them to the repo

```bash
git add .
git commit -m '[#ISSUE_NUMBER] short commit description' (e.g. git commit -m '[#53] added domain settings')
git push origin BRANCH_NAME
```

1. You already can create PR with develop branch as a target. Once the feature is ready let us know in the channel - we will review

2. Merge your feature to `qa` branch and push. Ensure your pipeline is successful

```bash
git checkout qa
git pull --rebase qa
git merge --no-ff BRANCH_NAME
git push origin qa
```

# Running linter

```bash
docker-compose run --rm web bundle exec rubocop -A
```
# Health checks

# Running test
The default health check uri is `health_check`. To use a custom uri please add the `HEALTH_CHECK_URI` environment variable to the docker-compose.yml

```bash
docker-compose run --rm core bash
bin/rails test
```

# Health checks
# Contributing

The default health check uri is `health_check`. To use a custom uri please add the `HEALTH_CHECK_URI` environment
variable to the docker-compose.yml
Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) within this repository.

## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/UffizziCloud/uffizzi_app.
6 changes: 3 additions & 3 deletions charts/uffizzi-app/Chart.yaml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
apiVersion: v2
name: uffizzi-app
version: 1.1.1
version: 1.1.2
kubeVersion: ">= 1.21.0-0" # https://issuetracker.google.com/issues/77503699
description: "Uffizzi is an open-source engine for creating lightweight, ephemeral test environments for APIs and full-stack applications. Uffizzi enables teams to preview new features before merging."
type: application
Expand All @@ -24,11 +24,11 @@ dependencies:
version: "1.0.0"
repository: https://uffizzicloud.github.io/uffizzi_controller/
- name: postgresql
version: "~11.1.12"
version: "~11.1.29"
repository: https://charts.bitnami.com/bitnami
condition: postgresql.enabled
- name: redis
version: "~16.8.0"
version: "~16.8.10"
repository: https://charts.bitnami.com/bitnami
condition: redis.enabled
maintainers:
Expand Down
106 changes: 95 additions & 11 deletions charts/uffizzi-app/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,18 @@

This chart installs [Uffizzi](https://uffizzi.com), the continuous previews application. This is just a standard open-source Uffizzi setup.

## Requirements

This chart requires a Kubernetes Cluster. While it will likely function on k8s >= 1.19, we have only tested upon k8s 1.21 - 1.23.

The Cluster must be capable of provisioning `Ingress` resources that obtain public IP addresses and/or hostnames.

We've briefly tested Uffizzi on:

- Google Kubernetes Engine (GKE)
- Azure Kubernetes Service (AKS)
- Amazon Elastic Kubernetes Service (EKS)

### Dependencies

This chart depends upon three subcharts:
Expand All @@ -14,25 +26,97 @@ You can disable the `bitnami` subcharts if you want to manage your own datastore

## Configuration

### DNS
This Helm chart requires integration with your DNS records and other services, so there are several required values. Create a YAML file with these values before installing this chart. There's an example below and you can read more about Helm Values Files here: https://helm.sh/docs/chart_template_guide/values_files/

You'll want to configure the following values to include a hostname you control:
### Controller

- `app_url`
- `webHostname`
- `managed_dns_zone_dns_name`
- `uffizzi-controller.ingress.hostname`
See the [Controller's Helm Chart](https://artifacthub.io/packages/helm/uffizzi-controller/uffizzi-controller) for its configuration, including its certificate authority.

### Controller
The controller itself depends upon two other popular Helm charts:

See the Controller's Helm Chart for it's configuration, including its certificate authority.
- [`ingress-nginx`](https://kubernetes.github.io/ingress-nginx/)
- [`cert-manager`](https://cert-manager.io/docs/)

If you already have one or both of these applications installed, you may want to disable them for this Helm release. Specifically, your k8s Cluster may already have cert-manager's Custom Resource Definitions defined.

### Secrets

The following secrets are configurable:
When installing Uffizzi in a sensitive or production environment, it's important to generate strong passwords. Provide new values for the `ChangeMeNow` values in the example below.

### Example Helm Values File
Example values file with required values:

```yaml
global:
postgresql:
auth:
postgresPassword: ChangeMeNow
password: ChangeMeNow
redis:
password: ChangeMeNow
uffizzi:
controller:
password: ChangeMeNow
app_url: https://uffizzi.example.com
webHostname: uffizzi.example.com
allowed_hosts: uffizzi.example.com
managed_dns_zone_dns_name: uffizzi.example.com
uffizzi-controller:
ingress:
hostname: controller.uffizzi.example.com
clusterIssuer: "letsencrypt"
cert-email: [email protected]
```
Edit these values and save them in a file named `myvals.yaml` or similar.

## Installation

If this is your first time using Helm, consult their documentation: https://helm.sh/docs/intro/quickstart/

Begin by adding our Helm repository:

```
helm repo add uffizzi-app https://uffizzicloud.github.io/uffizzi_app/
```

Then install the lastest version as a new release using the values you specified earlier. We recommend isolating Uffizzi in its own Namespace.

```
helm install my-uffizzi-app uffizzi-app/uffizzi-app --values myvals.yaml --namespace uffizzi --create-namespace
```
If you encounter any errors here, tell us about them in [our Slack](https://join.slack.com/t/uffizzi/shared_invite/zt-ffr4o3x0-J~0yVT6qgFV~wmGm19Ux9A).
You should then see the release is installed:
```
helm list --namespace uffizzi
```
### DNS
After the Helm release is installed, add DNS records for the hostnames you specified in your values file. You can obtain the IP or hostname for Uffizzi's Ingress using `kubectl`:
```
kubectl get ingress --namespace uffizzi
```
Be sure to add a "wildcard" record for the domain specified in `managed_dns_zone_dns_name`. In the above example, that's `*.uffizzi.example.com`.
### Creating the first user
After installation, you'll need to create at least one User to access your Uffizzi installation. For now, the best way to do this is executing an interactive `rake` task within the application server container:
```
kubectl exec -it deploy/my-uffizzi-app-web --namespace uffizzi -- rake uffizzi_core:create_user
Enter User Email (default: [email protected]): [email protected]
Enter Password:
Enter Project Name (default: default):
```
## Usage
- `global.uffizzi.controller.username`
- `global.uffizzi.controller.password`
If everything went well, you can now connect to the Uffizzi API service and begin Continously Deploying Previews! Use [the Uffizzi CLI](https://github.com/UffizziCloud/uffizzi_cli) or [the Uffizzi GitHub Action](https://github.com/UffizziCloud/preview-action) or your own API client.
## More Info
Expand Down

0 comments on commit c8bd8bd

Please sign in to comment.