public-mirrors
/
composer
mirror of https://github.com/composer/composer
1
0
Fork 0
Code

Merge pull request #5876 from copitz/patch-1 

Add documentation for providers option
pull/5886/head
Rob 2016-11-18 14:33:33 +01:00 committed by GitHub
parent 30e8845b1e 96540d4139
commit fd5fca615d
1 changed files with 180 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

332
doc/articles/handling-private-packages-with-satis.md
View File

@ -14,16 +14,19 @@ third party systems.
Toran's revenue is also used to pay for Composer and Packagist development and Toran's revenue is also used to pay for Composer and Packagist development and
hosting so using it is a good way to support open source financially. You can hosting so using it is a good way to support open source financially. You can
find more information about how to set it up and use it on the [Toran Proxy](https://toranproxy.com/) website. find more information about how to set it up and use it on the [Toran
Proxy](https://toranproxy.com/) website.
# Satis # Satis
Satis on the other hand is open source but only a static `composer` Satis on the other hand is open source but only a static `composer` repository
repository generator. It is a bit like an ultra-lightweight, static file-based generator. It is a bit like an ultra-lightweight, static file-based version of
version of packagist and can be used to host the metadata of your company's packagist and can be used to host the metadata of your company's private
private packages, or your own. You can get it from [GitHub](https://github.com/composer/satis) packages, or your own. You can get it from
or install via CLI: [GitHub](https://github.com/composer/satis) or install via CLI:
`php composer.phar create-project composer/satis --stability=dev --keep-vcs`. ```
php composer.phar create-project composer/satis --stability=dev --keep-vcs
```
## Setup ## Setup
@ -41,74 +44,75 @@ The default file Satis looks for is `satis.json` in the root of the repository.
```json ```json
{ {
"name": "My Repository", "name": "My Repository",
"homepage": "http://packages.example.org", "homepage": "http://packages.example.org",
"repositories": [ "repositories": [
{ "type": "vcs", "url": "https://github.com/mycompany/privaterepo" }, { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
{ "type": "vcs", "url": "http://svn.example.org/private/repo" }, { "type": "vcs", "url": "http://svn.example.org/private/repo" },
{ "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" } { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
], ],
"require-all": true "require-all": true
} }
``` ```
If you want to cherry pick which packages you want, you can list all the packages If you want to cherry pick which packages you want, you can list all the
you want to have in your satis repository inside the classic composer `require` key, packages you want to have in your satis repository inside the classic composer
using a `"*"` constraint to make sure all versions are selected, or another `require` key, using a `"*"` constraint to make sure all versions are selected,
constraint if you want really specific versions. or another constraint if you want really specific versions.
```json ```json
{ {
"repositories": [ "repositories": [
{ "type": "vcs", "url": "https://github.com/mycompany/privaterepo" }, { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
{ "type": "vcs", "url": "http://svn.example.org/private/repo" }, { "type": "vcs", "url": "http://svn.example.org/private/repo" },
{ "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" } { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
], ],
"require": { "require": {
"company/package": "*", "company/package": "*",
"company/package2": "*", "company/package2": "*",
"company/package3": "2.0.0" "company/package3": "2.0.0"
} }
} }
``` ```
Once you've done this, you just run `php bin/satis build <configuration file> <build dir>`. Once you've done this, you just run `php bin/satis build <configuration file>
For example `php bin/satis build satis.json web/` would read the `satis.json` <build dir>`. For example `php bin/satis build satis.json web/` would read the
file and build a static repository inside the `web/` directory. `satis.json` file and build a static repository inside the `web/` directory.
When you ironed out that process, what you would typically do is run this When you ironed out that process, what you would typically do is run this
command as a cron job on a server. It would then update all your package info command as a cron job on a server. It would then update all your package info
much like Packagist does. much like Packagist does.
Note that if your private packages are hosted on GitHub, your server should have Note that if your private packages are hosted on GitHub, your server should
an ssh key that gives it access to those packages, and then you should add have an ssh key that gives it access to those packages, and then you should add
the `--no-interaction` (or `-n`) flag to the command to make sure it falls back the `--no-interaction` (or `-n`) flag to the command to make sure it falls back
to ssh key authentication instead of prompting for a password. This is also a to ssh key authentication instead of prompting for a password. This is also a
good trick for continuous integration servers. good trick for continuous integration servers.
Set up a virtual-host that points to that `web/` directory, let's say it is Set up a virtual-host that points to that `web/` directory, let's say it is
`packages.example.org`. Alternatively, with PHP >= 5.4.0, you can use the built-in `packages.example.org`. Alternatively, with PHP >= 5.4.0, you can use the
CLI server `php -S localhost:port -t satis-output-dir/` for a temporary solution. built-in CLI server `php -S localhost:port -t satis-output-dir/` for a
temporary solution.
### Partial Updates ### Partial Updates
You can tell Satis to selectively update only particular packages or process only You can tell Satis to selectively update only particular packages or process
a repository with a given URL. This cuts down the time it takes to rebuild the only a repository with a given URL. This cuts down the time it takes to rebuild
`package.json` file and is helpful if you use (custom) webhooks to trigger rebuilds the `package.json` file and is helpful if you use (custom) webhooks to trigger
whenever code is pushed into one of your repositories. rebuilds whenever code is pushed into one of your repositories.
To rebuild only particular packages, pass the package names on the command line like To rebuild only particular packages, pass the package names on the command line
so: like so:
``` ```
php bin/satis build satis.json web/ this/package that/other-package php bin/satis build satis.json web/ this/package that/other-package
``` ```
Note that Note that this will still need to pull and scan all of your VCS repositories
this will still need to pull and scan all of your VCS repositories because any VCS because any VCS repository might contain (on any branch) one of the selected
repository might contain (on any branch) one of the selected packages. packages.
If you want to scan only a single repository and update all packages found in it, If you want to scan only a single repository and update all packages found in
pass the VCS repository URL as an optional argument: it, pass the VCS repository URL as an optional argument:
``` ```
php bin/satis build --repository-url https://only.my/repo.git satis.json web/ php bin/satis build --repository-url https://only.my/repo.git satis.json web/
``` ```
@ -116,19 +120,19 @@ php bin/satis build --repository-url https://only.my/repo.git satis.json web/
## Usage ## Usage
In your projects all you need to add now is your own composer repository using In your projects all you need to add now is your own composer repository using
the `packages.example.org` as URL, then you can require your private packages and the `packages.example.org` as URL, then you can require your private packages
everything should work smoothly. You don't need to copy all your repositories and everything should work smoothly. You don't need to copy all your
in every project anymore. Only that one unique repository that will update repositories in every project anymore. Only that one unique repository that
itself. will update itself.
```json ```json
{ {
"repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ], "repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ],
"require": { "require": {
"company/package": "1.2.0", "company/package": "1.2.0",
"company/package2": "1.5.2", "company/package2": "1.5.2",
"company/package3": "dev-master" "company/package3": "dev-master"
} }
} }
``` ```
@ -142,19 +146,17 @@ Example using a custom repository using SSH (requires the SSH2 PECL extension):
```json ```json
{ {
"repositories": [ "repositories": [{
{ "type": "composer",
"type": "composer", "url": "ssh2.sftp://example.org",
"url": "ssh2.sftp://example.org", "options": {
"options": { "ssh2": {
"ssh2": { "username": "composer",
"username": "composer", "pubkey_file": "/home/composer/.ssh/id_rsa.pub",
"pubkey_file": "/home/composer/.ssh/id_rsa.pub", "privkey_file": "/home/composer/.ssh/id_rsa"
"privkey_file": "/home/composer/.ssh/id_rsa" }
} }
} }]
}
]
} }
``` ```
@ -164,17 +166,15 @@ Example using HTTP over SSL using a client certificate:
```json ```json
{ {
"repositories": [ "repositories": [{
{ "type": "composer",
"type": "composer", "url": "https://example.org",
"url": "https://example.org", "options": {
"options": { "ssl": {
"ssl": { "local_cert": "/home/composer/.ssl/composer.pem"
"local_cert": "/home/composer/.ssl/composer.pem" }
} }
} }]
}
]
} }
``` ```
@ -184,129 +184,157 @@ Example using a custom HTTP Header field for token authentication:
```json ```json
{ {
"repositories": [ "repositories": [{
{ "type": "composer",
"type": "composer", "url": "https://example.org",
"url": "https://example.org", "options": {
"options": { "http": {
"http": { "header": [
"header": [ "API-TOKEN: YOUR-API-TOKEN"
"API-TOKEN: YOUR-API-TOKEN" ]
] }
} }
} }]
}
]
} }
``` ```
### Authentication ### Authentication
When your private repositories are password protected, you can store the authentication details permanently. When your private repositories are password protected, you can store the
The first time Composer needs to authenticate against some domain it will prompt you for a username/password authentication details permanently. The first time Composer needs to
and then you will be asked whether you want to store it. authenticate against some domain it will prompt you for a username/password and
then you will be asked whether you want to store it.
The storage can be done either globally in the `COMPOSER_HOME/auth.json` file (`COMPOSER_HOME` defaults to The storage can be done either globally in the `COMPOSER_HOME/auth.json` file
`~/.composer` or `%APPDATA%/Composer` on Windows) or also in the project directory directly sitting besides your (`COMPOSER_HOME` defaults to `~/.composer` or `%APPDATA%/Composer` on Windows)
composer.json. or also in the project directory directly sitting besides your composer.json.
You can also configure these by hand using the config command if you need to configure a production machine You can also configure these by hand using the config command if you need to
to be able to run non-interactive installs. For example to enter credentials for example.org one could type: configure a production machine to be able to run non-interactive installs. For
example to enter credentials for example.org one could type:
composer config http-basic.example.org username password composer config http-basic.example.org username password
That will store it in the current directory's auth.json, but if you want it available globally you can use the That will store it in the current directory's auth.json, but if you want it
`--global` (`-g`) flag. available globally you can use the `--global` (`-g`) flag.
### Downloads ### Downloads
When GitHub or BitBucket repositories are mirrored on your local satis, the build process will include When GitHub or BitBucket repositories are mirrored on your local satis, the
the location of the downloads these platforms make available. This means that the repository and your setup depend build process will include the location of the downloads these platforms make
on the availability of these services. available. This means that the repository and your setup depend on the
availability of these services.
At the same time, this implies that all code which is hosted somewhere else (on another service or for example in At the same time, this implies that all code which is hosted somewhere else (on
Subversion) will not have downloads available and thus installations usually take a lot longer. another service or for example in Subversion) will not have downloads available
and thus installations usually take a lot longer.
To enable your satis installation to create downloads for all (Git, Mercurial and Subversion) your packages, add the To enable your satis installation to create downloads for all (Git, Mercurial
following to your `satis.json`: and Subversion) your packages, add the following to your `satis.json`:
```json ``` json
{ {
"archive": { "archive": {
"directory": "dist", "directory": "dist",
"format": "tar", "format": "tar",
"prefix-url": "https://amazing.cdn.example.org", "prefix-url": "https://amazing.cdn.example.org",
"skip-dev": true "skip-dev": true
} }
} }
``` ```
#### Options explained #### Options explained
* `directory`: required, the location of the dist files (inside the `output-dir`) * `directory`: required, the location of the dist files (inside the
`output-dir`)
* `format`: optional, `zip` (default) or `tar` * `format`: optional, `zip` (default) or `tar`
* `prefix-url`: optional, location of the downloads, homepage (from `satis.json`) followed by `directory` by default * `prefix-url`: optional, location of the downloads, homepage (from
* `skip-dev`: optional, `false` by default, when enabled (`true`) satis will not create downloads for branches `satis.json`) followed by `directory` by default
* `absolute-directory`: optional, a _local_ directory where the dist files are dumped instead of `output-dir`/`directory` * `skip-dev`: optional, `false` by default, when enabled (`true`) satis will
* `whitelist`: optional, if set as a list of package names, satis will only dump the dist files of these packages not create downloads for branches
* `blacklist`: optional, if set as a list of package names, satis will not dump the dist files of these packages * `absolute-directory`: optional, a _local_ directory where the dist files are
* `checksum`: optional, `true` by default, when disabled (`false`) satis will not provide the sha1 checksum for the dist files dumped instead of `output-dir`/`directory`
* `whitelist`: optional, if set as a list of package names, satis will only
dump the dist files of these packages
* `blacklist`: optional, if set as a list of package names, satis will not
dump the dist files of these packages
* `checksum`: optional, `true` by default, when disabled (`false`) satis will
not provide the sha1 checksum for the dist files
Once enabled, all downloads (include those from GitHub and BitBucket) will be replaced with a _local_ version. Once enabled, all downloads (include those from GitHub and BitBucket) will be
replaced with a _local_ version.
#### prefix-url #### prefix-url
Prefixing the URL with another host is especially helpful if the downloads end up in a private Amazon S3 Prefixing the URL with another host is especially helpful if the downloads end
bucket or on a CDN host. A CDN would drastically improve download times and therefore package installation. up in a private Amazon S3 bucket or on a CDN host. A CDN would drastically
improve download times and therefore package installation.
Example: A `prefix-url` of `https://my-bucket.s3.amazonaws.com` (and `directory` set to `dist`) creates download URLs Example: A `prefix-url` of `https://my-bucket.s3.amazonaws.com` (and
which look like the following: `https://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zip`. `directory` set to `dist`) creates download URLs which look like the following:
`https://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zip`.
### Web outputs ### Web outputs
* `output-html`: optional, `true` by default, when disabled (`false`) satis will not generate the `output-dir`/index.html page. * `output-html`: optional, `true` by default, when disabled (`false`) satis
* `twig-template`: optional, a path to a personalized [Twig](http://twig.sensiolabs.org/) template for the `output-dir`/index.html page. will not generate the `output-dir`/index.html page.
* `twig-template`: optional, a path to a personalized
[Twig](http://twig.sensiolabs.org/) template for the `output-dir`/index.html
page.
### Abandoned packages ### Abandoned packages
To enable your satis installation to indicate that some packages are abandoned, add the following to your `satis.json`: To enable your satis installation to indicate that some packages are abandoned,
add the following to your `satis.json`:
```json ```json
{ {
"abandoned": { "abandoned": {
"company/package": true, "company/package": true,
"company/package2": "company/newpackage" "company/package2": "company/newpackage"
} }
} }
``` ```
The `true` value indicates that the package is truly abandoned while the `"company/newpackage"` value specifies that the package is replaced by The `true` value indicates that the package is truly abandoned while the
the `company/newpackage` package. `"company/newpackage"` value specifies that the package is replaced by the
`company/newpackage` package.
Note that all packages set as abandoned in their own `composer.json` file will be marked abandoned as well. Note that all packages set as abandoned in their own `composer.json` file will
be marked abandoned as well.
### Resolving dependencies ### Resolving dependencies
It is possible to make satis automatically resolve and add all dependencies for your projects. This can be used It is possible to make satis automatically resolve and add all dependencies for
with the Downloads functionality to have a complete local mirror of packages. Just add the following your projects. This can be used with the Downloads functionality to have a
to your `satis.json`: complete local mirror of packages. Just add the following to your `satis.json`:
```json ```json
{ {
"require-dependencies": true, "require-dependencies": true,
"require-dev-dependencies": true "require-dev-dependencies": true
} }
``` ```
When searching for packages, satis will attempt to resolve all the required packages from the listed repositories. When searching for packages, satis will attempt to resolve all the required
Therefore, if you are requiring a package from Packagist, you will need to define it in your `satis.json`. packages from the listed repositories. Therefore, if you are requiring a
package from Packagist, you will need to define it in your `satis.json`.
Dev dependencies are packaged only if the `require-dev-dependencies` parameter is set to true. Dev dependencies are packaged only if the `require-dev-dependencies` parameter
is set to true.
### Other options ### Other options
* `output-dir`: optional, defines where to output the repository files * `providers`: optional, `false` by default, when enabled (`true`) each
if not provided as an argument when calling the `build` command. package will be dumped into a separate include file which will be only
* `config`: optional, lets you define all config options from composer, except `archive-format` and `archive-dir` as the configuration is done through [archive](#downloads) instead. See loaded by composer when the package is really required. Speeds up composer
handling for repositories with huge number of packages like f.i. packagist.
* `output-dir`: optional, defines where to output the repository files if not
provided as an argument when calling the `build` command.
* `config`: optional, lets you define all config options from composer, except
`archive-format` and `archive-dir` as the configuration is done through
[archive](#downloads) instead. See
(http://getcomposer.org/doc/04-schema.md#config) (http://getcomposer.org/doc/04-schema.md#config)
* `notify-batch`: optional, specify a URL that will be called every time a user installs a package. See (https://getcomposer.org/doc/05-repositories.md#notify-batch) * `notify-batch`: optional, specify a URL that will be called every time a
user installs a package. See
(https://getcomposer.org/doc/05-repositories.md#notify-batch)