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.

​

Prerequisites

You will need Docker installed on your local machine.

​

Install ocuroot

TODO: Provide instructions for installing the binary

Confirm that ocuroot was installed correctly by running:

ocuroot version

​

Start the server

A Ocuroot server is needed to maintain the state for your builds and deployments. The full server is included with the command line tool, and you can start it locally in demo mode:

ocuroot server --demo

This will run a server locally with all state stored in memory. Suffice to say that demo mode should not be used in a production setting.

Once the server starts successfully, you can browse to the UI at: http://localhost:8080

You will notice that “staging” and “production” environments were automatically created for you. This gives you somewhere for your deployments to go.

​

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 git@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, the URL for the Ocuroot server that should be used (in this case localhost), 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.

​

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, a full log will be output 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 at http://localhost:8080.
2. Click “Repositories” in the menu bar.
3. Click “github.com/ocuroot/quickstart” in the repositories list.
4. Click “message” to view the deployments for this package.

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. If you click the “Builds” tab, you can see further detail.

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 abotu 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.

Now our new build is in staging, it can be synchronized to the production environments.

​

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.

To get “qr” deployed to staging, you can run ocuroot sync again.

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 output/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 output/deployments/prod1 and output/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”.

Run ocuroot deliver again, and 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.

If you look at this build in the Ocuroot UI, you will see it is marked as “modified”.

This is because the build was created with uncommitted changes in the repo. Delivering changes that haven’t been merged allows for rapid iteration when building out your configuration, and greater flexibility when handling emergencies.

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!