This guide will introduce you to Ocuroot and get you up and running quickly with some example builds and deployments.

You will set up a local instance of the Ocuroot server, then build and deploy some sample packages. All the work will be done locally, so you won’t need to provide any secrets or access any cloud providers.

You will be introduced to:

• The Ocuroot CLI
• The Ocuroot Web UI
• The deliver command
• The sync command

​

Prerequisites

You will need Go 1.23 or later installed on your local machine.

​

Install ocuroot

1. Log in to your Ocuroot account.

2. Click “Download CLI” at the bottom of the page and select the appropriate version for your system.

3. Install the downloaded CLI package following the installation instructions for your operating system.

​

Authenticate the client with the Ocuroot server

Run the following command to authenticate the client with the Ocuroot server:

ocuroot auth login

This will open your browser to complete the authentication process.

​

Clone the Quickstart Repo

In a new terminal, clone the quickstart repo into a directory of your choice and change into that directory:

git clone https://github.com/ocuroot/quickstart.git
cd quickstart

At the root of the repo, there is a repo.ocu.star file that contains global configuration for the whole repo. This contains a name for the repo and declarations for the environments we’ll be working with, one staging environment and two production.

This repo contains two packages, under the directories message and qr respectively. These packages work together to produce a QR code for each of your environments containing a customized message.

Each package is configured in the package.ocu.star file in its directory. This file contains functions to build the package and to deploy and destroy the package in any given environment. It also includes a policy function that determines whether a build is ready to deploy in a specific environment. Ocuroot will execute this function frequently to keep the target state updated and determine what deployments should happen next.

​

Set up your environments

Before we can start building and deploying, we need to set up the environments. In the repo.ocu.star file, we have defined the environments we’ll be working with.

To synchronize these environments to your Ocuroot account, run:

ocuroot environment sync

You can confirm these environments were added by running:

ocuroot environment list

Or visiting the Environments page in the Ocuroot UI.

​

Deliver the initial commit

Let’s do some Continuous Delivery!

A key step in the lifecycle of change is the deliver command, which will run builds for any packages that have been modified, and record those builds within Ocuroot’s state store so they can be deployed as desired.

ocuroot deliver

This will build the message and qr packages, as neither of them has been built before. The CLI will tell you what it’s doing at each step of the way. If anything goes wrong, Ocuroot will output a full log to help you diagnose the problem.

You can see the results of the deliver operation for message in the UI:

1. Browse to the server UI
2. Click “Packages” in the menu bar.
3. Click “message” to view the builds for this package.

You will see that the build has been associated with the current commit in the quickstart repo. If you click on the build you can see further detail.

In this view you can see expanded detail about the change, as well as the attributes associated with the build. In this case, the message attribute contains the output of the file message/message.txt. This acts as the “asset” for this build that we can deploy to various environments.

If you go back to the package page for the message package, you can select the “Deployments” tab to view a summary of which environments have received which deployment.

Your initial deployment is currently pending in the staging environment.

The policy function for these packages has been configured to require successful deployment to staging before production, so production deployments are not queued yet.

Now the build is complete, you can deploy it to staging.

​

Synchronize to deploy

Paired with the deliver command, is the sync command. This command will check the target and actual deployment state of your packages and perform necessary actions to bring them in sync with one another.

If you run:

ocuroot sync

You will see that “message” has been deployed to staging, but since “qr” has a dependency on “message”, qr won’t be ready to deploy until that dependency has been satisfied.

This will have satisfied the dependency on “message”, so now “qr” is ready to deploy to staging.

Run ocuroot sync again. Then open the deployments view for the qr package.

You will see that qr has been deployed to staging, and in the UI, you will see an indicator showing it is “live” in that environment. You will also see that the build is now ready to deploy to production.

For this example, we are “deploying” to local files. If you look in your copy of the quickstart repo, you should now see a directory .ocuroot/deployments/staging, containing a file qr.png. If you open this image and scan the QR code with your phone, you should see the message: “Hello from staging!”

You now want to get everything in production. To avoid having to repeatedly run ocuroot sync, you can run it in continuous mode:

ocuroot sync --continuous

This will repeatedly run sync cycles whenever there is work available. You should see everything deploy to production and then pause. Hit Ctrl+C to stop the sync running.

You will now see directories under .ocuroot/deployments/prod1 and .ocuroot/deployments/prod2 containing custom QR codes for those environments.

​

Make a change

Now we have our packages up and running, let’s put out a change to the message.

Open the file message/message.txt and change the content to read “Goodbye, from $ENVIRONMENT”.

Create a commit for this change with Git, and re-run ocuroot deliver.

You will see that only message was built and deployed. This is because the file you changed was only in the scope covered by message/package.ocu.star. The package file will monitor any files in or below its own directory.

Once the build has completed, run ocuroot sync --continuous to deploy through to the production environments. You will see that the initial build of qr is redeployed. This is because the input it pulled from the message package has been updated, so qr has to be redeployed to pick up the new value.

Double-check the generated QR codes to make sure they’re displaying the correct message. They should all show your new message and specify the correct environment.

Congratulations, you’ve deployed your first changes with Ocuroot!