How We Simplified Private Composer Packages at OT Commerce with Satis

otcommerce — Mon, 07 Sep 2026 08:15:34 +0000

At OT Commerce, we maintain a large PHP ecosystem consisting of multiple services and dozens of internal Composer packages.

Most of these packages are stored in private Bitbucket repositories.

For a long time, our applications accessed them directly through Composer:

{
"repositories": [
{
"type": "git",
"url": "git@bitbucket.org:company/internal-package.git"
}
]
}

This works well when you have a few packages.

But as our infrastructure grew, every project accumulated a long list of private repositories. Developer machines, Docker builds and CI/CD agents also needed SSH access to Bitbucket just to install PHP dependencies.

We decided to simplify this architecture by introducing a private Composer repository based on Satis.

The New Architecture

The package distribution flow at OT Commerce now looks like this:

Bitbucket
↓ SSH
Satis
↓
Composer metadata + ZIP archives
↓
Nginx
↓ HTTPS + Basic Auth
Composer

Satis is deployed as a service in our Docker Swarm and periodically scans our private repositories, generates Composer metadata and builds dist archives for available package versions.

We also use Bitbucket webhooks to trigger builds immediately when packages are updated, while periodic builds remain as a fallback.

Persistent Storage

Two persistent volumes are used by the service.

One stores the generated Composer repository and package archives.

The other stores the VCS cache, preventing Satis from cloning dozens of repositories from scratch whenever the container is recreated.

This makes repository rebuilds significantly faster.

HTTPS and Authentication

The generated repository is served through Nginx and protected with HTTPS and Basic Authentication.

TLS certificates are issued and automatically renewed using Let's Encrypt with an AWS Route53 DNS-01 challenge.

This means we don't need to expose port 80 just for certificate validation.

Composer credentials are stored separately in auth.json, so application repositories contain neither Bitbucket SSH credentials nor private Composer repository passwords.

One Repository Instead of Dozens

The biggest visible change for our PHP projects is very simple.

Instead of maintaining dozens of VCS declarations:

{
"type": "git",
"url": "git@bitbucket.org:company/internal-package.git"
}

applications now use a single repository:

{
"repositories": [
{
"type": "composer",
"url": "https://packages.example.com"
}
]
}

The responsibility is now clearly separated:

Satis → knows how to access source code
Composer → knows how to access packages

Developer machines, Docker builds and CI/CD agents no longer need direct SSH access to every private Bitbucket repository.

Why We Made This Change

OT Commerce has been developed for many years, and our PHP infrastructure has grown together with the platform.

Small infrastructure decisions that work perfectly with five packages don't necessarily scale well when there are dozens of packages and multiple services consuming them.

Moving package distribution behind Satis was not a major architectural rewrite. It was a relatively small change that gave us:

simpler composer.json files;
fewer distributed SSH credentials;
cleaner Docker builds;
simpler CI/CD configuration;
faster dependency installation through dist archives;
centralized package distribution;
clearer security boundaries between source code and package consumers.

Sometimes improving infrastructure isn't about introducing a more complex technology.

It's about removing unnecessary connections between existing components.

For us, Satis provided exactly that separation.

php #composer #devops #docker