Quickstart (Uffizzi CI)¶

What is Uffizzi CI?¶

Uffizzi CI is an integrated build service provided by Uffizzi Cloud. Every time you push a new commit to your repository, Uffizzi CI receives a webhook and builds your application from source. Choose this solution if you don't already have a CI platform or don't want to use your existing solution to build preview images. Learn more >

1. Fork the quickstart-uffizzi-ci repository¶

Fork the quickstart-uffizzi-ci repository on GitHub. Be sure to uncheck the option Copy the main branch only. This ensures that the try-uffizzi branch will be included in your fork.

Click to expand

What's in this repository?¶

This repository includes a sample voting application that consists of five microservies. Also included in the repository is a Docker Compose template (docker-compose.uffizzi.yml) that describes the application stack and includes information required by Uffizzi.

At a minimum, this file must include the following object definitions:

1. services - The container service(s) that make up your application. See Docker Compose for Uffizzi for supported keywords.

2. x-uffizzi - This is a custom extension field required by Uffizzi.

   a. ingress - Tells Uffizzi which of your services should receive incoming https traffic
   b. continuous_previews - Required by Uffizzi CI. Set the following values to true:

   • deploy_preview_when_pull_request_is_opened: true
   • delete_preview_when_pull_request_is_closed: true
   • share_to_github: true - Toggles commenting on GitHub pull request issues

Your Docker Compose template must be committed to the branch that you merge into, i.e. your target base branch (typically this is your default branch). It is recommended to commit your compose file to the root directory, although this is not required. Note that all paths specified in your docker-compose.uffizzi.yml file should be relative to this file location.

2. Create a project at uffizzi.com¶

If you haven't already done so, create a Uffizzi Cloud account. Once logged in, follow these steps to create project:

1. Select New project > Uffizzi CI > Configure GitHub
2. Install Uffizzi Cloud on your GitHub account
3. Install & Authorize the Uffizzi GitHub App your repository
4. Select Set up project for your desired repository
5. Add your docker-compose.uffizzi.yml file in Project > Settings > Compose. Be sure to choose the branch that you merge into, i.e. your target base branch.
6. Save and validate your compose; resolve any errors
7. Check your configuration with a test deployment

Click to expand (Screenshots)

1. Select New project > Uffizzi CI > Configure GitHub

2. Install Uffizzi Cloud on your GitHub account

3. Install & Authorize the Uffizzi GitHub App your repository

4. Select Set up project for the repository you just forked

5. Add your `docker-compose.uffizzi.yml` file in Project > Settings > Compose. Be sure to choose the branch that you merge into, i.e. your target base branch.

6. Save and validate your compose; resolve any errors

7. Check your configuration with a test deployment

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, a preview will not run in this example.

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