vanilla-os/apx

Apx is the Vanilla OS package manager. It’s meant to be simple to use, but also powerful with support to installing packages from multiple sources without altering the root filesystem.

Apx

Apx (/à·peks/) is the default package manager in Vanilla OS. It is a wrapper around multiple package managers to install packages and run commands inside a managed container.

Special thanks to distrobox for making this possible.

Help

Apx is a package manager with support for multiple sources, allowing you to install packages in subsystems.

Usage:
  apx [command]

Available Commands:
  [subsystem] Work with the specified subsystem, accessing the package manager and environment.
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  pkgmanagers Work with the package managers that are available in apx.
  stacks      Work with the stacks that are available in apx.
  subsystems  Work with the subsystems that are available in apx.

Flags:
  -h, --help      help for apx
  -v, --version   version for apx

Use "apx [command] --help" for more information about a command.

Documentation and Guides

Documentation

The official documentation and manpage for apx are available at https://docs.vanillaos.org/docs/en/apx.

Dependencies

To add new dependencies, use go get as usual, then run go mod tidy and go mod vendor before committing the code.

Translations

Contribute translations for the manpage and help page in Weblate.

Generating man pages for translations

Once the translation is complete in Weblate and the changes committed, clone the repository using git and perform go build, create a directory using the mkdir man/<language_code> && mkdir man/<language_code>/man1 command, and execute this command LANG=<language_code> ./apx man > man/<language_code>/man1/apx.1. Open a PR for the generated manpage here.

Instructions for using Apx in other distributions

Apx has been designed as a distro-agnostic tool, allowing it to work with any distribution.

Prerequisites

• You must have go installed from your distribution's native repositories to compile apx.
• You must have git installed to clone the repository.
• You must have either podman (suggested) or docker installed.
• You must have make installed for the installation.

Procedure

Clone apx's repository using git and enter it using cd:-

git clone --recursive https://github.com/Vanilla-OS/apx.git
cd apx

Build apx using make:-

make build

Install apx using make:-

sudo make install

Install the apx manpages using make:-

sudo make install-manpages

Uninstall apx using make:-

make uninstall

Uninstall apx man pages using make:-

make uninstall-manpages

Installing apx in a custom destination

The prefix or installation destination can be changed using PREFIX and DESTDIR.

To install apx into ~/.local for example:-

make install PREFIX=$HOME/.local
make install-manpages PREFIX=$HOME/.local

Or into a separate root:-

make install DESTDIR=$HOME/altroot
make install-manpages DESTDIR=$HOME/altroot

Community Packages

Apx is packaged in various sources by our community, if you aren't comfortable with building apx manually you can install a package listed below.

(Note: These packages are unofficial if there are any issues with packaging report them to the respective maintainers, if there are any issues with apx functionalities report them here.)

apx's Issues

Atomic installations using overlays

Since Almost supports overlays via overlayfs and those are already being used for Atomic updates, might be a good idea to use the same feature to perform a kind of atomic installation, by applying the transaction only if succeed.

recent config change will cause panic without some migration code

the change that was merged Jan 2 had a large change in the config file struct. If apx is released with that new change, it will panic on startup when it tries to parse the old config file and fails.

Need to write a config migration & checks.

Upgrade apx to use vanilla-os/orchid

Sideload flag doesn't create an icon/desktop entry automatically

auto generate man page

Cobra will auto-generate man pages.
Investigate doing this cleanly during the build process.

Attempting to use almost any apx command as root results in a panic

Preface: It is my understanding that apx is not meant to be run as a root user. Though I would say its preferable to display a tip/warning or guide the user to relevant documentation instead of panicking.

Affected CLI commands:

- autoremove
- clean
- export
- init
- install
- list
- purge
- run
- remove
- search
- show
- unexport
- update
- upgrade
- version

I.e. all except help (prints help message as expected) and enter (cannot find the associated managed container).

Example:

user@vanilla:~$ sudo apx --dnf update
⣾ Creating container...⌬ Apx :: exit status 1
panic: exit status 1

goroutine 1 [running]:
log.Panic({0xc00014bba0?, 0x16?, 0xc00014bbb0?})
	log/log.go:388 +0x65
github.com/vanilla-os/apx/core.CreateContainer({0x880ff3, 0x3})
	github.com/vanilla-os/apx/core/container.go:188 +0x35b
github.com/vanilla-os/apx/core.RunContainer({0x880ff3, 0x3}, {0xc00015c9c0, 0x4, 0x0?})
	github.com/vanilla-os/apx/core/container.go:108 +0x7e
github.com/vanilla-os/apx/cmd.update(0xc0001ac280?, {0xc000111a20, 0x0, 0x1?})
	github.com/vanilla-os/apx/cmd/update.go:63 +0x2ee
github.com/spf13/cobra.(*Command).execute(0xc0001ac280, {0xc000111a10, 0x1, 0x1})
	github.com/spf13/cobra/command.go:872 +0x694
github.com/spf13/cobra.(*Command).ExecuteC(0xc00012bb80)
	github.com/spf13/cobra/command.go:990 +0x3bd
github.com/spf13/cobra.(*Command).Execute(...)
	github.com/spf13/cobra/command.go:918
main.main()
	github.com/vanilla-os/apx/main.go:87 +0x672

Better integration with system

Is there any way of getting apx more integrated with system? Containerized spotify-edge from aur can't open login buttons using any browser from any other container or flatpak, only using installed from aur container. And browser installed from any container can't be chosen as default in gnome settings app.

Remove --sys flag and replace it with abroot

Please create a normal documentation, how to build "apx" in other distros

Do not require package manager flag to work with named containers

Currently, I have to write apx enter --dnf --name a_name to access a named container. Considering that --name option appends custom name to apx_managed_dnf, it could infer what package manager to use with the container, so that I can skip --dnf

Podman/Docker check in Apx differs from Distrobox

Distrobox prioritize docker on its check for a manager, while Apx prioritize podman. In Apx we use the manager direclty to list and remove containers, so if docker is installed in the system, distrobox will use it to make new containers but since Apx prioritize podman, if this is also found in the system it will not found the existing containers.

nix: add --unfree flag

add an --unfree flag to allow nixpkgs to install unfree packages.

I appreciate the support to get zerotier working.

At boot time, I get this error message.

`jcastillo@apx_managed:~$ sudo zerotier-one
zerotier-one: fatal error: cannot bind to local control interface port 9993

[Feature] a way to delete containers

I think the vanilla control center could have a button "delete container" on the same side as "enter the shell" button

Bug: Broken images from DockerHub makes Apx containers unusable

the APX package does not work =(
Clean system, just installed

doc@vanilla:~$ apx init
⣾ Creating container...⌬ Apx :: error creating container: exit status 125

Add "--all" flag for update and upgrade

• Add labels on the containers for their package manager and name (solve #57)
• Query all containers labels for easier updates across all of them (help topgrade-rs/topgrade#306)

EDIT: The command distrobox upgrade --all could help for most cases, but it does not support yay (89luca89/distrobox#569)

Support for multiple users

We could add the user ID on the container name. When the user invokes any apx command, then apx will connect to the container that is owned by that user.

I am not aware of any Docker way to have different containers for each user. It may be possible with Podman, as it is daemon-less.

User ID was chosen over the username, as the username could change, but the ID should always remain the same.

Another option, would be to add more users to the existing containers, but having different containers for each user provides better isolation. Also, the initial user is created by Docker itself inside distrobox, and I don't know whether it's a good idea to override Docker's/Podman's behavior.

Add dnf, aur commands to README

Properly tag releases in git

I see apx is supposed to have the version 1.3.4 according to e94504e, but this isn't reflected in neither git nor Github, since the version (or any other) hasn't been properly tagged. Please do so so it can be packaged properly in a multitude of distributions and it's easier to track which version is which point in history.

bind pflags with viper for env variable usage

see https://github.com/spf13/viper#working-with-flags for specifics.

This would allow apx to recognize environment variables like APX_NAME to set the --name flag. Super powerful when combined with direnv

.envrc:
export APX_NAME=mycontainer
apx enter

Improve desktop entries labels

..to avoid showing (on apx_apt_managed).

Installing with the --sys flag doesn't reenable immutability in vanilla os after the installation process completes

When installing to the system directly, apx doesn't reenable immutability after it's done modifying the file system. This is on the unstable.20221106 iso.

Here is the terminal output:

adam@vanilla:~$ sudo almost check
[sudo] password for adam: 
Mode: ro
System is read-only
adam@vanilla:~$ apx install --sys pcmanfm
Apx :: Performing operations on the host system.
Reading package lists... Done
Building dependency tree... Done
...
adam@vanilla:~$ sudo almost check
Mode: rw
System is read-write

apps installed with apx can't reach bluetooth?

Hi there.
I installed blueman with apt (via apx) so I can connect my headphones to my computer.
when I opened the app it gave me an error with the text: Bluez daemon is not running.
Now the problem is apparently that apps like blueman cant reach the bluetooth card (I think).

When I try bluetoothctl in an apx container it says:

Waiting to connect to bluetoothd...dbus[3940]: arguments to dbus_connection_get_object_path_data() were incorrect, assertion "connection != NULL" failed in file ../../../dbus/dbus-connection.c line 5921.
This is normally a bug in some application using the D-Bus library.

D-Bus not built with -rdynamic so unable to print a backtrace

Is this an bug / problem or am I doing something wrong?
Thanks for you're time and hard work!

document go.mod vendor changes

add documentation about go.mod vendoring changes that were recently merged.

Installed applications with full identifier names in their .desktop filenames don't properly remove the .desktop file on uninstall

KDE's KWrite for example has it's .desktop file named as org.kde.kwrite.desktop. apx successfully exports it outside of the container as apx_managed_apk-org.kde.kwrite.desktop (_apk comes from #31) but then can't remove it as it looks for apx_managed_apk-kwrite.desktop rather than the proper name. So now the .desktop file is left lingering.

[Question] Hardcoded distrobox paths

Regarding my PR #55, I wanted to ask whether it is really required to provide the full path of distrobox.

I found some pieces of code where the binaries are searched in the PATH. For example:

apx/core/container.go

Line 312 in 44b5c84

c.Run("sh", "-c", "distrobox-export --app "+program+" 2>/dev/null || true")

apx/core/container.go

Line 317 in 44b5c84

out, err := c.Output("sh", "-c", "distrobox-host-exec $(getent passwd $USER | cut -f 7 -d :) -l -i -c printenv | grep -E ^PATH=")

apx/core/container.go

Line 383 in 44b5c84

c.Run("sh", "-c", "distrobox-export --bin "+string(bin_path)+" --export-path ~/.local/bin >/dev/null 2>/dev/null || true")

default storage config for distrobox/podman on first setup

on apx first run, check to see if /home is on btrfs, if so, write a storage configuration file to set btrfs backend for podman.

Autocomplete for apx install

Kernel update error on sudo vso trigger-update --now

Hello everybody!
I've been trying to update my system, but the following happens:

Setting up vanilla-base-desktop (1.0.0) ...
Processing triggers for linux-image-5.19.0-28-generic (5.19.0-28.29) ...
/etc/kernel/postinst.d/dkms:

• dkms: running auto installation service for kernel 5.19.0-28-generic
  Sign command: /usr/bin/kmodsign
  Signing key: /var/lib/shim-signed/mok/MOK.priv
  Public certificate (MOK): /var/lib/shim-signed/mok/MOK.der
  ACPI disabled in this kernel, not building module.
  Error! The /var/lib/dkms/acpi-call/1.2.2/5.19.0-28-generic/x86_64/dkms.conf for module acpi-call includes a BUILD_EXCLUSIVE directive which does not match this kernel/arch/config.
  This indicates that it should not be built.
  Sign command: /usr/bin/kmodsign
  Signing key: /var/lib/shim-signed/mok/MOK.priv
  Public certificate (MOK): /var/lib/shim-signed/mok/MOK.der
  Error! Your kernel headers for kernel 5.19.0-28-generic cannot be found at /lib/modules/5.19.0-28-generic/build or /lib/modules/5.19.0-28-generic/source.
  Please install the linux-headers-5.19.0-28-generic package or use the --kernelsourcedir option to tell DKMS where it's located.
  Sign command: /usr/bin/kmodsign
  Signing key: /var/lib/shim-signed/mok/MOK.priv
  Public certificate (MOK): /var/lib/shim-signed/mok/MOK.der
  Error! Your kernel headers for kernel 5.19.0-28-generic cannot be found at /lib/modules/5.19.0-28-generic/build or /lib/modules/5.19.0-28-generic/source.
  Please install the linux-headers-5.19.0-28-generic package or use the --kernelsourcedir option to tell DKMS where it's located.
  ...done.
  /etc/kernel/postinst.d/initramfs-tools:
  update-initramfs: Generating /boot/initrd.img-5.19.0-28-generic
  /etc/kernel/postinst.d/zz-update-grub:
  /usr/sbin/grub-probe: error: failed to get canonical path of `overlay'.
  run-parts: /etc/kernel/postinst.d/zz-update-grub exited with return code 1
  dpkg: error processing package linux-image-5.19.0-28-generic (--configure):
  installed linux-image-5.19.0-28-generic package post-installation script subprocess returned error exit status 1
  Errors were encountered while processing:
  grub-pc
  linux-image-5.19.0-28-generic
  E: Sub-process /usr/bin/dpkg returned an error code (1)
  Error: exit status 100
  Description:
  Execute a command in a transactional shell in the future root partition and switch to it on the next boot.

My VanillaOS was installed during beta periodo and since than I have done some updates without problem.
If I could provide more information, please, let me know

Thanks

How to run it behind the proxy?Any solution please

connect failed

I want to modify the CheckConnection URL in the configuration file，I can't access google.com

Colors/shell escape codes aren't properly handled

apx errors look like this:

I assume this shouldn't be the case and instead print the error message with colors.
This happens on fish and bash.
System is crystal linux (arch), with latest apx cloned on 15/09

No icon in the exported .desktop file for Telegram Desktop

I've installed Telegram Desktop in a container, and I get the menu entry, but without the icon. Tried Ubuntu and Fedora containers, the issue is on both (and Ubuntu has way older Telegram version). apx export didn't help.

A Guide for porting this to another ubuntu distribution

I'm trying to port this over to my own ubuntu distro, but I'm having many issues a guide would come in clutch!

User-selected graph driver error

When using apx install x or apx run x, I get the following error:
ERRO[0000] User-selected graph driver "overlay" overwritten by graph driver "vfs" from database - delete libpod local files to resolve

APX checks for desktop entry after removing application

After removing an application with a desktop entry with APX, it will notify you that it can't find a desktop entry right after removing the application.

Command `update` and `upgrade` without flag

Make apx automatically update and upgrade all the containers just by typing command, instead of forcing to type it for every container separately.

Export binaries

Since apx uses Distrobox in the background to manage containers, which supports exporting binaries from the container to the host, it would be a nice feature to integrate into apx. It feels a bit clunky to alway type 'apx run' before the actual command and having a way to directly run the program from the host cli would make apx feel more tightly integrated.

Move "old" folder to new repository

Pls make a new archive repository for the "old" folder.

packages from AUR not install by default

I solved it but I think it could be improved

with apx --aur install (package) with packages from the arch linux official repository install normally

but packages that belong to the AUR repository, need some additional packages even though yay is already installed by default:

git
fakeroot
binutils

the official documentation about AUR recommend install base-devel but these 3 were enough every time I needed it

would it be possible to install these 3 packages or base-devel automatically as soon as the container is created? I think it would improve usability if it is possible to do

"Error: exit status 1" when exporting a binary

apx version 1.4.1-2

Repro steps:

1. Create fresh aur container (apx init --aur)
2. Install the necessary packages to be able to build packages inside the aur container (sudo pacman -S --needed git base-devel)
3. Install gotop from the aur (apx install --aur gotop)
4. Try to export gotop (apx export --aur --bin gotop)

Expected Result:
I can either run gotop using a desktop shortcut or via terminal (apx run gotop)

Actual Result:
The following is printed in console and neither shortcuts are available to gotop: "Error: exit status 1"

Sideload deletes the package, even if installation was canceled

When using apx install --sideload, the package file is deleted, even if the installation is canceled or fails for some reason. This is undocumented, unexpected, and destructive.

It appears that this is due to this line, which moves the file to a temp directory:

apx/cmd/install.go

Line 53 in 3281428

path, err := core.MoveToUserTemp(args[0])

However, the file is never moved back, regardless of the success or failure of the operation. Perhaps it would be a better idea to copy the file there instead?

apx version command

apx has a root level -v flag to show version, but the man page and help say there is an apx version command. It doesn't exist. We should either add it, or remove the version subcommand from the help/man page.

Install the NVIDIA driver inside container if it is installed on the host

By default when running Vanilla OS and installing the NVIDIA driver then installing a container the container doesn't include the NVIDIA driver needed for GPU acceleration

This can be easily fixed by checking the driver version in Vanilla control center then installing it manually with apx install nvidia-driver525 for example, but this is quite annoying to do and will likely break when you update the driver this should be handled automatically ideally by

1. Checking if the Nvidia driver is installed
2. Running Nvidia smi or some similar Go function to get driver version
3. Install the driver

And on installing new Nvidia driver

1. Check the driver version
2. Compare with version in container
3. Install new version if needed in all containers

It might be convenient to perhaps make a repository to install the correct NVIDIA driver for each distro apx supports e.g. Fedora, Arch since the newest version might be different on all of them because of different release cycles

apk Alpine gonna be supported in futur ?

Alpine is very great, their package is update regularly, stable, installation is blazing fasssssttt compare to Ubuntu / other 😄

If you want to try how alpine is fast compare with ffmpeg

Alpine :

docker run -it --rm alpine

apk update && apk add ffmpeg

Ubuntu :

docker run -it --rm Ubuntu

apt update && apt install ffmpeg -y

Ubuntu package is old for almost all things, alpine have frequently updated version of packages. Ffmpeg is old on Ubuntu more than 2 years almost.

Sorry for my English 😅

Minimise and maximise button

Could you add the minimise and maximise button by default ? It's very annoying to install gnome tweaks and do it manually.

Explain why container features are disabled in VM

`apx run` does not pass arguments

Summary

When invoking commands using apx run, it should be possible to pass command line arguments to the command being invoked inside the container, analogous to podman run.

Expected Behavior

When invoking a command using apx run, any command line arguments given after the command name should be passed along to the command being run, and not interpreted by apx.

Similar to docker/podman, flags belonging to apx should be passed after the run command but before the program name. Everything after the program name should be passed to the container verbatim.

Actual Behavior

Command line arguments are being interpreted by apx instead.

For instance, apx run ls -l shows the following error message:

Error: unknown shorthand flag: 'l' in -l
Usage:
  apx run <program> [flags]

Examples:
apx run htop

Flags:
  -h, --help   help for run

Global Flags:
      --apk           Install packages from the Alpine repository.
      --apt           Install packages from the Ubuntu repository.
      --aur           Install packages from the AUR (Arch User Repository).
      --dnf           Install packages from the Fedora's DNF (Dandified YUM) repository.
  -n, --name string   Create or use custom container with this name.

Specifications

• Version: apx version 1.4.2
• Platform: VanillaOS 22.10
• Kernel: Linux 5.19.0-29-generic

Changing system timezone breaks container

I changed the system timezone on my fresh VanillaOS install and was no longer able to enter the default container, being met with the following message.

Error: OCI runtime error: unable to start container "8a99d8ffdf38fba65f173f069bc0adb567edac94037f0525dfaecc3b6176ce8f": mount /etc/localtime to /etc/localtime: Not a directory

Replace vm check in Apx with live check