diff --git a/docs/articles/en/working-w-pkgms.md b/docs/articles/en/working-w-pkgms.md new file mode 100644 index 00000000..a6af10c8 --- /dev/null +++ b/docs/articles/en/working-w-pkgms.md @@ -0,0 +1,243 @@ +## Working with Package Managers +```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 ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +``` + +## 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. +``` +```bash +apx pkgmanagers rm -n yum +``` +``` + INFO Are you sure you want to remove 'yum'? [y/N] +y + INFO Removed package manager 'yum'. +``` \ No newline at end of file diff --git a/docs/articles/en/working-w-stacks.md b/docs/articles/en/working-w-stacks.md new file mode 100644 index 00000000..0454913f --- /dev/null +++ b/docs/articles/en/working-w-stacks.md @@ -0,0 +1,195 @@ +## 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 +```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. +``` +```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 ┊ +┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼ +``` + +## 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. +``` +```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!