Alpine Linux

Alpine Linux - what is needed pkgs (Part 4) - repository maintenance

Some questions answered here.

  1. How do I maintain my partial repository.
  2. How do I upgrade my custom curated apk pkgs folder.


  • Content on this page only applies to disk-less boots.
  • Target audience: Alpine Linux intermediate+
  • Caveat: Maintaining your partial repository involves risks. Read all parts(1-5) carefully and experiment with it, before running a production setup on it.

Directory/files structures - of Alpine master boot disk

(1)
/media/sda1/
|-- alpine
|   `-- v3.22
|       `-- releases
|           `-- alpine-extended-3.22.0-x86_64.iso
|-- apks   <- installed from alpine-extended-3.22.0-x86_64.iso
|-- ...
|-- apks2   <- custom curated apk pkgs folder
|   `-- v3.22
|       |-- fetch-apk.sh   <- helper script to download apks
|       |-- main
|       |   `-- x86_64
|       |       |-- APKINDEX.tar.gz
|       |       `-- ... .apk
|       `-- community
|           `-- x86_64
|               |-- APKINDEX.tar.gz
|               `-- ... .apk
|-- boot
|-- ...
|-- cache
|   `-- installed
|-- efi
|-- ...
`-- lost+found
  • Above is layout of master disk-less boot disk meant for devices/vm running version 3.22.0-x86_64.

About master boot disk

  • This can be created by combining (Part 1) + True-diskless-boot
  • Disk can be used to serve/share /apks2 over local lan.
  • Keep your master setup safe.
    • If using sd-card keep it locked when setup is complete.
    • Periodically writing your apkovl configs+apks2 to DVD can also be done.

About directory structure

This section explains directory structure as in (1) above.

About /apks2

1. Directory structure is similar to official CDN/repository, can be used in /etc/apk/repositories from another Alpine Linux' disk-less installs, or same booted disk, eg. 

# cat /etc/apk/repositories
/media/sda1/apks

# on same booted disk
# /media/sda1/apks2/v3.22/main
# /media/sda1/apks2/v3.22/community

# on another booted Alpine-Linux
http://192.168.1.100:8080/apks2/v3.22/main
http://192.168.1.100:8080/apks2/v3.22/community

See (Part 1), How-to-share-you-apks-repo (Part 3)

2. /apks2 can be updated/upgraded from internet connected device.

About APKINDEX.tar.gz
  • It is signed index for all packages from official repository/cdn.[2]
  • In your partial repository this file needs to be present.
  • Officially signed APKINDEX.tar.gz for limited packages in your partial repository is currently not possible.
About fetch-apk.sh
  • fetch-apk.sh is script [3],
    • That lets you download your applications packages along-with their dependencies.
    • Downloaded .apk pkgs can be then can be organized like local repository mirror.
NOTE:
  • sh fetch-apk.sh [main|community] [getindex|mklist|fetch]
1a. download APKINDEX.tar.gz for main/
localhost:/media/sda1/apks2/v3.22# sh fetch-apk.sh main getindex
>>> set branch: main
>>> fetching: https://cdn.alpinelinux.org/alpine/v3.22/main/x86_64/APKINDEX.tar.gz
--2025-11-17 12:34:35--  https://cdn.alpinelinux.org/alpine/v3.22/main/x86_64/APKINDEX.tar.gz
Resolving cdn.alpinelinux.org (cdn.alpinelinux.org)... 199.232.58.132, 2a04:4e42:42::644
Connecting to cdn.alpinelinux.org (cdn.alpinelinux.org)|199.232.58.132|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 499995 (488K) [application/octet-stream]
Saving to: 'APKINDEX.tar.gz'

APKINDEX.tar.gz   100%[======================================>] 488.28K   272KB/s    in 1.8s    

2025-11-17 12:34:38 (272 KB/s) - 'APKINDEX.tar.gz' saved [499995/499995]

>>> OLD index has be backed-up to v3.22.2-206-ge2cfd1f9853
>>> NOTE: remember to move both APKINDEX.tar.gz to their branch/arch folder
>>> Moving index files to main/x86_64
1b. download APKINDEX.tar.gz for community/
localhost:/media/sda1/apks2/v3.22# sh fetch-apk.sh community getindex
>>> set branch: community
>>> fetching: https://cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
--2025-11-17 13:00:34--  https://cdn.alpinelinux.org/alpine/v3.22/community/x86_64/APKINDEX.tar.gz
Resolving cdn.alpinelinux.org (cdn.alpinelinux.org)... 199.232.22.132, 2a04:4e42:42::644
Connecting to cdn.alpinelinux.org (cdn.alpinelinux.org)|199.232.22.132|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 2093729 (2.0M) [application/octet-stream]
Saving to: 'APKINDEX.tar.gz'

APKINDEX.tar.gz   100%[======================================>]   2.00M   348KB/s    in 6.3s    

2025-11-17 13:00:41 (324 KB/s) - 'APKINDEX.tar.gz' saved [2093729/2093729]

>>> OLD index has be backed-up to v3.22.2-214-g33de1eff6af
>>> NOTE: remember to move both APKINDEX.tar.gz to their branch/arch folder
>>> Moving index files to community/x86_64
NOTE:
  • Remember: you only need to run getindex once, to make sure your repository snapshot is fixed to that version of APKINDEX.tar.gz file.

1c. make note of their version and freeze copy of index files
localhost:/media/sda1/apks2/v3.22# ls -lah main/x86_64/APK*
-rw-r--r-- 1 root root 489K Nov 16 16:54 main/x86_64/APKINDEX-v3.22.2-206-ge2cfd1f9853.tar.gz
-rw-r--r-- 1 root root 489K Nov 16 16:54 main/x86_64/APKINDEX.tar.gz

localhost:/media/sda1/apks2/v3.22# ls -lah community/x86_64/APK*
-rw-r--r-- 1 root root 2.0M Nov 18 04:02 community/x86_64/APKINDEX-v3.22.2-214-g33de1eff6af.tar.gz
-rw-r--r-- 1 root root 2.0M Nov 18 04:02 community/x86_64/APKINDEX.tar.gz
2a. add packages
localhost:/media/sda1/apks2/v3.22# apk add 7zip
(1/1) Installing 7zip (24.09-r0)
ERROR: 7zip-24.09-r0: package mentioned in index not found (try 'apk update')
1 error; 1835 MiB in 848 packages
NOTE:

"ERROR: ..." above means .apk package 7zip is not yet present in your local repository.

2b. make packages' download list
localhost:/media/sda1/apks2/v3.22# sh fetch-apk.sh main mklist
>>> set branch: main
>>> Process INSTALL
>>> creating main.lst
adding + 1 7zip-24.09-r0
... list created, run fetch cmd
2c. fetch packages from download list
localhost:/media/sda1/apks2/v3.22# sh fetch-apk.sh main fetch
>>> set branch: main
>>> fetching: https://cdn.alpinelinux.org/alpine/v3.22/main/x86_64/7zip-24.09-r0.apk
--2025-11-19 09:54:34--  https://cdn.alpinelinux.org/alpine/v3.22/main/x86_64/7zip-24.09-r0.apk
Resolving cdn.alpinelinux.org (cdn.alpinelinux.org)... 199.232.22.132, 2a04:4e42:42::644
Connecting to cdn.alpinelinux.org (cdn.alpinelinux.org)|199.232.22.132|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 915773 (894K) [application/octet-stream]
Saving to: '7zip-24.09-r0.apk'

7zip-24.09-r0.apk      100%[==================================>] 894.31K   375KB/s    in 2.4s    

2025-11-19 09:54:37 (375 KB/s) - '7zip-24.09-r0.apk' saved [915773/915773]
2d. move fetched packages into branch/arch folder
localhost:/media/sda1/apks2/v3.22# mv *.apk main/x86_64/
NOTE:
  • Moving is done manually, so as to give a second thought, whether to keep those pkgs in your repo.
2e. run apk fix
localhost:/media/sda1/apks2/v3.22# apk fix
(1/1) Installing 7zip (24.09-r0)
Executing busybox-1.37.0-r18.trigger
OK: 1837 MiB in 849 packages
NOTE:
  • apk fix, would now install the packages.
  • Steps 2a -> 2e can be repeated for main/,community/ branches.
  • If added package/s has dependencies in both main/+community/, then repeat steps 2b -> 2e.
  • Remember to change branch name where needed by script, eg.
    • sh fetch-apk.sh [main|community] [mklist|fetch]
    • mv *.apk [main|community]/x86_64/

3a. run lbu commit
localhost:/media/sda1/apks2/v3.22# lbu commit
NOTE:
  • Run lbu commit if wanting to re-install it on next reboot.
  • Run apk del 7zip if wanting only to keep packages available in your local repository mirror.
Caveat: Known Issues and solutions,
  • Try finishing your needed packages installs fast before new updates happen, any new updates will change APKINDEX.tar.gz file.
  • Due to delay, if package/version you are trying to install is unavailable on official CDN, just re-do getindex till everything seems ok. lbu commit and REBOOT!
  • On next reboot, you may have to re-fetch some more missing updated packages.

4a. downloads
While old git repository is in search of new host, here is temporary/alt one.
/cache v/s apks2
/cache/apks2
/cache files downloads are controlled by apk and should not be manually updated/changed/apks2 files downloads are user controlled and can be manually updated/changed
Its difficult to create a snapshot of /cacheCreating packages snapshot is easy
apk update will download and update to newer APKINDEX.tar.gz fileAPKINDEX.tar.gz file can only be manually dowloaded
Creating/maintaining multiple /cache snapshot is not recommendedCreating/maintaining multiple /apks2 snapshot is doable(advanced)
When to update/upgrade
Reason for update/upgradeYes/No
Is a critical bug?
Simple feature bug fix update?
Unneeded feature update?
Lots of internet/media hype?
Is your setup working as expected?

Q&A

How to do full upgrade?

Just create a new master boot-disk using new/updated ISO, keep the old one if possible.

  • Full upgrade also requires you to rebuild your partial repository(apks2) from scratch.

Is it secure?

It does not take care of security aspects related to outdated packages, unless repository is updated regularly.

  • To update with latest security fixes, do an upgrade to master disk that has shared repository.
  • Reboot to upgrade other devices.
  • Caveat: Kernel does not get upgraded yet.

What the heck, this personal repository thing is freaking me out.

It was chaotic for me too, but once I got into the regular upgrade maintenance mode its kinda cool.

  • Get in practice of knowing your packages while upgrading repo, this will help if some critical upgrades are available.
  • Doing regular upgrade at reasonable period is also ok.
  • If system is not connected to internet upgrade period can be prolonged, as it is likely immune of any security related critical bugs.

Is this method officially supported?

Currently No. Having a partial repository also means it may contain packages/versions that are no longer provided by official repositories. Seeking help on such packages may not be possible.

  • Caveat: maintaining your own partial-repository is an extra work and involves risks. Be careful when adopting this process. It may give perception of being locked to that snapshot of your repository.

Is it possible to have multiple snapshots for repository?

Short answer yes. Having multiple snapshots means more maintenance work and Alpine Linux' know-how. See (Part 5).

Use cases

  • Multiple setups for, eg. PHP7, PHP8.x.y, PHP8.x.z
  • Bug reporting and reproducing at another developers' station

Author

V.Krishn

Resources

  1. Diskless ram-based install
  2. APKINDEX spec
  3. Alpine Linux apk download scripts with some curated pkgs lists


Edit - History - Print - Recent Changes - Search
Page last modified on November 22, 2025, at 06:45 AM