Tractorbeam Handbook

Appearance

Fleet Deployment Guide ​

This guide explains how to deploy packages to Fleet DM for self-service installation.

Prerequisites ​

  • Fleet Premium subscription (required for custom packages)
  • Fleet admin access
  • Signed and notarized .pkg file
  • fleetctl CLI installed (optional, for automation)

Manual Upload via Fleet UI ​

Step 1: Build the Package ​

bash
# Build with full signing and notarization
export APPLE_SIGNING_IDENTITY="Developer ID Application: ..."
export APPLE_ID="..."
export APPLE_APP_SPECIFIC_PASSWORD="..."
export APPLE_TEAM_ID="..."

./packages/CursorCarlyle/build.sh

# Output: dist/CursorCarlyle/CursorCarlyle-1.0.0.pkg

Step 2: Upload to Fleet ​

  1. Log in to your Fleet dashboard
  2. Navigate to Software > Add software
  3. Click Upload and select your .pkg file
  4. Fill in the details:
    • Name: Cursor (Carlyle)
    • Version: 1.0.0
    • Platform: macOS

Step 3: Configure Installation ​

Set the installation options:

  • Install script: Leave empty (pkg handles it)
  • Uninstall script:
    bash
    /Applications/Cursor\ Carlyle.app/Contents/Resources/uninstall.sh
    Or provide the full uninstall script content.

Step 4: Enable Self-Service ​

  1. Go to the software item settings
  2. Enable Self-service
  3. Choose which teams can see it

Step 5: Test Installation ​

  1. On a test Mac enrolled in Fleet
  2. Open Fleet Desktop or self-service portal
  3. Find "Cursor (Carlyle)"
  4. Click Install
  5. Verify installation completes successfully

Automated Deployment with fleetctl ​

Install fleetctl ​

bash
# macOS
brew install fleetdm/tap/fleetctl

# Or download from releases
# https://github.com/fleetdm/fleet/releases

Configure fleetctl ​

bash
fleetctl config set --address https://your-fleet-server.com
fleetctl login

Upload Package ​

bash
fleetctl software add \
  --software-package dist/CursorCarlyle/CursorCarlyle-1.0.0.pkg \
  --self-service \
  --team "Engineering"

Update Existing Package ​

bash
fleetctl software update \
  --software-id <software-id> \
  --software-package dist/CursorCarlyle/CursorCarlyle-1.1.0.pkg

CI/CD Integration ​

Add a deployment step to your GitHub Actions workflow:

yaml
- name: Deploy to Fleet
  if: github.ref == 'refs/heads/main'
  env:
    # NOTE: FLEET_API_TOKEN and FLEET_URL now come from AWS Secrets Manager
    # (tractorbeam/github-actions/fleet in Shared Services account), not GitHub secrets.
    FLEET_API_TOKEN: ${{ secrets.FLEET_API_TOKEN }}
    FLEET_URL: ${{ secrets.FLEET_URL }}
  run: |
    # Install fleetctl
    brew install fleetdm/tap/fleetctl
    
    # Configure
    fleetctl config set --address "$FLEET_URL" --token "$FLEET_API_TOKEN"
    
    # Upload
    fleetctl software add \
      --software-package dist/${{ inputs.package }}/*.pkg \
      --self-service

Version Management ​

Versioning Strategy ​

Use semantic versioning:

  • MAJOR: Breaking changes (new authentication, incompatible config)
  • MINOR: New features (new branding, additional tools)
  • PATCH: Bug fixes, updates to upstream app

Tracking Upstream Versions ​

For repackaged apps like Cursor Carlyle:

  1. The weekly CI build checks for new Cursor versions
  2. If Cursor updates, a new package is built
  3. Version format: {upstream_version}-{our_patch}
    • Example: 2.4.35-1 (Cursor 2.4.35, our patch 1)

Updating in Fleet ​

When deploying a new version:

  1. Upload the new package to Fleet
  2. Users will see "Update available" in self-service
  3. Or push updates automatically via policy

Monitoring ​

Installation Success ​

Check Fleet's software inventory:

  • Which hosts have the package installed
  • Installation success/failure rates
  • Version distribution across fleet

User Feedback ​

Monitor for:

  • Support tickets related to the package
  • Slack channel for package-specific issues
  • Fleet activity logs for installation failures

Troubleshooting ​

Package Won't Upload ​

  • Check file size (Fleet may have limits)
  • Verify pkg is properly signed
  • Check Fleet server disk space

Installation Fails on Hosts ​

Common issues:

  1. Gatekeeper blocks: Package not properly notarized
  2. Permission errors: postinstall needs sudo
  3. Disk space: Host doesn't have enough space

Check Fleet logs:

bash
fleetctl get host <hostname> --json | jq '.software_install_logs'

Users Don't See Package ​

  • Check self-service is enabled
  • Verify team assignment
  • Check host is in the right team

Package Shows Wrong Version ​

Fleet caches software information. Force refresh:

bash
fleetctl trigger --host <hostname> --name software_inventory

Best Practices ​

  1. Test on staging first: Use a staging Fleet instance or test team
  2. Gradual rollout: Start with a small group before company-wide
  3. Communication: Announce new packages in Slack/email
  4. Documentation: Link to package README in Fleet description
  5. Rollback plan: Keep previous versions available for quick rollback