This is a guided intro to Uffizzi that will demonstrate its core capabilities, how it works, and use case(s).
Setting up Continuous Previews (CP) to share, review, and test our in-progress topic branch development is one of our first steps on the journey from Code to Cloud. First we CP, then we CI / CD.
Prior to beginning we will need the following:
1. Docker Hub Account - sign up for free @ https://hub.docker.com/
2. Github Account - sign up for free @ https://github.com/join
3. Uffizzi account - Either the cloud-hosted offering or your Kubernetes administrator has installed the self-hosted version on your organization's cluster(s)
First let's review why we're setting up CP
Uffizzi's Continuous Previews (CP) will benefit your team in these ways:
Easily and quickly share in-progress development with your entire team. Peer Review and QA can begin as soon as a Developer begins work on a branch so that when you’re ready to merge there’s little left to be tested. This will increase your team’s overall development velocity and application stability. Take a look at www.cpmanifesto.org for more on how the CP method will accelerate your release cycles.
Integration of Combined Content for Micro-services Applications
Easily pull and combine your mix of app components (your custom code & commonly used base images) for previewing and testing your complex application. Throughout this Getting Started Guide we will be leveraging three Docker Official images (nginx, redis, and postgres) to reduce the time it takes to get the demo app up and working.
Isolating Function Testing from Integration Testing
When QA-ing topic branches with Uffizzi you can end to end test the feature in isolation prior to merging with other new branches. Then, after merging, you can focus on integration testing and reduce time spent debugging. This method follows the principle of Separation of concerns and ultimately simplifies how you test your code. Function Test, then Integration Test.
More resources available to the Developer
Local machines can get bogged down particularly if you’re working with micro-services and complex applications. With Uffizzi you have a scalable environment backed by Kubernetes with significant amounts of memory and processing available.
Developing and Testing in a production-like environment
The Uffizzi-managed cloud environment more closely resembles production compared to your local runtime environment. For organizations that utilize Kubernetes in production this will be a very close simulation. For customers that use self-hosted Uffizzi you can match or very nearly match (isomorphically) your production environment.
Integrate with our current Ecosystem
In addition to a fully managed cloud offering, Uffizzi offers a self-hosted option that is compatible with any Kubernetes cluster including AWS’ EKS, GCP’s GKE, Azure’s AKS, and on-premise configurations.
Now let's get started with Phase I - Getting to a Template
Step 0. Prep work on Github-
Fork this public repo and copy to your Github account -
From within the new Github repo create a new topic branch and let’s call it “change-color”.
Step 1. Sign Up-
Go to the URL that has been provided
Step 2. Account Set Up
First we'll ensure that we are connected to our Docker Hub and Github accounts. We will not be able to deploy anything without connecting to at least one of these. If logging in to Docker Hub with an Access Token, we can set the token permission level to Read-only.
When complete navigate back to the Main Dashboard to Create a Project
Step 3. Create a New Project
Step 4. Setting up the Project
We will Preview the Vote App which is powered by six containers. Three containers are Docker Hub Official Images and three containers are custom images that are built from our Github repositories.
Figure 1- Vote App Architecture
nginx container routes HTTP traffic to both the
results containers. The
vote container accepts the user's votes and submits them to the
redis memorystore container. The
worker container then pulls the votes from
redis, processes them and writes to the
postgres container. The
results container renders voting results to the user's web browser. Note that the
worker container also defines the database schema when it starts.
Now let's set up our project and start building our Preview.
First add any necessary supporting elements i.e. Backing Services or Configurations to the Project.
For the Voting App preview, we will need to upload the below Config File.
Copy and Paste this Config- (later this will be applied to nginx to route incoming requests between two of the containers in this deployment)
Name the File vote.conf and Save (*for this demo the file must be saved in the format of name.conf because this is the format nginx expects)-
There are no backing services required for the Voting App so return to Deployments within this Project and we will move to the next step Create the Preview →
Step 5. Create the Preview
I. Now add these 7 components listed in a. through g. below (we will pull 6 images from Dockerhub and add our 1 Config File).
a. (Docker Hub) uffizzicloud/example-worker:latest
b. (Docker Hub) uffizzicloud/example-vote:latest
c. (Docker Hub) uffizzicloud/example-result:latest
d. (Docker Hub) library/nginx:latest
e. (Docker Hub) library/postgres:9.6 (*include the ENVs below)
f. (Docker Hub) library/redis:latest
g. Nginx Configuration File vote.conf (*note the Mount to and Mount path below)
II. Now Configure the Network Settings
III. Now Deploy
-If our Github or Docker Hub repos are not populating we’ve most likely lost connection. We can go to Settings and refresh the connection
-If we are deploying only images the process typically takes 5-7 minutes to complete.
-If our Preview includes a Uffizzi managed Build this can take up to 15+ minutes depending on the size and complexity of the Build.
-We can drill down into our Preview to see the activity feed and track progress.
-We can also access the build logs, container logs, and settings for each individual container.
IV. Now Access our Preview (status will show a green check mark and the link will go live)
The Preview URL shows what the Results App is serving up.
We can go Vote by accessing the Vote App whose link is embedded
PHASE 2 - Creating a Preview Template
In PHASE 1 we set up our account, our first project, and successfully created a Preview of a 6 container application where each service depends upon one another for the proper functioning of the Vote App.
Now we’ll use our successful Preview to create a Template that will serve as the foundation for our ultimate goal - Continuous Previews of our in-progress development.
From within the Vote App Project select “Templates” and then “New Template”
We will build a Template from the existing deployment that we just executed.
Now we will name our Template and then complete this step with “Create Template”
PHASE 3 - Setting up a Continuous Preview from a Template
We will return to our Previews List within the Vote App Project and select “New Preview”
This time we will create a Preview from our Template
After our Template populates, we will choose the application component that we plan to work on. In this case it will be the Uffizzicloud/Example-Result:latest container.
From within the drop down change the source from Docker Hub to Github. Choose the repo and branch that we are working on - in this case “example-voting-result” and “change-color”, then SAVE
Now we’ve swapped out the “voting-result” base container with the source code for a new image that Uffizzi will build and deploy based on our updates to the Github repository. This happens continuously so that every commit or
results in a new build and deployed version of our in-progress development.
Now let's click “Deploy”
This process will take a little longer than our initial Preview because now we are including a Build process.
Once our new Preview is up and running let's check our Preview URL.
Now let’s go back to Github where we will work on our code.
For demo purposes we’ll make a new commit to our “change-color” branch within the Github UI.
Select the “Views” folder
Then the “stylesheets” folder
Now we’ll edit the code in this file:
At line 28 we’ll change-
Now scroll down and “Commit” our change
Drill into our most recent Preview and we can see Uffizzi start to build and deploy the update.
Within a few minutes the change will be deployed and if we refresh our browser we can see that our background-color has changed to “white” at our Preview URL. If the change doesn't populate immediately give it a minute and refresh again.
Congratulations! You've set up your first Continuous Preview
You can now continue to iterate on this branch until your team is satisfied with the desired look and/or functionality. At that point your branch is ready for the CI/CD process and you can merge with confidence knowing that the team has already evaluated the functionality of this branch. The dynamic preview environment that was created can then be deleted with a click.
For all the future topic, feature, and bug fix branches for this application we can easily create a Preview by starting with the template and adjusting as necessary to isolate and focus on the service we are revising.
In a coming soon version, Uffizzi will trigger Preview creation and destruction based on Pull Requests. Open a PR and Uffizzi will build the Preview. Close the PR and Uffizzi will tear it down. And we can stay focused on our Git workflow.
For questions and feedback please join us on Slack - Uffizzi Users