Repositories: Difference between revisions

From Alpine Linux
(→‎Overview: changed overview to Managing repositories and made a few changes to reflect the change.)
m (replaced link)
 
(36 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{TOC right}}
{{TOC right}}


The Alpine software repositories have three branches:
A [https://en.wikipedia.org/wiki/Software_repository repository] is a storage location with a collection of Alpine Linux [[Alpine Package Keeper#Packages and Repositories|packages]]. [[Alpine Package Keeper|APK]] loads repository definitions from {{Path|/etc/apk/repositories}} file first and has various sub-commands to query and manipulate [[Alpine_Package_Keeper#World|world]] and package repositories. There are three official package repositories available in Alpine Linux.


* '''main''' packages are the software that have direct support and updates from the Alpine core and main team. They also have official special documentation, are always available for all releases and will have substitutions if some are not continued from upstream. Commonly these packages are selected due to their responsibility and stability with respect to upstream availability. Packages from ''community'' or (rarely) ''testing'', that are accepted go to the ''main'' branch.
== Official repositories ==


* '''community''' packages are those made by users in team with the official developers and close to the Alpine package process. They are supported by those user(s) contributions and could end if the user(s) stops; they may also be removed in a future release due to lack of support by upstream authors. Packages from ''testing'' that are accepted go to the ''community'' branch.
=== Main ===


* '''testing''' packages are where new packages go. These are made by any contributor to Alpine. Testing has no release linked. The ''testing'' repository is only available on ''edge''. Packages from ''testing'' that are accepted go to the ''community'' branch or (rarely) the ''main'' branch.
Packages in '''main''' repository are the software that have direct support and updates from the Alpine core team. Alpine Linux tries to limit the amount of packages in ''main'' to only include base system packages, i.e packages which are needed by other packages or are needed to setup a basic system. Packages in ''main'' must '''not''' have dependencies in other repositories.


= Managing repositories =
Packages in '''main''' repository also have official special documentation, are always available for all releases and will have substitutions if some are not continued from upstream. Commonly these packages are selected due to their responsibility and stability with respect to upstream availability. Packages from ''community'' or (rarely) ''testing'' can be accepted into the ''main'' repository.


To enable a repository, remove the '''#''' in front of the URL along with any blank space.
=== Community ===


Example: Disabled
Packages in '''community''' repository are those made by users in team with the official developers and close to the Alpine package process. They are supported by those user(s) contributions and could end if the user(s) stops; they may also be removed in a future release due to lack of support by upstream authors.  
{{cat|/etc/apk/repositories|#http://dl-cdn.alpinelinux.org/alpine/v3.16/community}}


Example: Enabled
The '''community''' repository was introduced with Alpine Linux version [https://alpinelinux.org/posts/Alpine-3.3.0-released.html 3.3.0]. Packages from ''testing'' that are accepted go to the ''community'' repository.
{{cat|/etc/apk/repositories|http://dl-cdn.alpinelinux.org/alpine/v3.16/community}}


To edit the repositories, open the <code>/etc/apk/repositories</code> file in a text editor:
=== Testing ===


{{cmd|# <editor> /etc/apk/repositories}}
The ''testing'' repository is only available on [[#Edge|edge]] branch i.e development branch and this is where new packages go. These are made by any contributor to Alpine Linux. Packages from ''testing'' that are accepted go to the ''community'' repository or (rarely) to the ''main'' repository. Packages in ''testing'' have no support (staging only) and only built for ''edge''. If it stays here long enough it gets moved to unmaintained/purged (gets cleaned up every 6 months).


The default will look something like:
Before a package can move from ''testing'' to ''main'' or ''community'', the following requirements must be met:


{{cat|/etc/apk/repositories|#/media/cdrom/apks
# Package must work correctly, including the init.d script (if provided) and default configuration.
http://dl-cdn.alpinelinux.org/alpine/v3.16/main
# Packaging must be done correctly, with files installed in the right places, e.g. configs are in <code>/etc/</code> and not in <code>/usr/etc</code>.
#http://dl-cdn.alpinelinux.org/alpine/v3.16/community
# Package dependencies are handled correctly. Abuild can (and should) autodetect shared libs, for example ''sqlite-libs'' provides ''so:libsqlite3.so.0''. Any package linked to ''sqlite'' should have an automatically (by abuild) added <code>depend=so:libsqlite3.so.0</code> and the user should not have to manually add a <code>depend="sqlite-libs"</code> in the APKBUILD.
#http://dl-cdn.alpinelinux.org/alpine/edge/main
# There is a maintainer who claims responsibility for the maintenance of the package and can help fix things if they break in the future.
#http://dl-cdn.alpinelinux.org/alpine/edge/community
#http://dl-cdn.alpinelinux.org/alpine/edge/testing}}


=== Changing repositories to https ===
== Release Branches ==
For better security you should probably change the url's from '''http''' to '''https'''. [https://en.wikipedia.org/wiki/HTTPS#Technical]


{{Note|Some Alpine Linux package mirrors may not support '''https'''. If that is the case, you will need to change mirrors or revert back. You can check if your mirror supports '''https''' on https://mirrors.alpinelinux.org }}
There are several release branches for Alpine Linux available at the same time. Each May and November we make a '''stable''' release branch from ''edge''. '''The current release branch of Alpine Linux is {{#expr:{{AlpineLatest}}}}'''.


=== Avoid manually changing the repositories file for a new release ===
Each stable release branch has its own main and community repositories. The '''main''' repository of every release branch is supported for 2 years. The '''community''' repository of any release branch is supported until next stable release i.e six months. Security fixes beyond that can be made on request, if there are patches available. Support entails security patches for the given feature versions.


You can avoid having to manually update the version in <code>/etc/apk/repositories</code> for each Alpine Linux release by changing <code>v3.16</code> to <code>latest-stable</code>.
{{Note|If packages from community repository are used, one needs to update to the latest release branch to continue to have support.}}


Example:
'''To upgrade''' to the latest release branch, follow the steps in  [[Upgrading_Alpine#Upgrading_to_latest_release|Upgrading Alpine Linux]].
{{cat|/etc/apk/repositories|#/media/cdrom/apks
https://dl-cdn.alpinelinux.org/alpine/latest-stable/main
https://dl-cdn.alpinelinux.org/alpine/latest-stable/community
#http://dl-cdn.alpinelinux.org/alpine/edge/main
#http://dl-cdn.alpinelinux.org/alpine/edge/community
#http://dl-cdn.alpinelinux.org/alpine/edge/testing}}


{{Warning|Changing the repositories to <code>latest-stable</code> may initiate unexpected release upgrades.}}
== Edge ==


= Release Branches =
''edge'' is the name given to the current [[Aports tree|development tree]] of Alpine Linux.  ''edge'' can be considered as '''rolling release version''' of Alpine Linux. This version contains the latest build of all available Alpine Linux packages. Those packages are updated on a regular basis.


There are several release branches for Alpine Linux available at the same time. Each May and November we make a release branch from '''edge'''. The '''main''' repository is typically supported for 2 years and the '''community''' repository is supported until next stable release.
Similar to [[#Release Branches|release branches]] edge consists of '''main''' and '''community''' repositories in addition to the third repository i.e '''testing'''.


Security fixes beyond that can be made on request when there are patches available.
{{Warning|''edge'' is under constant development so be careful using it in production. It is possible that bugs in ''edge'' could cause data loss or could break your system.}}


== Main ==
Since ''edge'' is a development branch, many changes are not heavily tested (or tested at all) and packages in ''edge'' can and sometimes do break without warning. However, testing ''edge'' is a very valuable activity which [[Alpine Linux:Contribute|helps]] the Alpine Linux development to ensure that the quality of the stable releases is high.


By default only the '''main''' repository is enabled. ''main'' has a support cycle of 2 years. We also try to limit the amount of packages in ''main'' to only include base system packages, in base you can think of packages which are needed by other packages or are needed to setup a basic system. Packages in ''main'' must '''not''' have dependencies in other repositories.
== Managing repositories ==


== Community ==
The package repositories that <code>apk</code> uses to retrieve package files for installation are specified in file {{path|/etc/apk/repositories}}. To '''automatically''' configure the repositories file {{path|/etc/apk/repositories}}, use the  [[Alpine setup scripts#setup-apkrepos|setup-apkrepos]] script: {{cmd|# setup-apkrepos -cf}}


The '''community''' repository was introduced with Alpine Linux version [https://alpinelinux.org/posts/Alpine-3.3.0-released.html 3.3.0].  ''community'' has a maximum support cycle of 6 months. After that you will need to update to the new release to continue to have support.
After making changes to {{path|/etc/apk/repositories}} you should update the package index using: {{cmd|# apk update}}


=== Enabling the community repository ===
Each line of {{path|/etc/apk/repositories}} specifies the location of a package repository, one repository per line and optionally a tag. Lines that start with a hash character (#) are ignored.


To enable the repository, edit the file <code>/etc/apk/repositories</code> and add (or uncomment) a line that points to the "community" directory.
The location may be an <code>http://</code> or <code>https://</code> URL, or the path to a directory on the local filesystem. If you booted from a USB stick ({{Path|/media/sda1}}) or CD-ROM ({{Path|/media/cdrom}}), your repository file probably looks something like this: {{Cat|/etc/apk/repositories|/media/sda1/apks/}}


Its format is:
In a properly configured Alpine Linux system, the default will look something like:


<nowiki>https://<mirror-server>/alpine/<version>/community</nowiki>
{{cat|/etc/apk/repositories|#/media/cdrom/apks
http://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
http://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community}}


For example, if your mirror is dl-cdn.alpinelinux.org and you're on version 3.16, add the following line to the repositories file:
{{Note| For better security you should probably change the url's from '''http''' to '''https'''. Some Alpine Linux package mirrors may not support '''https'''. If that is the case, you will need to change mirrors or revert back. You can check if your mirror supports '''https''' on https://mirrors.alpinelinux.org }}


<nowiki>https://dl-cdn.alpinelinux.org/alpine/v3.16/community</nowiki>
=== Tagged repository ===


After enabling the community repository, one needs to update the index of available packages with:
A tagged repository is prefixed with the <code>@tag</code> specifier, followed by a space and the repository location in the {{Path|/etc/apk/repositories}} file as follows.{{Cat|/etc/apk/repositories|https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
{{Cmd|# apk update}}
https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community
And then it's possible to install packages from the community repository.
@personal https:/personal-repo.example.com/alpine-apks/}}


= Edge =
The optional <code>@tag</code>, when used as shown above indicates that the tagged repository should not be used by default.


''edge'' is the name given to the current [[Aports tree|development tree]] of Alpine Linux. It consists of an APK repository called ''edge'' and contains the latest build of all available Alpine Linux packages. Those packages are updated on a regular basis.
[[apk]] will by default only use the untagged repositories. However for constraints with a tag, untagged repositories are also considered. The tag is inherited to all dependencies as an allowed repository. That is, the dependencies are selected from the tagged repository if the name@tag has a dependency with version constraint requiring a version available only from the tagged repository. If the dependency can be satisfied from untagged repository it will be preferred.


{{Warning|''edge'' is under constant development so be careful using it in production. It is possible that bugs in ''edge'' could cause data loss or could break your system.}}
For eg: {{ic|apk add busybox@personal}} enables selection of {{ic|busybox}} from a tagged repository @personal. The above command allows installation of {{ic|busybox}} and it's dependencies from the tagged repository @personal. Since tagged repositories are not prioritized, if a version of {{ic|busybox}} or it's dependencies from an untagged repository is a better fit, it will be used.
 
End users should not use ''edge'' as their main day-to-day workstation or as a productive system. Because ''edge'' is a development branch, many changes are not heavily tested (or tested at all) and packages in ''edge'' can and sometimes do break without warning.
 
However, testing ''edge'' is a very valuable activity which helps the Alpine Linux development to ensure that the quality of the stable releases is high. Testing ''edge'' is a great way to contribute to the Alpine Linux development.


== Upgrading to edge ==
=== Upgrading to edge ===


{{:Include:Upgrading to Edge}}
{{:Include:Upgrading to Edge}}


== Testing ==
=== Using testing repository ===
 
The '''testing''' repository was introduced with Alpine Linux ''edge'' development. No support (staging only) and only built for ''edge''. If it stays here long enough it gets moved to unmaintained/purged (gets cleaned up every 6 months).
 
Before a package can move from ''testing'' to ''main'' or ''community'', the following requirements must be met:
 
# Package must work correctly, including the init.d script (if provided) and default configuration.
# Packaging must be done correctly, with files installed in the right places, e.g. configs are in <code>/etc/</code> and not in <code>/usr/etc</code>.
# Package dependencies are handled correctly. Abuild can (and should) autodetect shared libs, for example '''sqlite-libs''' provides '''so:libsqlite3.so.0'''. Any package linked to '''sqlite''' should have an automatically (by abuild) added <code>depend=so:libsqlite3.so.0</code> and the user should not have to manually add a <code>depend="sqlite-libs"</code> in the APKBUILD.
# There is a maintainer who claims responsibility for the maintenance of the package and can help fix things if they break in the future.
 
=== Enabling the testing repository ===
 
To enable the repository, edit the file <code>/etc/apk/repositories</code> and add (or uncomment) a line that points to the "testing" directory.
 
Its format is:
 
<code><nowiki>https://<mirror-server>/alpine/edge/testing</nowiki></code>
 
After enabling the testing repository, one needs to update the index of available packages with:
{{Cmd|# apk update}}
And then it's possible to install packages from the testing repository.
 
=== Using the testing repository on stable branches ===
 
{{Warning|'''Only do this if you're 100% sure what you're doing!''' Installing packages from edge that link to something in ''main'' or ''community'' usually will not work. Alpine does not officially support mixing branches this way.}}
 
Edit the file <code>/etc/apk/repositories</code> and add (or uncomment) a line that points to the "testing" directory, while also [[Package_management#Repository_pinning|tagging]] the repository, for example:
 
{{Cat|/etc/apk/repositories|
https://dl-cdn.alpinelinux.org/alpine/v3.16/main
https://dl-cdn.alpinelinux.org/alpine/v3.16/community
@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing
}}
 
In that case, the tag is <code>@testing</code>, which allows you to pull packages from that repository without potentially messing up your install (too badly):
 
$ apk add wireguard-go@testing
 
== Unmaintained ==


{{Expand|Maybe also move this somewhere else?}}
Using [[#Testing|testing]] repository with [[#Edge|Edge]] branch is explained in the previous sections. However, installing packages from testing repository in a '''stable''' [[#Release Branches|release branch]] is not recommended and not guaranteed to work. To do this, add '''testing''' repository as a [[#Tagged repository|tagged repository]] by editing the file {{path|/etc/apk/repositories}} as follows:{{Cat|/etc/apk/repositories|https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community
@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing}}


'''unmaintained''' packages are not built.
Do this only if you need package(s) which are available only in [[#Testing|testing]] repository. Ensure that the package does not have [[Alpine_Package_Keeper#Check_Dependencies|version dependencies]] on the other two repositories of the edge branch. In the example command {{ic|# apk add wireguard-go@testing}}, the tag <code>@testing</code> allows [[apk]] to pull the necessary package(s) from that repository without potentially messing up your installation (too badly).


= See also =
== See also ==


* [[Alpine_Package_Keeper|Alpine Package Keeper]]
* [[Alpine_Package_Keeper#World| Alpine Linux '''world''' ]]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-repositories.5.scd Manual for apk-repositories(5)]
* [[Alpine Linux in a chroot]]
* [[Alpine Linux in a chroot]]
* [http://bugs.alpinelinux.org/ Report Bugs]
* [https://bugs.alpinelinux.org/ Report Bugs]


[[Category:Development]]
[[Category:Development]]
[[Category:Package Manager]]
[[Category:Package Manager]]

Latest revision as of 04:49, 25 March 2025

A repository is a storage location with a collection of Alpine Linux packages. APK loads repository definitions from /etc/apk/repositories file first and has various sub-commands to query and manipulate world and package repositories. There are three official package repositories available in Alpine Linux.

Official repositories

Main

Packages in main repository are the software that have direct support and updates from the Alpine core team. Alpine Linux tries to limit the amount of packages in main to only include base system packages, i.e packages which are needed by other packages or are needed to setup a basic system. Packages in main must not have dependencies in other repositories.

Packages in main repository also have official special documentation, are always available for all releases and will have substitutions if some are not continued from upstream. Commonly these packages are selected due to their responsibility and stability with respect to upstream availability. Packages from community or (rarely) testing can be accepted into the main repository.

Community

Packages in community repository are those made by users in team with the official developers and close to the Alpine package process. They are supported by those user(s) contributions and could end if the user(s) stops; they may also be removed in a future release due to lack of support by upstream authors.

The community repository was introduced with Alpine Linux version 3.3.0. Packages from testing that are accepted go to the community repository.

Testing

The testing repository is only available on edge branch i.e development branch and this is where new packages go. These are made by any contributor to Alpine Linux. Packages from testing that are accepted go to the community repository or (rarely) to the main repository. Packages in testing have no support (staging only) and only built for edge. If it stays here long enough it gets moved to unmaintained/purged (gets cleaned up every 6 months).

Before a package can move from testing to main or community, the following requirements must be met:

  1. Package must work correctly, including the init.d script (if provided) and default configuration.
  2. Packaging must be done correctly, with files installed in the right places, e.g. configs are in /etc/ and not in /usr/etc.
  3. Package dependencies are handled correctly. Abuild can (and should) autodetect shared libs, for example sqlite-libs provides so:libsqlite3.so.0. Any package linked to sqlite should have an automatically (by abuild) added depend=so:libsqlite3.so.0 and the user should not have to manually add a depend="sqlite-libs" in the APKBUILD.
  4. There is a maintainer who claims responsibility for the maintenance of the package and can help fix things if they break in the future.

Release Branches

There are several release branches for Alpine Linux available at the same time. Each May and November we make a stable release branch from edge. The current release branch of Alpine Linux is 3.21.

Each stable release branch has its own main and community repositories. The main repository of every release branch is supported for 2 years. The community repository of any release branch is supported until next stable release i.e six months. Security fixes beyond that can be made on request, if there are patches available. Support entails security patches for the given feature versions.

Note: If packages from community repository are used, one needs to update to the latest release branch to continue to have support.

To upgrade to the latest release branch, follow the steps in Upgrading Alpine Linux.

Edge

edge is the name given to the current development tree of Alpine Linux. edge can be considered as rolling release version of Alpine Linux. This version contains the latest build of all available Alpine Linux packages. Those packages are updated on a regular basis.

Similar to release branches edge consists of main and community repositories in addition to the third repository i.e testing.

Warning: edge is under constant development so be careful using it in production. It is possible that bugs in edge could cause data loss or could break your system.


Since edge is a development branch, many changes are not heavily tested (or tested at all) and packages in edge can and sometimes do break without warning. However, testing edge is a very valuable activity which helps the Alpine Linux development to ensure that the quality of the stable releases is high.

Managing repositories

The package repositories that apk uses to retrieve package files for installation are specified in file /etc/apk/repositories. To automatically configure the repositories file /etc/apk/repositories, use the setup-apkrepos script:

# setup-apkrepos -cf

After making changes to /etc/apk/repositories you should update the package index using:

# apk update

Each line of /etc/apk/repositories specifies the location of a package repository, one repository per line and optionally a tag. Lines that start with a hash character (#) are ignored.

The location may be an http:// or https:// URL, or the path to a directory on the local filesystem. If you booted from a USB stick (/media/sda1) or CD-ROM (/media/cdrom), your repository file probably looks something like this:

Contents of /etc/apk/repositories

/media/sda1/apks/

In a properly configured Alpine Linux system, the default will look something like:

Contents of /etc/apk/repositories

#/media/cdrom/apks http://dl-cdn.alpinelinux.org/alpine/v3.21/main http://dl-cdn.alpinelinux.org/alpine/v3.21/community
Note: For better security you should probably change the url's from http to https. Some Alpine Linux package mirrors may not support https. If that is the case, you will need to change mirrors or revert back. You can check if your mirror supports https on https://mirrors.alpinelinux.org

Tagged repository

A tagged repository is prefixed with the @tag specifier, followed by a space and the repository location in the /etc/apk/repositories file as follows.

Contents of /etc/apk/repositories

https://dl-cdn.alpinelinux.org/alpine/v3.21/main https://dl-cdn.alpinelinux.org/alpine/v3.21/community @personal https:/personal-repo.example.com/alpine-apks/

The optional @tag, when used as shown above indicates that the tagged repository should not be used by default.

apk will by default only use the untagged repositories. However for constraints with a tag, untagged repositories are also considered. The tag is inherited to all dependencies as an allowed repository. That is, the dependencies are selected from the tagged repository if the name@tag has a dependency with version constraint requiring a version available only from the tagged repository. If the dependency can be satisfied from untagged repository it will be preferred.

For eg: apk add busybox@personal enables selection of busybox from a tagged repository @personal. The above command allows installation of busybox and it's dependencies from the tagged repository @personal. Since tagged repositories are not prioritized, if a version of busybox or it's dependencies from an untagged repository is a better fit, it will be used.

Upgrading to edge

An upgrade of Alpine Linux from a stable version to the rolling development version edge basically requires the same steps as Upgrading to latest release.

The crucial difference is, that when editing the /etc/apk/repositories file, all referenced repository versions (such as v3.21 or latest-stable) therein need to be pointing to edge as follows.

Contents of /etc/apk/repositories

#/media/cdrom/apks http://dl-cdn.alpinelinux.org/alpine/edge/main http://dl-cdn.alpinelinux.org/alpine/edge/community http://dl-cdn.alpinelinux.org/alpine/edge/testing

When using edge branch, testing repository can be added as shown above. Installing packages from testing repository with Edge branch and submitting bug reports is one of the best ways to contribute to Alpine Linux. Remember that, packages in testing repository have no support.

Warning: Do not enable stable release branch and edge repos at the same time. This can break your system. Either use edge or stable. If you mix stable and edge repositories, you're on your own.


After upgrading to edge, the currently installed edge version i.e the build date that is attached to the edge release may be checked with command:

$ cat /etc/alpine-release

Using testing repository

Using testing repository with Edge branch is explained in the previous sections. However, installing packages from testing repository in a stable release branch is not recommended and not guaranteed to work. To do this, add testing repository as a tagged repository by editing the file /etc/apk/repositories as follows:

Contents of /etc/apk/repositories

https://dl-cdn.alpinelinux.org/alpine/v3.21/main https://dl-cdn.alpinelinux.org/alpine/v3.21/community @testing https://dl-cdn.alpinelinux.org/alpine/edge/testing

Do this only if you need package(s) which are available only in testing repository. Ensure that the package does not have version dependencies on the other two repositories of the edge branch. In the example command # apk add wireguard-go@testing, the tag @testing allows apk to pull the necessary package(s) from that repository without potentially messing up your installation (too badly).

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Repositories&oldid=29446"