How to add 3rd party repositories
There is some confusion how to add 3rd party repositories to Debian based distros. In part because best practice has changed a few times and also because there are lots of incorrect info floating around everywhere and it is copy & pasted over and over.
How does repositories work
A debian package repository is nothing more than straight files on a webserver, layed out in a particular way. To make sure the packages we are downloading and installing haven't been tampered with, debian package system (apt) uses SHA256 file hashes. To make sure the file hashes haven't been tampered with, debian uses cryptographically signed files, aka gpg keys or openpgp keys.
Debian and Ubuntu already comes pre-installed with their own gpg keys but we need to add 3rd party repositories manually or in some case through pre-built packages.
Finding the gpg key
There is no standard location where to find the gpg key needed but usually the file is on the repository website and it's exact URL in the installation instructions.
Let's use postgreSQL as an example.
Looking at their outdated documentation we will find the repositories public key at https://www.postgresql.org/media/keys/ACCC4CF8.asc
Binary and ascii armored gpg keys
Keys can be in binary format or ascii encoded (aka ascii armored). Debian package system can handle both but the files need to have the proper file extension.
- binary files should be
*.gpg
- ascii armored should be
*.asc
Most package repositories use ascii armored key files but it can have any name regardless. Common examples are:
- *.gpg
- * .asc
- * .key
- *.gpg.key
How to determine what type of key file
If we open the key file we can immediately verify what type of key it is because ascii armored keys start with -----BEGIN PGP PUBLIC KEY BLOCK-----
To show the start of the file straight from the shell run:
curl -sL https://www.postgresql.org/media/keys/ACCC4CF8.asc | head -1
Where to add the key file
To add this key to your system it should be placed in /etc/apt/keyrings/ and nowhere else. For more info run man sources.list on a current debian distro.
Older distros doesn't have that directory but you can just create it it as root with mkdir /etc/apt/keyrings . It should get the right permissions but it's 0755.
So to get the key from PostgreSQL using curl and put it in the right place do this as root:
curl -sL https://www.postgresql.org/media/keys/ACCC4CF8.asc > /etc/apt/keyrings/postgresql.asc
Add repository info
Now we need to add the repository URL and tell the package system which key to use.
3rd party URL should be added in the /etc/apt/sources.list.d directory by creating one config file for every repository with the name *.list
What distro / code name are we running?
Often we need to know what specific distro and version/code name we are using because package repositories can often handles many different ones.
Debian 12 for example is code name bookworm. If you want to script this you can use $(lsb_release -cs) to get the code name (needs to have package lsb-release installed).
Note:
If you find a reference to stable in the package repository documentation, it's probably wrong. Stable is used to refer to the current stable debian distro, but that changes every two years as soon as a new version becomes stable. And that breaks your repository information. Best practice is to use the code name and not stable.
Content of the config files for apt
The config file we are creating for postgreSQL should have the following basic info:
deb http://apt.postgresql.org/pub/repos/apt bookworm-pgdg main
But we also need to add the information about what key to use:
deb [signed-by=/etc/apt/keyrings/postgresql.asc] http://apt.postgresql.org/pub/repos/apt bookworm-pgdg main
To create the config file as root do:
echo "deb [signed-by=/etc/apt/keyrings/postgresql.asc] http://apt.postgresql.org/pub/repos/apt bookworm-pgdg main" > /etc/apt/sources.list.d/postgresql.list
Run man sources.list for more info on what options are avalable in the apt config files.
Checking that the repository is up
Run apt update and the new repository should appear.
So you see The following signatures couldn't be verified because the public key is not available ?
Then something is wrong with your key file or it's location.
If everything looks good your system is ready to install packages from the new repository with apt install
Check repositories and priority
Run apt policy if you want to check what repositories your system have.
This also show the priorities of the different repositories and tells apt what to do when the same package is available in different repositories. Run man apt_preferences for more info on that.
Misc tools
- To list what packages you have installed on your system run
dpkg -l
- To check what version a package is and what repository will be used to install it, run
apt info <packagename> - for example apt info postgresql
Uninstall repository
To uninstall a 3rd party repository we just need to:
- remove the config file from /etc/apt/sources.list.d
- remove the key file from /etc/apt/keyrings
And then run apt update to refresh the package list.
In our example:
rm /etc/apt/sources.list.d/postgresql.list
rm /etc/apt/keyrings/postgresql.asc
apt update
Things to look out for
- don't use
apt-key, it has been deprecated
- don't put keys anywhere but
/etc/apt/keyrings, it's outdated
- no need to convert key types with
gpg - if you see gpg used you know it's outdated
- don't run unvetted install scripts as root to install 3rd party packages, it's unsafe. Looks like this:
curl unknownscript.sh | bash -
- verify that you actually need the 3rd party repository with your current version - in many cases you don't
- check that you have the packages needed. Debian minimal install doesn't have
curl installed by default for example
- you need either
curl or wget to download files - when you see both used in a script you know it's a mishmash of multiple sources
