Private Packages

Appearance

Getting Started ​

This guide will walk you through setting up Private Packages and adding your first premium plugin or theme.

Prerequisites ​

Before you begin, make sure you have:

  • An account at private-packages.com/portal - you'll create your first workspace during signup
  • License keys for the premium plugins/themes you want to manage
  • A Composer-based WordPress setup

Step 1: Understanding Workspaces ​

When you create your account, you'll be prompted to create your first workspace. Workspaces help organize your packages and tokens. A typical user will only need one workspace.

Multiple Workspaces

If you're a freelance developer working with multiple agencies, you can create additional workspaces later:

  • Navigate to Workspaces → Create New
  • Each workspace has its own repository url, packages and tokens
  • Workspaces are billed separately

Step 2: Add Your First Package ​

  1. Navigate to Packages in your workspace
  2. Click Add Package
  3. Select the appropriate recipe for your plugin/theme.
  4. Fill in the required information:
    • License Key: Your license key
    • Recipe-Specific Settings: Each recipe may require different information (see Packages for details)

Step 3: Configure Package Settings ​

Depending on the recipe, you may need to provide:

  • Source URL: The WordPress site where the license is activated
  • Endpoint URL: The vendor's update server URL
  • Plugin Slug: The plugin's unique identifier
  • Additional Settings: Some recipes require specific configuration

TIP

Many recipe forms include helper text and placeholders with information on how to obtain the necessary values. Look for the information icon (?) next to form fields.

Step 4: Activate License (Optional) ​

For supported packages, you can activate the license directly with the vendor:

  1. Go to the package that has a license that is currently not activated on the vendor's system.
  2. Click Activate License
  3. The system will communicate with the vendor's API to activate your license
  4. You'll see a success or error message

Not all recipes support activation. If activation is not supported, you need to activate the Source URL on the vendor's website.

Step 5: Generate an Access Token ​

To use your packages with Composer, you need to generate an access token:

  1. Navigate to Access → Tokens
  2. Click Create Token
  3. Give it a descriptive name (e.g., "website-name")
  4. Copy the generated token

TIP

Create tokens on a per-project basis for better security and easier management.

See Tokens for detailed information about authentication.

Step 6: Configure Composer ​

Add Private Packages as a repository in your project's composer.json:

json
{
    "repositories": [
        {
            "type": "composer",
            "url": "https://{{workspace-slug}}.private-packages.com"
        }
    ]
}

Note: Replace {{workspace-slug}} with your workspace slug.

Step 7: Authenticate with Composer ​

Configure Composer to use your access token for authentication:

json
{
    "http-basic": {
        "{{workspace-slug}}.private-packages.com": {
            "username": "{{token-username}}",
            "password": "{{token}}"
        }
    }
}

Note: Replace {{workspace-slug}}, {{token-username}} and {{token}} with their respective values.

DANGER

Never commit your auth.json file to version control. Add it to your .gitignore file.

Step 8: Require Your Package ​

Now you can require your premium packages like any other Composer dependency:

bash
composer require vendor/package-name

The exact vendor and package names are shown on the packages overview and detail pages.

Maintenance & Monitoring ​

Automatic Updates ​

Private Packages will:

  • Check for new releases every 6 hours
  • Validate licenses daily
  • Update package information automatically

Manual Actions ​

From the package edit page, you can:

  • Check License: Manually verify license validity
  • Check for Updates: Trigger an immediate update check
  • Activate License: Activate with the vendor (if supported)

Troubleshooting ​

Package Not Updating ​

  • Check if your license is still valid. Log in to the vendor's website to verify.
  • Check if the source URL matches where the license is activated
  • Verify the recipe configuration
  • Review the error messages in the package details
  • Package updates that fail during automatic updates will show up in Logs → Package logs

License Activation Failed ​

  • Ensure the license key is correct. Log in to the vendor's website to verify.
  • Check if the source URL matches where the license is activated
  • Verify you haven't exceeded activation limits

Composer Authentication Failed ​

  • Ensure you have added your repository to the composer.json file
  • Verify your token is correct
  • Check that the token hasn't been deactivated
  • Ensure the package you're trying to install has been activated for this specific token
  • Ensure you're using the correct domain in your auth configuration

Next Steps ​

  • Explore all available Packages and their specific requirements
  • Learn more about Access Tokens and best practices
  • Set up additional workspaces if needed