Managing Private Composer Repositories with Packages

Maintaining private code repositories with Composer can be tricky. There are two options: run a small instance of Satis, manually updating available packages or set up your own instance of Packagist. The former offers little flexibility, and the latter is actually quite the undertaking. Packagist also offers many features a private repository simply doesn't need such as searching and statistics.

Enter Packages

Packages is an open source project designed to solve the problem of managing... well, Composer packages. Packages provides a middle-ground between Satis and Packagist, giving your team the flexibility it needs without hindering it with maintenance.

Packages wraps Satis, providing a web interface that allows straightforward configuration. Packages also integrates directly with GitLab, able to fetch a list of available projects and automatically configure webhooks to enable the automatic update of Satis package data.

Setting up your own Packages instance

Packages is simple to setup. It requires a database backend supported by Doctrine and a Redis database to manage php-resque jobs.

Installation

This guide makes the following assumptions:

• Composer is already installed on the system.
• Sqlite, MySQL, PostgreSQL or some other database engine is available on the system.
• Redis is ready and running, with a database that Packages can muck around with.
• A webserver is configured, pointing at the web directory wherever you setup Packages
• You have a GitLab instance already setup, with an API key that has access to at least one project

Clone the Packages repository and use Composer to install dependencies:

git clone https://github.com/terramar-labs/packages
cd packages
composer install

Next, copy config.yml.dist to config.yml.

cp config.yml.dist config.yml

Configuration

Open config.yml in your favorite editor. A brief overview of the contents:

• The security section configures the username and password used to login to the web interface and manage Packages. Set it to something secure.
• The doctrine section configures the database connection. There is no need to modify the mapping:paths options. Configure your driver and any options.
  
  An example MySQL configuration:

  doctrine:
    database:
      # Any Doctrine driver
      driver: pdo_mysql
      
      # Options
      host: 127.0.0.1
      user: root
      password: 
      database: packages
  

• The resque section configures the Redis connection. host can be a unix socket or a valid hostname. Change database to whichever Redis database is set up for Packages.

Once you've made any modifications, confirm Packages works by running bin/console in your terminal.

$ bin/console
Terramar Labs Packages version 2.1.1

Options:
  --help           -h Display this help message.
...

Now, create the database schema by running the database migrations

bin/console migrations:migrate

Using the Packages web interface

Visit your Packages install from your browser. You'll be meeted with a fairly generic landing page (which you are encouraged to customize)

Click the Login button and login with the credentials you specified in config.yml. Click on Configuration and set up your GitLab information, including URL and API Key.

Now, from the Configuration, click the Sync button. Packages will load all available projects on that API key and populate a Package.

From there, you need to enable specific Packages. Do this by going to the Packages listing and click Enable on whichever project you want Packages to automatically update.

Wrapping up

As a final step, you need to either push a change to the project or manually update Satis from the command line by running:

bin/console satis:update --build

The file packages.json will be generated in the web/ folder. This should be accessible from the web.

All that's left is to configure your projects to use your new Composer repository by adding it to your projects' composer.json files. Here's an example Composer configuration file-- just change the repository URL to the location of your Packages installation:

{
  "name": "terramar-labs/some-project",
  "repositories": [
    {
      "type": "composer",
      "url": "http://packages.terramarlabs.com/"
    }
  ],
}

And you're set! Code pushes will automatically update Satis and running composer update will resolve your private dependencies with all the great features that Composer offers!