Clarify version pinning for APT

[sandstrom]

Thanks for an awesome project! 🏅

Short problem description

When pinning to a version, one must specify passenger with the same version.

I realize that the suggested change (this PR) isn't enough, since your install instructions is dynamic.

However, I'd like to help improve the documentation around this, perhaps in an info-box or similar.

But before I suggest more changes I'd like to hear your thoughts on this, just to make sure I've understood the issue correctly!

Longer problem description

Ran into an issue where our install wouldn't work:

sudo apt install libnginx-mod-http-passenger=1:5.3.1-1~bionic1
Reading package lists... Done
Building dependency tree       
Reading state information... Done
Some packages could not be installed. This may mean that you have
requested an impossible situation or if you are using the unstable
distribution that some required packages have not yet been created
or been moved out of Incoming.
The following information may help to resolve the situation:

The following packages have unmet dependencies:
 libnginx-mod-http-passenger : Depends: passenger (= 1:5.3.1-1~bionic1) but it is not going to be installed
E: Unable to correct problems, you have held broken packages.

However, when pinning the passenger package too it works:

sudo apt install libnginx-mod-http-passenger=1:5.3.1-1~bionic1 passenger=1:5.3.1-1~bionic1
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following additional packages will be installed:
  fonts-lato javascript-common libjs-jquery libruby2.5 rake ruby ruby-did-you-mean ruby-minitest ruby-net-telnet ruby-power-assert ruby-rack ruby-test-unit ruby2.5 rubygems-integration zip
Suggested packages:
  ri ruby-dev bundler
Recommended packages:
  passenger-doc passenger-dev
The following NEW packages will be installed:
  fonts-lato javascript-common libjs-jquery libnginx-mod-http-passenger libruby2.5 passenger rake ruby ruby-did-you-mean ruby-minitest ruby-net-telnet ruby-power-assert ruby-rack ruby-test-unit ruby2.5 rubygems-integration zip
0 upgraded, 17 newly installed, 0 to remove and 17 not upgraded.
Need to get 9,007 kB of archives.
After this operation, 41.2 MB of additional disk space will be used.
Do you want to continue? [Y/n] n

This is the content of the apt source:

cat /etc/apt/sources.list.d/passenger-nginx.list 
deb      "https://oss-binaries.phusionpassenger.com/apt/passenger" bionic main

[CamJN]

We're currently in the middle of a big update to the passenger library, however when we're done it would be great to have a page explaining package pinning int he advanced guides section.

[sandstrom]

Thanks for the update @CamJN!

A related issue, that is somewhat outside your domain but something that I expect may be common for your users anyway, is Nginx installs and version numbers.

A few weeks ago we could install this nginx version without any trouble:

sudo apt install nginx-extras=1.14.0-0ubuntu1

But today this don't work anymore (example below). The difference is an additional .1 at the end of the version string (1.14.0-0ubuntu1 vs. 1.14.0-0ubuntu1.1).

Perhaps some instructions around how to solve this could also be helpful in an advanced guides section.

sudo apt install nginx-extras=1.14.0-0ubuntu1
Reading package lists... Done
Building dependency tree       
Reading state information... Done
Some packages could not be installed. This may mean that you have
requested an impossible situation or if you are using the unstable
distribution that some required packages have not yet been created
or been moved out of Incoming.
The following information may help to resolve the situation:

The following packages have unmet dependencies:
 nginx-extras : Depends: libnginx-mod-http-auth-pam (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-cache-purge (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-dav-ext (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-echo (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-fancyindex (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-geoip (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-headers-more-filter (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-image-filter (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-lua (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-perl (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-subs-filter (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-uploadprogress (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-upstream-fair (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-http-xslt-filter (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-mail (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-nchan (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: libnginx-mod-stream (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
                Depends: nginx-common (= 1.14.0-0ubuntu1) but 1.14.0-0ubuntu1.1 is to be installed
E: Unable to correct problems, you have held broken packages.

I'm guessing the issue here is that version pinning isn't a good idea for Ubuntu (and other distros). Instead one should rely on them not introducing breaking changes within a stable OS release (18.04, for example).

@CamJN Are there any guarantees around breaking changes for your repo? (https://oss-binaries.phusionpassenger.com/apt/passenger)

I.e. can we drop the version pinning and not have to worry about a new version when our chef script runs 12 months from now?