Stacks Workflow

You've written your stack file, now it's time import and manage that stack on Cycle.

It is recommended to commit your cycle.json file to the root of your git repo, and import directly from there. You can also, for speed or to test your stack file, import it by pasting it in directly. We'll cover both options.

Importing From A Git Repo

Once you've pushed up the cycle.json to a repo, navigate to the stack import form in the portal:

  1. Click Stacks in the nav menu on the left hand side.
  2. In the top right corner, click the blue Import Stack button.
  3. Select the Import from a Git Repo tile on the left, then click Next.

Stack Name

The stack name is for your reference, but it is recommended to name it after the application it builds.

Git Repo URL

Enter the URL to the git repo containing your stack file. If it starts with ssh://, you will need to enter the private SSH key associated with your repo.

The SSH Key should be an RSA PEM-encoded key

The process for associating your repo with an SSH key is different for each service. So whether you're using a service like GitHub, GitLab, or Bitbucket you'll want to reference your services documentation on the best practice. Generating the key itself is straightforward. This command will create an RSA PEM encoded key pair.
ssh-keygen -t rsa -b 4096 -m pem -f my-key-pair.pem

Importing A Raw Stack File

For convenience and testing purposes, you can paste your cycle.json file directly into the portal to test your build.

  1. Click Stacks in the nav menu on the left hand side.
  2. In the top right corner, click the blue Import Stack button.
  3. Select the Import from a File tile on the right, then click Next.

Stack Name

The stack name is for your reference, but it is recommended to name it after the application it builds.

Raw Cycle JSON File

This is where you paste your file. When you're ready, click Import. If there are any issues with your stack, the field will turn red and the error listed below.

Start the Import Job

Once your information is filled out, click Import. You'll be taken to a screen where you can see the progress of the import job. Depending on the amount of images that need to be imported, this could take awhile.

Importing the stack will also trigger an initial build. Later on, you can trigger additional builds manually, or via webhook, as you make changes to your stack.

Managing Stack Builds

Builds are atomic snapshots of your stack. Learn how to create new ones, view their output, and delete unused ones.
Feature Alert
One of the next major updates to Cycle will focus heavily on webhook integration. Soon, you will be able to trigger builds simply by committing to your git repo.

Whenever a change is made to a container in your stack, you'll need to do a build. A build, much like an individual container, is atomic and contains everything it needs to be deployed (config, images, etc.). The first build is created for you when you import your stack.To start a build using the portal, follow these steps:

  1. Click Stacks in the nav menu on the left hand side.
  2. Select the stack you want to build from the list.
  3. Find and click the Rebuild Stack button on the right hand side.

You will be taken to a page detailing the progress of the build. You can navigate away and the build will continue in the background.

Viewing the Build Log

Once a build is complete, you may wish to see the generated output of your builds. The build log details every step for each image that was imported.

To view the log for a specific build:

  1. From the stack view, click the Builds tab under the stack name at the top.
  2. On the table, click the Build Log button of the build you wish to view. This will pop up a modal with all the output of the build.

Deleting Individual Builds

If you no longer need a build and wish to delete it, you must first make sure no containers are using images from the build. To check, go to the "Builds" tab of a stack, find the build you wish to delete, and make sure under usage it says "0 Containers".

Once you have verified the build is unused (or updated the containers to use a more recent build by redeploying), check the box next to the builds you wish to delete. At the bottom of the table, you'll see a dropdown. From the dropdown, click Delete Selected, then click Delete.

This action cannot be undone.

All functionality for updating or deleting stacks is found on the "Settings" tab of a specific stack. To get to that page, follow these steps:

  1. Click Stacks in the nav menu on the left hand side.
  2. Select the stack you want to build from the list.
  3. Select the Settings tab located underneath the name of the stack.

Updating a Stack

You can only change the name of a stack once it has been created. This is done to keep the stack builds atomic. If you need to change the source, please delete the stack and import a new one.

From the settings tab, locate the "Update Stack" form on the left hand side. Change the name to whatever you'd like, then click Update Stack.

Deleting a Stack

If you've decided you no longer need a stack and wish to delete it, you will first need to delete the environments that the stack is deployed to. This is done to prevent accidental removal of running containers.

Once the environments the stack is deployed to have been removed, go back to the Settings tab of the stack you wish to delete, locate the delete form on the right-hand side. Enter the name of the stack into the box, and click Delete Stack.

Deleting a stack will also delete all builds and build logs ever generated for that stack. This cannot be undone.

Need Help?

If you've got questions about the platform or need some help getting started, our team is more than happy to assist. Whether you're new to containers or just new to Cycle, reach out to us via livechat by clicking the blue circle in the bottom right corner. Join our Slack channel, and get help from the dev team or other members of the community, and check out our Roadmap to see what's planned for the future!