artempartos / quickstart

Get started with Uffizzi (~1 min)

Uffizzi Quickstart (~ 1 minute)

Go from pull request to Uffizzi Preview Environment in less than one minute...

1. Fork this repo

⚠️ Be sure to uncheck the option Copy the main branch only.

This ensures that the try-uffizzi branch will be included in your fork.
 

2. Enable GitHub Actions workflows for your fork

Select Actions, then select I understand my workflows, go ahead and enable them.

3. Open a pull request for try-uffizzi branch against main in your fork

⚠️ Be sure that you're opening a PR on the branches of your fork (i.e. your-account/main ← your-account/try-uffizzi).

If you try to open a PR for UffizziCloud/main ← your-account/try-uffizzi, the Actions workflow will not run in this example.

That's it! This will kick off a GitHub Actions workflow and post the Preview Environment URL as a comment to your PR issue.

What to expect

The PR will trigger a GitHub Actions workflow that creates a Uffizzi Preview Environment for the microservices application defined by this repo. The Preview Environment URL will be posted as a comment in your PR issue when the workflow completes, along with a link to the Uffizzi Dashboard where you can view application logs. The Preview Environment will be deleted when the PR is merged/closed or after 1 hour (configurable).

How it works

Configuration

Preview Environments are configured with a Docker Compose template that describes the application components and a GitHub Actions workflow that includes a series of jobs triggered by a pull_request event and subsequent push events:

1. Build and push images to a container registry
2. Render a Docker Compose file from the Docker Compose template and the built images
3. Deploy the application to a Uffizzi Preview Environment and post a comment to the PR issue
4. Delete the Preview Environment when the PR is merged/closed or after 1h

Uffizzi Cloud

Running this workflow will create a Uffizzi Cloud account and project from your GitHub user and repo information, respectively. If you sign in to the Uffizzi Dashboard you can view logs, password protect your Preview Environments, manage projects and team members, set role-based access controls, and configure single-sign on (SSO).

Open-source projects preview for free on Uffizzi Cloud. All other accounts receive 10,000 preview minutes per month for free. If you exceed this amount, your Preview Environments will be paused unless you add a credit card. See our pricing for details or to request free access as an open-source maintainer. Alternatively, if you don't want to use Uffizzi Cloud, you can install open-source Uffizzi on your own Kubernetes cluster.

Acceptable Use

We strive to keep Uffizzi Cloud free or inexpensive for individuals and small teams. Therefore, activities such as crypto mining, filesharing, bots, and similar uses that lead to increased cost and intermittent issues for other users are strictly prohibited per the Acceptable Use Policy. Violators of this policy are subject to permanent ban.

Architecture of this Example App

The application defined by this repo allows users to vote for dogs or cats and see the results. It consists of the following microservices:

• voting-app - A frontend web app in Python which lets you vote between two options
• redis - A Redis queue which collects new votes
• worker - A .NET Core worker which consumes votes and stores them in…
• db - A PostgreSQL database backed by a Docker volume
• result-app - A Node.js web app which shows the results of the voting in real time

Set up Preview Environments for your application

You can follow this step-by-step guide to configure Preview Environments for your own application. The required components are:

• A Docker Compose template (docker-compose.uffizzi.yml) committed to your repo - This template must include ingress and services definitions. For a full list of supported keywords, see Docker Compose for Uffizzi.

• A Uffizzi preview job added to your pipeline - In the example app used by this quickstart guide, we use GitHub and GitHub Actions, but Uffizzi is designed to work with any version control system or CI platform. As a convenience, we've written actions/jobs for these popular CI platforms. If your platform is not listed, you can still add Uffizzi to your pipeline by wrapping the Uffizzi CLI, which is distributed as a container image available on Docker Hub. See our GitHub preview-action and reusable workflow as examples.

FAQs

What about my database?

All services defined by your Docker Compose file are deployed to Preview Environments as containers—this includes databases, caches, and other datastores. This means that even if you use a managed database service like Amazon RDS for production, you should use a database image in your Compose (See this example that uses a postgres image from Docker Hub).

If your application requires test data, you will need to seed your database when your Preview Environment is created. Here are two methods for seeding databases:

1. (Recommended) Have your application perform a data migration on start-up
2. Bundle test data into the database image itself. This method is only recommended for small datasets (< 50MB), as it will increase the size of your image and deployment times.

Does Uffizzi support monorepos/polyrepos?

Yes. Your CI pipeline will typically include a series of build/push steps for each of the components of your application. Uffizzi just needs to know the fully qualified container registry URL for where to find these built images.

Does Uffizzi support   _____________?

Uffizzi is container-centric and primarily designed for web languages. In general, if your application can be containerized, described with Docker Compose, and accepts HTTP traffic, Uffizzi can preview it.

How can my application services communicate?

Just like when you run docker-compose up locally, all the services defined in your Compose share a local network and can communicate via localhost:port. Applications that belong to different Preview Environments may only communicate via the public Internet.

How is Uffizzi different from GitHub Actions (or other CI providers)?

Uffizzi does not replace GitHub Actions or any other CI provider. Uffizzi previews are meant to be added as a step in your existing CI pipeline, after your container images are built and pushed to a container registry.

Can I connect Uffizzi with Netlify/Vercel?

Yes. While Uffizzi supports full-stack previews, some users who already leverage frontend platforms like Netlify or Vercel want to add Uffizzi previews for their APIs/backend. For help configuring this scenario see:

• Netlify + Uffizzi
• Vercel + Uffizzi

Is Uffizzi open source?

Yes. Check out the main repo

Get in touch

For questions, concerns, issues, or feature requests, please join our fast growing community on Slack.