Docs: Needs documentation on how to install using .deb files directly

[SidShetye]

Please see https://github.com/dotnet/core/issues/4179

when apt is down, we need a fall backs to download the .deb file and install it locally.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 38f33bad-b152-c53b-1b0a-234c9a075bd7
• Version Independent ID: 565e7432-c4b3-a1c2-8ce3-c8c1a0d8ebe8
• Content: Install .NET Core on Ubuntu 18.04 package manager - .NET Core
• Content Source: docs/core/install/linux-package-manager-ubuntu-1804.md
• Product: dotnet-core
• GitHub Login: @Thraka
• Microsoft Alias: adegeo

[dagood]

Interesting... I've done this before for a different issue to pick out a specific package, but hadn't considered it as a workaround for the periodic outages. I like the idea.

We may also want to consider offering tarball archives of the Debs and RPMs on https://dotnet.microsoft.com/download, because it's hard to find all right RPMs and Debs on https://packages.microsoft.com manually (even while knowing what you're looking for).

We do provide .NET Core as .tar.gz, however it takes more effort to switch over to that installation method from Deb/RPM.

Related, suggestion that we add a general description of the known outages to the docs: https://github.com/dotnet/docs/issues/16670

/cc @leecow @dleeapho @NikolaMilosavljevic

[Thraka]

If someone could write up the general info, I can port it to the docs. I'm not super-skilled in linux, although I can get around.

[dagood]

Well, here's a general process:

1. Navigate to the root directory where Debs/RPMs are hosted.
   
   
   
   • E.g. https://packages.microsoft.com/ubuntu/18.04/prod/pool/main/
   
   
   • E.g. https://packages.microsoft.com/fedora/30/prod/
   
   
2. Find the root package you want to install.
   
   
   
   • E.g. dotnet-sdk-3.1, aspnetcore-runtime-3.1, or dotnet-runtime-3.1.
   
   
3. Download the highest version of that package. Install the package from file. Observe the error message.
   
   
   
   • Command varies per distro. In my experience, some package managers accept ordinary install {file} commands, but others you need to use the underlying tool like dpkg or rpm.
   
   
   • At least some package managers support installing a package from a URL, so download and install can be combined there.
   
   
4. Find each missing required Deb/RPM in the repo, download them.
5. Repeat (3-4) until no errors.

It's unfortunately not as simple as "here's a set of URLs, just replace the version number" because we don't update every single package during every single servicing release. E.g. dotnet-sdk-3.0=3.0.102 depends on dotnet-targeting-pack-3.0 (>= 3.0.0).

(This also makes it hard to release a tarball of all RPMs/Debs required for a certain release, because we'd have to harvest them from previous releases.)

[leecow]

We currently do not publish the Linux native installer packages to the same location as the rest of the release. That could certainly be changed.

I like the idea of bundling the needed deb/rpm packages to simplify the experience. We could also go as far as including a bash script that drives the installation so that the experience is simply: download, unpack the tar to a directory, run the script.

[Thraka]

I think we need these instructions a bit better. It's hard to explain this in generic terms. For example, the two URLs you posted for the distros have different pathing schemes. If there are different commands on different distros, this needs to be called out.

Also, if the original problem is related to using APT to download from that repo path, isn't that going to just fail manually downloading?

I think it's better to tell them to download from the download page: https://dotnet.microsoft.com/download/dotnet-core/3.1 and once they have the version they want, here are the instructions to install.

[dagood]

I think we need these instructions a bit better.

Yeah... the general steps I gave would require some fairly deep research to figure out how to apply them, and even once they make sense, they'd be intensely tedious. I don't think it makes sense to add the steps to the documentation as they'd have to be done today.

Also, if the original problem is related to using APT to download from that repo path, isn't that going to just fail manually downloading?

The common problem is actually about the deb/rpm file being out of sync with a centralized repo manifest. Downloading the files manually would work fine there. (The manifest is the part that lags behind.) In other cases, yeah, there would still be a problem if the file itself is bad, but it's not the type of outage we normally see.

I think it's better to tell them to download from the download page: https://dotnet.microsoft.com/download/dotnet-core/3.1 and once they have the version they want, here are the instructions to install.

I don't understand what the suggestion is vs. what we have today--following this flow is one way to get to this page.

Are you suggesting that we recommend the binary/tarball downloads instead? That's what I'm referring to here:

We do provide .NET Core as .tar.gz, however it takes more effort to switch over to that installation method from Deb/RPM.

(It also ends up in a worse state: they no longer have automatic updates, so may miss security updates unless they remember to switch back to rpm/deb, manually keep track, or implement infra to use releases.json.)

---

I think that if we're going to do anything in the short term, this is the minimum:

I like the idea of bundling the needed deb/rpm packages to simplify the experience. We could also go as far as including a bash script that drives the installation so that the experience is simply: download, unpack the tar to a directory, run the script.

However, keep in mind that we are pushing the service owners to improve quality: https://github.com/dotnet/core/issues/4167.

[Thraka]

Really the easy solution for this is to do what @leecow suggested as a possibility:

We currently do not publish the Linux native installer packages to the same location as the rest of the release. That could certainly be changed.

If that happens, the instructions seem pretty straightforward for downloading the installer and getting this properly installed.

I agree, the tarball isn't optimal.

[leecow]

To be clear on the install instructions - Linux native installers are not a single bundle like Mac and Windows but are single component installers. So, the instructions would need to list the entire file set and explicit order they are installed. See an example in the 3.1 preview install instructions.

[dagood]

That's referring to (or I guess along the same lines--some minor disparity I didn't see at first) the suggestion I posted earlier:

We may also want to consider offering tarball archives of the Debs and RPMs on https://dotnet.microsoft.com/download, because it's hard to find all right RPMs and Debs on https://packages.microsoft.com manually (even while knowing what you're looking for).

It's not trivial from the release perspective, since not all packages are built during every release--some packages have to be brought forward and redisted in the next. Once we do that manual work once, though, it shouldn't be too hard to pull down the last release, update it with the current patch, and reupload. Definitely seems worth doing.

[leecow]

Davis, are you thinking of building a single tar.gz which contains the correct installer set?

[dagood]

So, the instructions would need to list the entire file set and explicit order they are installed.

It's worked fine for me to include all packages in a single install command. I use apt install ./*.deb and stuff like that.

[dagood]

Davis, are you thinking of building a single tar.gz which contains the correct installer set?

Yes, as an artifact of the release process, since we don't have access to the necessary bits at build-time.

[leecow]

@nakarnam as fyi

[dagood]

To be clear on the install instructions - Linux native installers are not a single bundle like Mac and Windows but are single component installers. So, the instructions would need to list the entire file set and explicit order they are installed. See an example in the 3.1 preview install instructions

I tried this out with a fresh ubuntu:19.04 Docker container, and the instructions are missing netstandard-targeting-pack-2.1, but after getting that and putting them all in the same dir, apt install ./*.deb does work fine. It installs the platform dependencies as well.

So as a note to the current effort: we need to be careful to include the right netstandard-targeting-pack-x.y when these are produced.

[leecow]

I just gave this a whirl on Fedora and it did use packages.microsoft.com to satisfy any missing dependencies such as the targeting pack which wasn't updated.

=============================================================================================================================
 Package                                 Architecture    Version                   Repository                            Size
==============================================================================================================================
Installing:
 aspnetcore-runtime-3.1                  x86_64          3.1.2-1                   @commandline                         7.5 M
 aspnetcore-targeting-pack-3.1           x86_64          3.1.2-1                   @commandline                         1.4 M
 dotnet-apphost-pack-3.1                 x86_64          3.1.2-1                   @commandline                          67 k
 dotnet-host                             x86_64          3.1.2-1                   @commandline                          39 k
 dotnet-hostfxr-3.1                      x86_64          3.1.2-1                   @commandline                         148 k
 dotnet-runtime-3.1                      x86_64          3.1.2-1                   @commandline                          29 M
 dotnet-runtime-deps-3.1                 x86_64          3.1.2-1                   @commandline                         2.8 k
 dotnet-sdk-3.1                          x86_64          3.1.102-1                 @commandline                          64 M
Installing dependencies:
 compat-openssl10                        x86_64          1:1.0.2o-7.fc30           updates                              1.1 M
 dotnet-targeting-pack-3.1               x86_64          3.1.0-1                   packages-microsoft-com-prod          3.4 M
 netstandard-targeting-pack-2.1          x86_64          2.1.0-1                   packages-microsoft-com-prod          2.1 M

Or would we want these archives to be complete?

[dagood]

Or would we want these archives to be complete?

With the goal being an alternative when the AzLinux service is down, yes, they must be. For non-production preview instructions I suppose we care less, but it made for a nice trial run.

[dagood]

We could tell people to download a tarball of RPM/Debs for every release (3.0.0, 3.0.1, 3.0.2, ...) and pick out the RPMs/Debs they require, but that brings us back to a bad/undocumentable UX.

[leecow]

I like the idea of making them standalone. This will make the workflow pretty easy for folks to automate and it should be very stable.

[SidShetye]

IMHO, whatever path the team takes, it needs to be a one liner. Try

source < (curl -s https://example.com/install-dotnet.sh)

The scrips itself then figures out what needs to be pulled from where, in what order and installed where.

[Thraka]

@leecow @dagood Is there a direction decided on this? Should I just remove this from the march sprint (documentation wise) and move it to the next sprint?

[dagood]

It seems to me we've determined in this thread this isn't something we can adequately document--we need additional artifacts to make it reasonable. I don't think it makes sense to have this as a scheduled issue on the docs side of things.

[Thraka]

@SidShetye We're going to close this for now. As the product team is aware of the issue, they'll work on this from that side. I'll close this doc request for now. Thanks.

[dagood]

Filed https://github.com/dotnet/core/issues/4379 to concretely track creating/releasing the artifacts we've been talking about.

[leecow]

I'm running some experiments over the weekend and we'll use 5.0 Preview 1 validate and flesh out the experience. After that, we can move the guidance into Docs.