Testing Vendor Onboarding

This guide covers how to test the vendor onboarding flow during development, including resetting state and managing registry images.

Resetting the Onboarding Flow

To test the onboarding flow from the beginning, you need to reset the vendor's onboarding state and optionally clean up any created resources.

Quick Reset (Keep Resources)

Reset just the onboarding status while keeping products, repositories, and customers:

bin/run rails console

vendor = Vendor.find_by(slug: "your-vendor-slug")
vendor.update!(onboarding_completed_at: nil, onboarding_dismissed_at: nil)
VendorOnboardingProgress.find_by(vendor: vendor)&.destroy

Full Reset (Remove All Resources)

Reset the onboarding and remove all resources created during the flow:

bin/run rails console

vendor = Vendor.find_by(slug: "your-vendor-slug")

# Remove all resources (in dependency order)
vendor.licenses.destroy_all
vendor.customers.destroy_all
vendor.repositories.destroy_all
vendor.products.destroy_all
vendor.auth_tokens.destroy_all

# Reset onboarding state
vendor.update!(onboarding_completed_at: nil, onboarding_dismissed_at: nil)
VendorOnboardingProgress.find_by(vendor: vendor)&.destroy

Registry Image Management

Automatic Deletion on Repository Destroy

When a Repository record is destroyed, the application can automatically delete the corresponding images from the Docker registry. This is controlled by environment variables.

Configuration

Set these environment variables to enable registry deletion:

# The internal URL of your registry (for API calls)
REGISTRY_URL=http://localhost:5000

# Enable deletion (disabled by default for safety)
REGISTRY_DELETE_ENABLED=true

Registry Configuration

Your Docker registry must also have deletion enabled. Add this to your registry's config.yml:

storage:
  delete:
    enabled: true

Or set the environment variable when running the registry container:

docker run -e REGISTRY_STORAGE_DELETE_ENABLED=true registry:2

Manual Registry Deletion

If automatic deletion is not enabled, you can manually delete images from the registry:

# Get the digest for a specific tag
curl -I -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  http://localhost:5000/v2/vendor-slug/image-name/manifests/latest

# Delete by digest (use the Docker-Content-Digest header from the response)
curl -X DELETE \
  http://localhost:5000/v2/vendor-slug/image-name/manifests/sha256:abc123...

Garbage Collection

After deleting images, the registry still holds blob data until garbage collection runs. To reclaim disk space:

# Run inside the registry container
docker exec <registry-container> registry garbage-collect /etc/docker/registry/config.yml

Testing Push Detection

The onboarding flow uses ActionCable to detect when images are pushed to the registry. To test this:

1. Start the Rails server with ActionCable enabled:
   bash
bin/dev


2. Navigate to the repository step in onboarding (/vendor/onboarding/repository)

3. In another terminal, push an image:
   bash
docker tag myimage registry.breakwaterapp.com/your-vendor/myimage:latest
docker push registry.breakwaterapp.com/your-vendor/myimage:latest


4. The page should automatically detect the push, show a success message, and display a "Continue" button.

Troubleshooting ActionCable

If push detection isn't working:

1. Check the browser console for WebSocket connection errors
2. Verify the Rails server logs show the ActionCable connection
3. Ensure you're logged in as a vendor user (ActionCable requires authentication)
4. Check that the VendorOnboardingChannel is properly loaded (restart the server if you recently added it)

Testing the Complete Flow

Here's a script to test the entire onboarding flow programmatically:

bin/run rails console

# Create a fresh vendor invitation
invitation = VendorInvitation.create!(
  email: "test@example.com",
  vendor_name: "Test Vendor",
  expires_at: 1.week.from_now
)

puts "Onboarding URL: /vendor/setup?token=#{invitation.raw_token}"

Then visit the URL in your browser to walk through the complete flow.