Skip to content

Playpen Management

This guide covers administrative aspects of managing playpens in VOR Stream, including the automatic upgrade process and dependency management.

Automatic Playpen Upgrades

VOR Stream includes an automatic playpen upgrade mechanism that ensures playpens stay synchronized with the latest VOR templates and dependencies. This process runs during playpen updates and handles various scenarios to maintain compatibility while preserving custom configurations.

Disabling Automatic Upgrades

Automatic playpen upgrades can be disabled if you need full control over when upgrades occur. To disable automatic upgrades, set the super_playpen_upgrade_enabled variable to False in the host.ini file during deployment. Refer to the Inventory File for more information.

When automatic upgrades are disabled, playpens will not be automatically synchronized with template changes. You can still manually trigger upgrades using vor update playpen <directory>.

Upgrade Process Overview

When a playpen is updated (either automatically or via vor update playpen), the following operations are performed:

  1. Template Synchronization: The playpen's go.mod file is updated with the latest dependencies from the VOR template
  2. Custom Dependency Preservation: Any custom dependencies or replace directives added by users are preserved
  3. Workspace Version Synchronization: For playpens using Go workspace mode, the workspace version is automatically synchronized
  4. Vendor Directory Regeneration: The vendor directory is rebuilt to match the updated dependencies
  5. Error Recovery: Problematic Go files are temporarily backed up to allow the upgrade to proceed

Dependency Management

Default

When a playpen has no custom dependencies or replace directives, the upgrade process performs a clean replacement of the go.mod, go.sum, and vendor directory with the template's latest dependencies.

Custom Dependencies

The upgrade process intelligently preserves custom dependencies that users have added to their playpens. This includes:

  • Third-party packages: External Go modules like gonum.org/v1/gonum
  • Local replace directives: Custom replace directives for development or testing
  • Custom versions: Specific versions of packages that differ from the template

Example: If your playpen's go.mod contains:

require gonum.org/v1/gonum v0.16.0

This dependency will be preserved during upgrades, even if it's not in the VOR template.

Replace Directives

Custom replace directives are also preserved during upgrades. For example:

replace github.com/custom/package => /local/path/to/package

This allows users to maintain local development workflows without losing configurations during upgrades.

Go Workspace Support

VOR Stream supports Go workspace mode for playpens that require it. When a playpen contains a go.work file, the upgrade process:

  1. Detects workspace mode automatically by checking for the go.work file in the playpen root directory
  2. Synchronizes workspace version using go work use to ensure compatibility
  3. Handles workspace-specific constraints during package loading and dependency resolution
  4. Disables workspace mode during vendoring to ensure a clean vendor directory for the playpen module

Error Handling and Recovery

The upgrade process includes comprehensive error handling:

Backup System

Before making changes, the upgrade process:

  • Creates backups of critical files (go.mod, go.sum, vendor directory)
  • Backs up problematic Go files that might prevent the upgrade
  • Removes generated code files that have compilation errors to allow the upgrade to proceed
  • Automatically rolls back changes if the upgrade fails

Recovery from Failures

If an upgrade fails:

  1. All backups are automatically restored
  2. The playpen is returned to its pre-upgrade state
  3. Error logs provide diagnostic information for troubleshooting

Common Issues and Solutions

Issue: Compilation errors in custom node files prevent upgrade

Solution: The upgrade process automatically backs up problematic files, allowing the upgrade to proceed. After the upgrade completes, review the backed-up files and fix any compilation issues.

Issue: Custom dependencies conflict with template dependencies

Solution: The upgrade preserves your custom dependencies. If there are version conflicts, you may need to manually update your dependencies to compatible versions.

Issue: Workspace version mismatch

Solution: The upgrade process automatically runs go work use to synchronize workspace versions. If issues persist, verify your go.work file is correctly configured.

Issue: Generated code removed during upgrade

Solution: If generated code files (in src/nodes/generated_code/) have compilation errors during the upgrade, they are automatically removed to allow the upgrade to proceed. After the upgrade completes successfully, regenerate the process using:

vor create process <process-name>

This will regenerate the code with the updated dependencies.

Monitoring Upgrades

To monitor playpen upgrades:

  1. Check upgrade logs: Playpen upgrade logs are available in the VOR Stream logs
  2. Verify dependencies: After an upgrade, review the go.mod file to ensure all dependencies are correct
  3. Test functionality: Run existing models and jobs to verify compatibility

Best Practices

  1. Commit before upgrading: If using version control, commit your playpen state before performing upgrades
  2. Document custom dependencies: Keep a record of custom dependencies and replace directives for reference
  3. Regular upgrades: Perform upgrades regularly to avoid large version jumps
  4. Review changes: After upgrades, review the updated go.mod to understand what changed

Integration with Version Control

When using version control with playpens:

  • Track go.mod and go.sum: These files should be committed to track dependency changes
  • Ignore vendor directory: The vendor directory can be regenerated and is typically not committed
  • Review upgrade diffs: After upgrades, review the diff to understand what changed

Manual Intervention

In rare cases, manual intervention may be required:

  1. Manual upgrade: Use vor update playpen <directory> to manually trigger an upgrade if automatic upgrades are disabled or fail.
  2. Manual dependency resolution: If automatic dependency resolution fails, you may need to manually run go mod tidy and go mod vendor to resolve dependencies.