Composer and global tools

Composer is the tool that installs your PHP dependencies, and every Laravel, Symfony and WordPress deployment on SrvYard relies on it. You rarely touch it directly: SrvYard installs it with PHP and runs composer install in the deploy script. What you do need to know is how to let it reach private packages (a paid Nova licence, a company registry, a private GitHub package) and where tools that you install globally end up.

This article covers both, together with the npm equivalent, because private npm registries are set up on the same page.

Before you begin#

• A server in the Ready state and the permission to manage packages on it.
• The credentials for the private repository: the host name, a username, and a password or token. For Packagist's private repositories, Nova and similar services, the vendor shows them in your account. Use a read-only token wherever the vendor allows it.
• Know which user runs your site. With Use website isolation on, each site has its own Linux user. Without it, sites run as the server's main user (srvyard on the demo server). Credentials are written for one user.

1. Where Composer comes from#

When SrvYard sets up PHP on a server, it installs Composer once, globally, as /usr/local/bin/composer, if the command is not there already. Every PHP version uses the same Composer, and every site user can run it. The deploy script that SrvYard generates for a PHP site runs, with the site's own PHP on the path:

composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev

There is no button to update Composer itself. To update it, sign in over SSH and run sudo composer self-update. If a project needs a different Composer version, keep a project-local composer.phar in the repository and call it from your own deploy script.

2. Give a server access to a private repository#

Open the server and choose Packages. The page is called Package authentication and explains the rule in one sentence: credentials are written to the files of a user on this server. They apply to every site that runs as that user; a site's own credentials win for the same repository.

1. Composer. The card says The http-basic part of auth.json. Secrets are encrypted in SrvYard and never shown again. With nothing configured it shows No Composer credentials yet and an Add credential button.
2. npm. The same for the user's .npmrc: Auth tokens of the user's .npmrc. It has its own Add credential button.

Press Add credential on the Composer card.

1. User. The Linux user whose file receives the credential. The text under the field says: The credential is written to this user's own file. Sites run as their own user, so pick the site's user to give just that site access. Choose the main user to give every site that shares it access.
2. Repository. The host name only, for example repo.packagist.com, without https://. Anything else is refused with Enter the host name of the repository.
3. Username. Letters, numbers and . _ @ + -.
4. Password or token. 4 to 500 characters. It is hidden while you type (press the eye to check it), stored encrypted, and never shown again.
5. Add credential. Writes the credential to ~/.config/composer/auth.json of that user, as the http-basic entry for the host, with permissions that only that user can read (mode 0600).

The credential appears in the card as a row you can remove. Removing it deletes the entry from the file.

For npm the dialog has the same User field and two more:

1. User. The same meaning as for Composer: the file belongs to that user.
2. Registry. The full address, starting with https://, for example https://npm.pkg.github.com. A trailing slash is removed.
3. Scope (optional). A scope such as @acme sends all packages of that scope to this registry. Without a scope, the token is only stored for the registry.
4. Add credential. Writes an auth token line to the user's ~/.npmrc. The token is 8 to 500 characters and is encrypted in SrvYard.

3. Give a single site its own credentials#

A credential that only one site should use belongs on the site. Open the site, choose Settings, and then Composer (or npm) in the menu on the left.

1. Composer authentication. The card says Credentials for private Composer repositories, stored encrypted and written to auth.json in the site folder (or ~/.config/composer/auth.json for a site with its own user). Three fields, Repository, Username and Password or token, and the Save credential button.
2. Save credential. Stores it and writes it on the server. The credential applies to the next deployment and to every Composer command that runs in that site's folder.

The new site form offers the same for a site you have not created yet: Advanced settings has Composer authentication and npm authentication sections, so the first deployment can already install private packages.

4. Global tools#

Tools that you install with composer global require (the Laravel installer, PHP CS Fixer, Psalm and so on) are installed into the user's home. When SrvYard prepares a site user it adds these two folders to the user's login shell, in this order:

• ~/.srvyard/bin, for tools that SrvYard itself installs for that user.
• ~/.config/composer/vendor/bin, where composer global require puts its executables.

So signing in as the site user and running composer global require laravel/installer makes laravel available in the next login shell. Global tools belong to the user, not the server: a tool installed for one site's user is not there for another. For tools that every user needs, install them system-wide with apt, or add them to each project as a dev dependency instead. That is also more reproducible, because the version is pinned in composer.lock.

Scheduled commands and deploy scripts do not read your login profile in every case. Call global tools by their full path (~/.config/composer/vendor/bin/laravel) in scripts.

Troubleshooting#

• "Could not authenticate against repo.packagist.com" or a 401/403 during a deployment. The credential is missing, expired or written for another user. Check that the User matches the site's user and that the host is exact. A site credential for the same host wins over the server one, so a wrong site credential breaks a good server one.
• "Enter the host name of the repository, for example repo.packagist.com." You pasted a URL. Remove https:// and any path.
• "The username may contain letters, numbers and . _ @ + - only." Remove spaces and other symbols; if the vendor gives you a token as the username, use that token.
• The registry says "unauthorized" for npm. The scope or registry address is wrong. A scoped package (@acme/ui) only uses the registry that has its scope.
• The server must be ready before credentials can be changed. The Packages page is read-only while the server is installing or disconnected.
• A removed credential still works. The site has its own credential for the same host, or the file on the server was edited by hand. Remove it on the site's Composer settings page too.

Related#

• Node.js versions and package managers: the Node.js side of builds and registries.
• Choose and switch PHP versions: the PHP Composer runs on.
• Write and test a deploy script: where composer install runs.
• Create a site on your server: add credentials while creating a site.