Breakwater / Docs
Request early access

Getting Started

Welcome to Breakwater! This guide will help you set up your vendor account and start distributing licensed container images to your customers.

Overview

Breakwater manages licensed access to private Docker container images. As a vendor, you can:

  • Create products that represent your containerized software offerings
  • Set up repositories to store your Docker images
  • Create customer accounts and grant them licenses
  • Control which image versions customers can access
  • Track image pulls and usage

Quick Start Checklist

  1. Create a product - Define what you're selling
  2. Set up a repository - Where your Docker images live
  3. Link repository to product - Connect them together
  4. Create a customer - Add your first customer account
  5. Issue a license - Grant the customer access to your product
  6. Generate auth tokens - Create credentials for pushing and pulling images

Step 1: Create a Product

Products represent your software offerings. A product might be a single application, a suite of tools, or any containerized software you want to license.

  1. Go to Products in the navigation
  2. Click New Product
  3. Enter a name and optional description
  4. Save the product

The product slug is auto-generated from the name and is used in API references.

Step 2: Set Up a Repository

Repositories correspond to Docker registry repositories where your images are stored. Repository names must:

  • Start with a lowercase letter or number
  • Contain only lowercase letters, numbers, dots, underscores, hyphens, and slashes
  • Use slashes to separate segments (each segment must start with a lowercase letter or number)
  1. Go to Repositories in the navigation
  2. Click New Repository
  3. Enter the repository name (e.g., myapp, myapp-enterprise, platform/api)
  4. Select which products this repository belongs to
  5. Save the repository

The full image path will be registry.breakwaterapp.com/your-vendor-slug/repository-name.

Step 3: Create a Customer

Customers are the companies or individuals who purchase licenses for your products.

  1. Go to Customers in the navigation
  2. Click New Customer
  3. Enter the customer's name
  4. Save the customer

Step 4: Issue a License

Licenses grant customers access to pull images from your repositories.

  1. Navigate to the customer's detail page
  2. Click New License
  3. Select the product to license
  4. Set the license period (start and expiration dates)
  5. Optionally set a tag pattern to restrict version access
  6. Save the license

Step 5: Generate Auth Tokens

Auth tokens are credentials used to authenticate with the Docker registry.

Vendor tokens (vtok_*) are for your own use:
- Push images to your repositories
- Pull any image from your repositories
- Use in CI/CD pipelines for publishing

Customer tokens (ctok_*) are for your customers:
- Pull images from licensed repositories only
- Respect license restrictions (dates, tag patterns)
- Give these credentials to your customers

To create a token:

  1. Go to Auth Tokens in the navigation
  2. Click New Token
  3. Choose token type (vendor or customer)
  4. Give it a descriptive name
  5. Optionally set an expiration date
  6. Save and copy the secret immediately - it won't be shown again

Using the Registry

Pushing Images (Vendor)

# Log in with your vendor token
docker login registry.breakwaterapp.com -u vtok_xxxxx

# Tag your image
docker tag myapp:latest registry.breakwaterapp.com/your-vendor/myapp:v1.0

# Push the image
docker push registry.breakwaterapp.com/your-vendor/myapp:v1.0

Pulling Images (Customer)

Share these instructions with your customers:

# Log in with the customer token you provided
docker login registry.breakwaterapp.com -u ctok_xxxxx

# Pull the image
docker pull registry.breakwaterapp.com/your-vendor/myapp:v1.0

Next Steps