From 34c89ade540c44ca64c16c6c66268f93a135cb81 Mon Sep 17 00:00:00 2001 From: Jarred Wilson Date: Wed, 16 Oct 2024 13:20:16 +0000 Subject: [PATCH] feat: add apx documentation --- docs/articles/en/working-w-pkgms.md | 340 +++++++++++++++++++++++ docs/articles/en/working-w-stacks.md | 222 +++++++++++++++ docs/articles/en/working-w-subsystems.md | 168 +++++++++++ 3 files changed, 730 insertions(+) create mode 100644 docs/articles/en/working-w-pkgms.md create mode 100644 docs/articles/en/working-w-stacks.md create mode 100644 docs/articles/en/working-w-subsystems.md diff --git a/docs/articles/en/working-w-pkgms.md b/docs/articles/en/working-w-pkgms.md new file mode 100644 index 00000000..4d570f5e --- /dev/null +++ b/docs/articles/en/working-w-pkgms.md @@ -0,0 +1,340 @@ +## Working with Package Managers +Package managers can be manipulated in various ways with `apx`. This includes creation, editing, deleting, importing configurations, and exporting configurations. +```bash +apx pkgmanagers --help +``` + +``` +Work with the package managers that are available in apx. + +Usage: + apx pkgmanagers [command] + +Available Commands: + export Export the specified package manager. + import Import the specified package manager. + list List all available package managers. + new Create a new package manager. + rm Remove the specified package manager. + show Show information about the specified package manager. + update Update the specified package manager. + +Flags: + -h, --help help for pkgmanagers + +Use "apx pkgmanagers [command] --help" for more information about a command. +``` + +## Creating a Package Manager +APX ships with several package managers out-of-the-box. These cover a wide range of different Linux distributions. In the event that you need to add a package manager for a new operating system, this can be done using the `apx` CLI. Here are the available options for adding a package manager: + +```bash +apx pkgmanagers new --help +``` +``` +Create a new package manager. + +Usage: + apx pkgmanagers new [flags] + +Flags: + -a, --autoremove string The command to run to autoremove packages. + -c, --clean string The command to run to clean the package manager's cache. + -h, --help help for new + -i, --install string The command to run to install packages. + -l, --list string The command to run to list installed packages. + -n, --name string The name of the package manager. + -S, --need-sudo Whether the package manager needs sudo to run. + -y, --no-prompt Assume defaults to all prompts. + -p, --purge string The command to run to purge packages. + -r, --remove string The command to run to remove packages. + -s, --search string The command to run to search for packages. + -w, --show string The command to run to show information about packages. + -u, --update string The command to run to update the list of available packages. + -U, --upgrade string The command to run to upgrade packages. +```bash +apx pkgmanagers list +``` +``` + INFO Found 5 package managers +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ NAME ┊ BUILT-IN ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ apk ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ apt ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ dnf ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ pacman ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ zypper ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +``` +Looking at the list, we see that `yum` is not preconfigured for us. This means that we need to add a package manager to `apx` and give it all the required parameters. + +```bash +apx pkgmanagers new +``` +> **NOTE:** These options can be passed as CLI args as shown above in the help output. +``` + INFO Choose a name: +yum + INFO Does the package manager need sudo to run? [y/N] +y + INFO Enter the command for 'list': +yum list + INFO Enter the command for 'show': +yum info + INFO Enter the command for 'autoRemove': +yum autoremove + INFO Enter the command for 'clean': +yum clean + INFO Enter the command for 'remove': +yum remove + INFO Enter the command for 'search': +yum search + INFO Enter the command for 'update': +yum upgrade --refresh + INFO Enter the command for 'upgrade': +yum upgrade + INFO Enter the command for 'install': +yum install + INFO Enter the command for 'purge': +yum remove + SUCCESS Package manager yum created successfully. +``` + +Now we should be able to see the new yum package manager in the list of available managers. +```bash +apx pkgmanagers list +``` +``` + INFO Found 6 package managers +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ NAME ┊ BUILT-IN ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ yum ┊ no ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ apk ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ apt ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ dnf ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ pacman ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +┊ zypper ┊ yes ┊ +┼┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼ +``` +> **NOTE:** The new `yum` package manager is user-defined and therefore not considered a "built-in". + + +## Updating a Package Manager +Updates to package managers can be done similarly to other operations in `apx`. +```bash +apx pkgmanagers update --help +``` +``` +Update the specified package manager. + +Usage: + apx pkgmanagers update [flags] + +Flags: + -a, --autoremove string The command to run to autoremove packages. + -c, --clean string The command to run to clean the package manager's cache. + -h, --help help for update + -i, --install string The command to run to install packages. + -l, --list string The command to run to list installed packages. + -n, --name string The name of the package manager. + -S, --need-sudo Whether the package manager needs sudo to run. + -y, --no-prompt Assume defaults to all prompts. + -p, --purge string The command to run to purge packages. + -r, --remove string The command to run to remove packages. + -s, --search string The command to run to search for packages. + -w, --show string The command to run to show information about packages. + -u, --update string The command to run to update the list of available packages. + -U, --upgrade string The command to run to upgrade packages. +``` + +Now let's update the autoremove command to add verbosity. This requires adding the `-v` argument to the command. + +```bash +apx pkgmanagers update -n yum -S +``` +> **NOTE:** Currently, sudo access with `-S` needs to be used every time an update occurs to maintain it. Leaving off the `-S` will remove sudo access from the command. +``` + INFO Enter new command for 'autoRemove' (leave empty to keep 'yum autoremove'): +yum autoremove -v + INFO Enter new command for 'clean' (leave empty to keep 'yum clean'): + + INFO Enter new command for 'install' (leave empty to keep 'yum'): + + INFO Enter new command for 'list' (leave empty to keep 'nstall'): + + INFO Enter new command for 'purge' (leave empty to keep 'v'): + + INFO Enter new command for 'remove' (leave empty to keep 'yum remove'): + + INFO Enter new command for 'search' (leave empty to keep 'yum search'): + + INFO Enter new command for 'show' (leave empty to keep 'yum info'): + + INFO Enter new command for 'update' (leave empty to keep 'yum upgrade --refresh'): + + INFO Enter new command for 'upgrade' (leave empty to keep 'yum upgrade'): + + INFO Updated package manager 'yum'. +``` + +```bash +apx pkgmanagers show yum +``` +``` +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Name ┊ yum ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ NeedSudo ┊ true ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ AutoRemove ┊ yum autoremove -v ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Clean ┊ yum clean ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Install ┊ yum install ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ List ┊ yum list ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Purge ┊ yum remove ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Remove ┊ yum remove ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Search ┊ yum search ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Show ┊ yum info ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Update ┊ yum upgrade --refresh ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Upgrade ┊ yum upgrade ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +``` + +## Exporting a Package Manager +`apx` can export a package manager to a yaml file to be imported later. +```bash +apx pkgmanagers export --help +``` +``` +Export the specified package manager. + +Usage: + apx pkgmanagers export [flags] + +Flags: + -h, --help help for export + -n, --name string The name of the package manager to export. + -o, --output string The path to export the stack to. +``` +Now let's say we are wanting to back up our package manager configuration for usage with some automation tooling. We just need to specify the name of the package manager and a location to export the yaml file. +```bash +apx pkgmanagers export -n yum -o . +cat yum.yml +``` +``` +model: 2 +name: yum +needsudo: true +cmdautoremove: yum remove +cmdclean: yum clean +cmdinstall: yum install +cmdlist: yum list +cmdpurge: yum remove +cmdremove: yum remove +cmdsearch: yum search +cmdshow: yum show +cmdupdate: yum upgrade +cmdupgrade: yum upgrade +builtin: false +``` +The package manager has been successfully exported! + +## Importing a Package Manager +Package managers can be imported easily with `apx`. +```bash +apx pkgmanagers import --help +``` +``` +Import the specified package manager. + +Usage: + apx pkgmanagers import [flags] + +Flags: + -h, --help help for import + -i, --input string The path to import the package manager from. +``` +For this example, we are going to import the yaml file that we exported in the previous section. +```bash +apx pkgmanagers import -i yum.yml +``` +``` + INFO Imported package manager from 'yum'. +``` +```bash +apx pkgmanagers show yum +``` +``` +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Name ┊ yum ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ NeedSudo ┊ true ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ AutoRemove ┊ yum remove ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Clean ┊ yum clean ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Install ┊ yum install ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ List ┊ yum list ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Purge ┊ yum remove ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Remove ┊ yum remove ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Search ┊ yum search ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Show ┊ yum show ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Update ┊ yum upgrade ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Upgrade ┊ yum upgrade ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +``` +The package manager has been successfully imported! + + +## Deleting a Package Manager +```bash +apx pkgmanagers rm --help +``` +``` +Remove the specified package manager. + +Usage: + apx pkgmanagers rm [flags] + +Flags: + -f, --force Force removal of the package manager. + -h, --help help for rm + -n, --name string The name of the package manager to remove. +``` +Since we are not using the `yum` package manager, we want to delete it. This can be done by passing the name of the package manager to the `rm` command. +```bash +apx pkgmanagers rm -n yum +``` +``` + INFO Are you sure you want to remove 'yum'? [y/N] +y + INFO Removed package manager 'yum'. +``` +And with that we no longer have the yum package manager! diff --git a/docs/articles/en/working-w-stacks.md b/docs/articles/en/working-w-stacks.md new file mode 100644 index 00000000..6c3e4224 --- /dev/null +++ b/docs/articles/en/working-w-stacks.md @@ -0,0 +1,222 @@ +## Working with Stacks +```bash +apx stacks --help +``` +``` +Work with the stacks that are available in apx. + +Usage: + apx stacks [command] + +Available Commands: + export Export the specified stack. + import Import the specified stack. + list List all available stacks. + new Create a new stack. + rm Remove the specified stack. + show Show information about the specified stack. + update Update the specified stack. + +Flags: + -h, --help help for stacks + +Use "apx stacks [command] --help" for more information about a command. +``` + +## Creating a Stack +Stacks in APX are preconfigured operating system images that are reusable across subsystems. Several are shipped already, but user-defined stacks are supported as well. Here are the available options for adding a stack: +```bash +apx stacks new --help +``` +``` +Create a new stack. + +Usage: + apx stacks new [flags] + +Flags: + -b, --base string The base distribution image to use. (For a list of compatible images view: https://distrobox.it/compatibility/#containers-distros) + -h, --help help for new + -n, --name string The name of the stack. + -y, --no-prompt Assume defaults to all prompts. + -p, --packages string The packages to install. + -k, --pkg-manager string The package manager to use. +``` +> **NOTE:** Depending on the stack that needs to be added, it may be necessary to create a package manager first. + +We want to use the latest Ubuntu LTS which at the time of writing is 24.04 (Noble Numbat) in a subsystem. Let's begin by listing off the currently available stacks. +```bash +apx stacks list +``` +``` + INFO Found 7 stacks: +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ NAME ┊ BASE ┊ BUILT-IN ┊ PKGS ┊ PKG MANAGER ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ alpine ┊ alpine:latest ┊ yes ┊ 0 ┊ apk ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ arch ┊ ghcr.io/archlinux/archlinux:multilib-devel ┊ yes ┊ 0 ┊ pacman ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ fedora ┊ fedora:latest ┊ yes ┊ 0 ┊ dnf ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ opensuse ┊ registry.opensuse.org/opensuse/tumbleweed:latest ┊ yes ┊ 0 ┊ zypper ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ ubuntu ┊ ubuntu:latest ┊ yes ┊ 0 ┊ apt ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ vanilla-dev ┊ ghcr.io/vanilla-os/dev:main ┊ yes ┊ 0 ┊ apt ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ vanilla ┊ ghcr.io/vanilla-os/pico:main ┊ yes ┊ 0 ┊ apt ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +``` +Looking at the above output we see that there is no stack for Ubuntu 24.04. This means that we need to create one! To do this, we tell `apx` to create a new stack and pass it some info. +```bash +apx stacks new +``` +> **NOTE:** These options can be passed as CLI args as shown above in the help output. +``` + INFO Choose a name: +noble + INFO Choose a base (e.g. 'vanillaos/pico'): +ubuntu:noble + INFO Choose a package manager: +1. yum +2. apk +3. apt +4. dnf +5. pacman +6. zypper + INFO Select a package manager [1-6]: +3 + INFO You have not provided any packages to install in the stack. Do you want to add some now?[y/N] +y + INFO Please type the packages you want to install in the stack, separated by a space: +neofetch vim + SUCCESS Created stack 'noble'. + ``` +We have received a "SUCCESS" message from `apx`! To confirm that the new `noble` stack has been created, just list off the available stacks. + ```bash + apx stacks list + ``` + ``` + INFO Found 8 stacks: +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ NAME ┊ BASE ┊ BUILT-IN ┊ PKGS ┊ PKG MANAGER ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ noble ┊ ubuntu:noble ┊ no ┊ 2 ┊ apt ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ alpine ┊ alpine:latest ┊ yes ┊ 0 ┊ apk ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ arch ┊ ghcr.io/archlinux/archlinux:multilib-devel ┊ yes ┊ 0 ┊ pacman ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ fedora ┊ fedora:latest ┊ yes ┊ 0 ┊ dnf ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ opensuse ┊ registry.opensuse.org/opensuse/tumbleweed:latest ┊ yes ┊ 0 ┊ zypper ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ ubuntu ┊ ubuntu:latest ┊ yes ┊ 0 ┊ apt ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ vanilla-dev ┊ ghcr.io/vanilla-os/dev:main ┊ yes ┊ 0 ┊ apt ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ vanilla ┊ ghcr.io/vanilla-os/pico:main ┊ yes ┊ 0 ┊ apt ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +``` +> **NOTE:** The new `noble` stack is user-defined and therefore not considered a "built-in". + +## Updating Stacks +Sometimes you will want to update a stack. This could be to change the container image to a new tag or updating a list of packages to be installed. `apx` supports doing those things and more. +```bash +apx stacks update --help +``` +``` +Update the specified stack. + +Usage: + apx stacks update [flags] + +Flags: + -b, --base string The base subsystem to use. + -h, --help help for update + -n, --name string The name of the stack. + -y, --no-prompt Assume defaults to all prompts. + -p, --packages string The packages to install. + -k, --pkg-manager string The package manager to use. +``` +In this example, we are going to update the list of installed packages to include `git`. +```bash +apx stacks update noble +``` +``` + INFO Type a new base or confirm the current one (ubuntu:noble): + + INFO Choose a new package manager or confirm the current one (apt): + + INFO You have not provided any packages to install in the stack. Do you want to add some now?[y/N] +y + INFO Type the packages you want to install in the stack, separated by a space: +neofetch vim git + INFO Updated stack 'noble'. +``` + +Let's check the stack to see if the packages were updated correct. +```bash +apx stacks show noble +``` +``` +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Name ┊ noble ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Base ┊ ubuntu:noble ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Packages ┊ neofetch, vim, git ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +┊ Package manager ┊ apt ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +``` + +## Exporting Stacks +```bash +apx stacks export -n noble -o . +cat noble.yml +``` +``` +name: noble +base: ubuntu:noble +packages: +- git +- neofetch +- vim +pkgmanager: apt +builtin: false +``` + +## Importing Stacks +```bash +apx stacks import -i noble.yml +``` +``` + INFO Imported stack from 'noble'. +``` + +## Deleting Stacks +```bash +apx stacks rm --help +``` +``` +Remove the specified stack. + +Usage: + apx stacks rm [flags] + +Flags: + -f, --force Force removal of the stack. + -h, --help help for rm + -n, --name string The name of the stack to remove. +``` +Stacks can be removed easily with `apx`. We just need to pass the name argument to the `rm` command. +```bash +apx stacks rm -n noble +``` +``` + INFO Are you sure you want to remove 'noble'? [y/N] +y + INFO Removed stack 'noble'. +``` \ No newline at end of file diff --git a/docs/articles/en/working-w-subsystems.md b/docs/articles/en/working-w-subsystems.md new file mode 100644 index 00000000..c216bda3 --- /dev/null +++ b/docs/articles/en/working-w-subsystems.md @@ -0,0 +1,168 @@ +## Working with Subsystems +You can interact with subsystems using the `apx` CLI as shown below. Managing subsystems is as easy as simple command in a shell. +```bash +apx subsystems --help +``` +``` +Work with the subsystems that are available in apx. + +Usage: + apx subsystems [command] + +Available Commands: + list List all available subsystems. + new Create a new subsystem. + reset Reset the specified subsystem. + rm Remove the specified subsystem. + +Flags: + -h, --help help for subsystems + +Use "apx subsystems [command] --help" for more information about a command. +``` + +## Creating a Subsystem +Subsystems are individual operating system containers built on the concept of stacks in APX. These subsystems can be created and deleted independently of stacks. You can even have multiple isolated subsystems built on the same stack! +```bash +apx subsystems new --help +``` +``` +Create a new subsystem. + +Usage: + apx subsystems new [flags] + +Flags: + -h, --help help for new + -H, --home string The custom home directory of the subsystem. + -i, --init Use systemd inside the subsystem. + -n, --name string The name of the subsystem. + -s, --stack string The stack to use. +``` + +Now that we have created a stack for Ubuntu 24.04, we want to create a new subsystem that is built from that stack. To do this we need to supply a couple parameters to `apx`. +```bash +apx subsystems new +``` +``` + INFO Choose a name: +noble-test + INFO Available stacks: +1. noble +2. alpine +3. arch +4. fedora +5. opensuse +6. ubuntu +7. vanilla-dev +8. vanilla + INFO Select a stack [1-8]: +1 +▀ Creating subsystem 'noble-test' with stack 'noble'… (0s)Resolved "ubuntu" as an alias (/etc/containers/registries.conf.d/shortnames.conf) +Trying to pull docker.io/library/ubuntu:noble... + ▀ Creating subsystem 'noble-test' with stack 'noble'… (1s)Getting image source signatures + ▄ Creating subsystem 'noble-test' with stack 'noble'… (1s)Copying blob ff65ddf9395b [--------------------------------------] 0.0b / 28.4MiB (skipped: 0.0b = 0.00%) Copying blob ff65ddf9395b [--------------------------------------] 0.0b / 28.4MiB (skipped: 0.0b = 0.00%) Copying blob ff65ddf9395b [=>------------------------------------] 1.4MiBCopying blob ff65ddf9395b [=>------------------------------Copying blob ff65ddf9395b [=>------------------------------------] 1.7MiB / 28.4MiB | 2.2 MiB/s Copying blob ff65ddf9395b [===>----------------------------------] 3.2MiB / 28.4MiB | 16.5 MiB/s Copying blob ff65ddf9395b [======>-------------------------------] 4.9MiBCopying blob ff65ddf9395b [========>-----------------------Copying blob ff65ddf9395b [===========>--------------------------] 8.8MiB / 28.4MiB | 19.9 MiB/s Copying blob ff65ddf9395b [==============>-----------------------] 10.9MiB / 28.4MiB | 17.6 MiB/s Copying blob ff65ddf9395b [===============>----------------------] 11.9MiCopying blob ff65ddf9395b [=================>--------------Copying blob ff65ddf9395b [====================>-----------------] 16.0MiB / 28.4MiB | 31.8 MiB/s Copying blob ff65ddf9395b [========================>-------------] 18.7MiB / 28.4MiB | 23.7 MiB/s Copying blob ff65ddf9395b [============================>---------] 21.5MiCopying blob ff65ddf9395b [================================Copying blob ff65ddf9395b [====================================>-] 27.5MiCopying blob ff65ddf9395b done | Copying blob ff65ddf9395b done | +Copying config 59ab366372 done | +Writing manifest to image destination +59ab366372d56772eb54e426183435e6b0642152cb449ec7ab52473af8ca6e3f + ▄ Creating subsystem 'noble-test' with stack 'noble'… (4s) [ OK ] +Distrobox 'apx-noble-test' successfully created. +To enter, run: + +apx noble-test enter + SUCCESS Created subsystem 'noble-test'. +``` +In the above example, we created a new subsystem named `noble-test` from the `noble` stack. We can confirm this by listing the available subsystems in `apx`. +```bash +apx subsystems list +``` +``` + INFO Found 1 subsystems: +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼ +┊ NAME ┊ STACK ┊ STATUS ┊ PKGS ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼ +┊ noble-test ┊ noble ┊ Up 7 minutes ┊ 2 ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┼ +``` +Now that we see that `noble-test` exists, let's try to use the subsystem. We want to `enter` the subsystem which should give us a shell inside the container. +```bash +apx noble-test enter +``` +``` +Starting container... [ OK ] +Installing basic packages... [ OK ] +Setting up devpts mounts... [ OK ] +Setting up read-only mounts... [ OK ] +Setting up read-write mounts... [ OK ] +Setting up host's sockets integration... [ OK ] +Setting up host's nvidia integration... [ OK ] +Integrating host's themes, icons, fonts... [ OK ] +Setting up package manager exceptions... [ OK ] +Setting up package manager hooks... [ OK ] +Setting up dpkg exceptions... [ OK ] +Setting up apt hooks... [ OK ] +Setting up distrobox profile... [ OK ] +Setting up sudo... [ OK ] +Setting up user groups... [ OK ] +Setting up kerberos integration... [ OK ] +Setting up user's group list... [ OK ] +Setting up existing user... [ OK ] +Setting up user home... [ OK ] +Ensuring user's access... [ OK ] + +Container Setup Complete! +jardon@apx-noble-test:~$ +``` +Now that we are inside the container, we can confirm the stack and that it installed `neofetch` like we asked it to when creating the stack. +```bash +neofetch --off --color_blocks off --stdout +``` +``` +jardon@lagann +------------- +OS: Ubuntu 24.04.1 LTS x86_64 +Host: Precision 5560 +Kernel: 6.9.8-amd64 +Uptime: 1 day, 20 hours, 14 mins +Packages: 438 (dpkg) +Shell: bash 5.2.21 +Resolution: 3840x2400 +DE: GNOME +WM: Mutter +Theme: Yaru [GTK3] +Icons: Yaru [GTK3] +Terminal: conmon +CPU: 11th Gen Intel i7-11850H (16) @ 4.800GHz +GPU: Intel TigerLake-H GT1 [UHD Graphics] +GPU: NVIDIA T1200 Laptop GPU +Memory: 12599MiB / 31827MiB +``` +With that, we have successfully created and used a subsystem built on a previously user-defined stack! + +## Deleting a Subsystem +Removing a subsystem with `apx` is easy. Just pass the name of the subsystem to the `apx` command and confirm the deletion. +```bash +apx subsystem rm --help +``` +``` +Remove the specified subsystem. + +Usage: + apx subsystems rm [flags] + +Flags: + -f, --force Force removal of the subsystem. + -h, --help help for rm + -n, --name string The name of the subsystem to remove. +``` + +```bash +apx subsystem rm -n noble-test +``` +``` + INFO Are you sure you want to remove 'noble-test'? [y/N] +y + SUCCESS Removed subsystem 'noble-test'. +``` + +And with that you have successfully deleted the subsystem!