DOCSEARCHbyAlgolia
Submit Docs

Packeton Documentation

repository·master·Indexed 19 days ago

https://github.com/vtsykun/packeton

An open-source private PHP package repository for vendors, built on Symfony 6 and compatible with Composer API v2. Packeton serves as an alternative to Private Packagist, offering features such as granular ACL, mirroring, Composer Proxies, and webhook support for GitHub, GitLab, Bitbucket, and Gitea. It supports various repository types including VCS, Mono-repo, and Custom JSON, and can be deployed via Docker or installed from source.

Tokens
38.3K
Snippets
125
Records
168
Agent score
67%

What's inside Packeton

  1. Overview of Packeton features

    master

    Packeton is a private PHP package repository for vendors, built on Symfony 6 and compatible with Composer API v2. It provides advanced management for private PHP packages, including:

    • Repository Management: Supports VCS (auto), Mono-repo, Custom JSON, and Artifacts. It also supports monolithic repositories (e.g., symfony/symfony) and multi-sub repositories.
    • Access Control: Granular ACL groups and customer users that can limit access by vendor, package, version, or release date. Supports LDAP at the configuration level.
    • Integrations & Webhooks: Supports update webhooks for GitHub, Gitea, Bitbucket, and GitLab. Includes OAuth2 integrations for major Git providers and outgoing webhooks with a custom UI request builder.
    • Mirroring & Proxies: Full support for Composer Proxies and Mirroring (including package zip files) with separate URL paths.
    • Security & Compliance: Includes security monitoring via webhook notifications and the ability to freeze updates for new releases if a customer license expires.
    • Workflow Tools: Pull Request composer.lock change reviews and fine-grained API tokens.

  2. Configure Packeton Webhooks

    master

    Packeton webhooks allow you to notify external services via POST requests when specific events occur. Webhook payloads can be customized using the Twig expression language within a sandbox mode. By default, only admin users can configure webhooks.

    Supported events include:

    • new_release
    • update_release
    • delete_release
    • push_new_event
    • update_new_event
    • http_request
    • update_repo_failed
    • new_repo
    • delete_repo
    • update_repo (implied)

  3. Compare Packeton with Private Packagist

    master

    Packeton is an open-source alternative to Private Packagist. Key differentiators include:

    • Pricing: Packeton is Open Source and free, whereas Private Packagist is a paid service.
    • Mirroring: Packeton offers full support with a separate URL path and a UI metadata manager for patching metadata.
    • Webhooks: Packeton provides full support for outgoing webhooks with a custom UI request builder using expressions, whereas Packagist uses a non-configurable payload format.
    • Access Control: Packeton allows limiting access by specific versions and release dates.
    • Repository Types: Packeton supports Mono-repo and Custom JSON types.

  4. Understand Customer User roles and access levels

    master

    Customer users in Packeton are managed via two primary roles that determine their level of access to package metadata:

    • ROLE_USER: Provides minimal access. These users can only read metadata for selected packages. Access for this role can be further restricted by package release date.
    • ROLE_FULL_CUSTOMER: Provides broad access. These users can read all package metadata without being restricted by group ACLs.

  5. Manage Application Roles in Packeton

    master

    Packeton uses specific roles to control access levels for users. Understanding these roles is essential for managing package visibility and administrative capabilities:

    • ROLE_USER: Minimal access. Users can only read metadata for specifically selected packages.
    • ROLE_FULL_CUSTOMER: Can read metadata for all packages.
    • ROLE_MAINTAINER: Can submit new packages and read all metadata.
    • ROLE_ADMIN: Full administrative access, including creating customer users, managing webhooks, and managing credentials.

  6. Use Twig variables in Webhook payloads

    master

    When configuring a webhook, you can access several Twig variables to build dynamic payloads:

    • package: The Package entity.
    • versions: An array of Versions[].
    • webhook: The current Webhook entity.
    • user: The User entity (available only for user login events).
    • parentResponse: A HookResponse object (available only for nesting webhooks).
    • request: An array (available only for http_request events).

  8. Configure User Provider priority in LDAP chain

    master

    Packeton uses the Symfony Chain User Provider to look up users. The order of providers in the chain configuration determines the lookup priority.

    If you want to enforce customer user restrictions (by vendors and versions) managed in the local database, ensure the packagist provider is listed before the LDAP provider. If packagist is listed after users_ldap, local packagist users may be ignored if an LDAP match is found first.

    security:
    providers:
        users_ldap:
            ldap:
                ...
 
        all_users:
            chain:
                # Correct: Load from packagist first, then LDAP
                providers: ['packagist', 'users_ldap'] 
                
                # Incorrect: packagist users will be ignored if found in LDAP
                providers: ['users_ldap', 'packagist']

  9. Manage Packeton User Roles

    master

    Packeton uses specific roles to control access to packages and management features:

    • ROLE_USER: Minimal access; can only read metadata for specifically assigned packages.
    • ROLE_FULL_CUSTOMER: Can read metadata for all packages.
    • ROLE_MAINTAINER: Can submit new packages and read all metadata.
    • ROLE_ADMIN: Full access; can create customer users, manage webhooks, and manage credentials.

    Use the packagist:user:manager command to create users and assign roles.

    # Create an admin user
php bin/console packagist:user:manager username --email=admin@example.com --password=123456 --admin

# Add a maintainer role to an existing user
php bin/console packagist:user:manager user1 --add-role=ROLE_MAINTAINER

  10. Understand Webhook expression security constraints

    master

    Packeton uses Twig in sandbox mode to evaluate expressions within webhooks. This imposes strict security limitations to prevent unauthorized access to sensitive data and network resources:

    1. Data Access Restrictions: You cannot call methods on objects that access security-sensitive information. Attempting to access sensitive properties or methods (e.g., calling getcredentials on a Packeton\Entity\Package object) will trigger a Twig\Sandbox\SecurityNotAllowedMethodError.
    2. SSRF Protection: To prevent Server-Side Request Forgery (SSRF) attacks, Packeton uses a NoPrivateNetworkHttpClient. This prevents webhooks from making HTTP requests to internal or private network IP addresses (e.g., http://10.8.100.1/ or 127.0.0.1). Attempting such a request will result in a Symfony\Component\HttpClient\Exception\TransportException stating the IP is blocked.

  11. How Pull Request composer lock review works

    master

    Packeton automatically analyzes composer.lock changes in Pull Requests and adds a comment describing the dependency changes. It specifically detects the following types of changes:

    • Added a new dependency
    • Removed dependency
    • Downgraded dependency
    • Upgraded dependency
    • Changes to dist or source URLs

  12. Configure SSH key and Composer authentication

    master

    Packeton uses the system's SSH keys and Composer configuration to access repositories (git/svn/hg). The web server and Supervisor worker must run under a user that has these credentials.

    SSH Key Directory Structure

    If your application runs under www-data with home /var/www, organize your keys like this:

    └── /var/www/
    └── .ssh/
        ├── config
        ├── id_rsa
        └── ...
    └── packeton/
        └── var/
            └── .composer/

    Composer Authentication

    To use auth.json for authentication, place it in the directory defined by APP_COMPOSER_HOME (default: %kernel.project_dir%/var/.composer/).

    Example auth.json:

    {
  "http-basic": {
    "git.example.pl": {
      "username": "kastus",
      "password": "489df705a503ac0173256ce01f"
    }
  }
}

    SSH Config for Multiple Accounts

    You can use ~/.ssh/config to manage multiple identities for different hosts:

    Host github-org1
    HostName github.com
    User git
    IdentityFile /var/www/.ssh/private_key_1
    IdentitiesOnly yes
    {
  "http-basic": {
    "git.example.pl": {
      "username": "kastus",
      "password": "489df705a503ac0173256ce01f"
    }
  }
}