.. include:: images.rst
.. include:: /substitutions.rst
.. include:: /urls.rst

.. _pureos_sw_management:

Software Management
===================

.. image:: ../img/gnome-software/sm.puri.Store.svg
   :width: 128
   :align: right
   :alt: The PureOS Store application icon

The **PureOS Store** application provides an easy-to-use graphical interface for searching, installing and uninstalling applications and other software packages.
It can also be used to manage and show information about system updates.

Locate the icon shown above in the app drawer and press it to launch the application.

.. Mobile PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Mobile PureOS</a></summary>


When you launch the **PureOS Store** application, it shows a page like the one shown below, with **Editor's Picks** and **Recent Releases** above a list of **Categories**.

.. |software-highlights| image:: ../img/mobile/gnome-software/software-highlights.png
   :scale: 50%
   :alt: The PureOS Store start page, showing highlighted applications

.. |software-categories| image:: ../img/mobile/gnome-software/software-categories.png
   :scale: 50%
   :alt: The PureOS Store start page, providing access to application categories

.. centered:: |software-highlights| |software-categories|

The header bar contains a search button that can be used to :ref:`search for applications <pureos_sw_search>` and a |menu| (menu) button that allows you to :ref:`add new software sources <pureos_sw_sources>`.

At the bottom of the screen, you can choose between three modes:

.. image:: ../img/mobile/gnome-software/software-modes.png
   :align: center
   :alt: The three modes that can be selected

These modes are used to perform different tasks:

 #. **Explore** allows you to browse all the applications, including those you have installed and those that are available to download.
 #. **Installed** lists only the :ref:`currently installed applications <pureos_sw_list>`, either as system defaults or by the user.
 #. **Updates** shows the applications and other components that require updating, and allows you to :ref:`update them individually or as a whole <pureos_sw_management_update>`

.. raw:: html

   </details>


.. _pureos_sw_search:

Find software
-------------

.. Desktop PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Desktop PureOS</a></summary>

#. Launch **Software** (aka ``gnome-software``) and click the 3-dot button to expand categories to search for a program:

   .. image:: ../img/gnome-software/software-welcome-collapsed.png
      :scale: 50%
      :alt: GNOME Software GUI

#. **Or** just click the search button:

   .. image:: ../img/gnome-software/software-welcome-expanded.png
      :scale: 50%
      :alt: GNOME Software search button

#. ...to type in the name of the program you are looking for:

   .. image:: ../img/gnome-software/software-search-bar.png
      :scale: 50%
      :alt: GNOME Software app search

#. Click the result you want:

   .. image:: ../img/gnome-software/software-search-result.png
      :scale: 50%
      :alt: GNOME Software search result

.. raw:: html

   </details>


.. Mobile PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Mobile PureOS</a></summary>

On the main **PureOS Store** page, shown when the **Explore** tab is selected, you can find a search button at the top-left of the screen.
Pressing this button causes a search bar to appear.
The on-screen keyboard should also appear, allowing you to enter keywords.

.. image:: ../img/mobile/gnome-software/software-search-start.png
   :align: center
   :scale: 50%
   :alt: Opening the search bar

Enter the search terms for the application you are looking for.
The page will update to show appropriate matches as you enter text, finding applications based on their metadata.

.. image:: ../img/mobile/gnome-software/software-search-results.png
   :align: center
   :scale: 50%
   :alt: Searching for an application

Once you have found a suitable application, select it in the list of search results to show more information about it.
You can always return to the search results by pressing the back button at the top-left of the screen.

.. raw:: html

   </details>


.. _pureos_sw_list:

List installed software
-----------------------

.. Mobile PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Mobile PureOS</a></summary>

#. Select the tab for the **Installed** mode at the bottom of the screen.
   The installed software page shows the applications and components that have been installed on the phone.

   .. tip::
      View more information about each of the installed applications by tapping its icon in the list.

   .. |software-list-installed| image:: ../img/mobile/gnome-software/software-installed.png
      :scale: 50%
      :alt: A list of installed applications

   .. |software-details| image:: ../img/mobile/gnome-software/software-app-details.png
      :scale: 50%
      :alt: Showing the details of an application

   .. centered:: |software-list-installed| |software-details|

#. Press the back button at the top-left of the screen to return to the list of installed applications.

.. raw:: html

   </details>


.. _pureos_sw_installation:

Install software
----------------


.. _pureos_sw_installation_graphical:

Graphical method
~~~~~~~~~~~~~~~~


.. _pureos_sw_installation_with_gnome_software:

GNOME Software
^^^^^^^^^^^^^^

This section describes how to install applications in PureOS.

.. Desktop PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Desktop PureOS</a></summary>

#. :ref:`Locate the software <pureos_sw_search>` for installation
#. Click the **Install** button:

   .. image:: ../img/gnome-software/software-install-button.png
      :scale: 50%
      :alt: GNOME Software Install button

#. Enter your password and click **Authenticate** (or press **Enter** on your keyboard):

   .. image:: ../img/gnome-software/software-install-authentication.png
      :scale: 50%
      :alt: GNOME Software password authentication

#. Wait for the application to install:

   .. image:: ../img/gnome-software/software-install-progress.png
      :scale: 50%
      :alt: GNOME Software software installation

#. The software is now installed!

   .. image:: ../img/gnome-software/software-installed-launch-button.png
      :scale: 50%
      :alt: GNOME Software software installed

.. raw:: html

   </details>


.. Mobile PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Mobile PureOS</a></summary>

Once you have found an application you want to install, you can review the description, software license and other details on its information page.

.. image:: ../img/mobile/gnome-software/software-install-app.png
   :align: center
   :scale: 50%
   :alt: Viewing an application's information

You may then choose to install the application by pressing the **Install** button, or press the back button at the top-left of the screen to return to the search results.

When you decide to install the application, progress on the installation process is reported above the description of the application.

.. image:: ../img/mobile/gnome-software/software-installing-app.png
   :align: center
   :alt: Installing an application

When the application has finished installing, you can launch it immediately by pressing the **Launch** button.
If you changed your mind, you can also remove it by pressing the **Remove** button.
You will be asked for confirmation before the application is uninstalled.

.. image:: ../img/mobile/gnome-software/software-installed-app.png
   :align: center
   :alt: Ready to launch an installed application

Installed applications are available in the app drawer, so you do not need to use the **PureOS Store** application to launch them.

.. raw:: html

   </details>


.. _pureos_sw_installation_deb:

.deb package installer
^^^^^^^^^^^^^^^^^^^^^^

This section describes how to install a downloaded ``.deb`` package using a graphical installer.

.. warning::
   It is not generally recommended to install packages this way.
   Installing untrusted 3rd party packages may possibly lead to unexpected security or incompatibility issues.

.. Desktop PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Desktop PureOS</a></summary>

#. Right-click on a downloaded ``.deb`` package file and click **Open With Other Application**:

   .. image:: ../img/instdeb1.png
      :scale: 50%
      :alt: Right-click context menu

#. Click **Software Install**, then click **Select**:

   .. image:: ../img/instdeb2.png
      :scale: 50%
      :alt: Application selection window

#. An installer window will open; click **Install** to install it:

   .. image:: ../img/instdeb3.png
      :scale: 50%
      :alt: Package installation window

#. Type your password if prompted.

.. raw:: html

   </details>


.. _pureos_sw_uninstallation:

Remove software
---------------

.. _pureos_sw_uninstallation_gnome_software:

Graphical method
~~~~~~~~~~~~~~~~

This section describes how to uninstall (remove) software using GNOME Software (aka ``gnome-software``, or just **Software**).

.. Desktop PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Desktop PureOS</a></summary>

#. Launch **Software** and open the **Installed** tab.
#. Locate the application you wish to remove, then click **Remove**:

   .. image:: ../img/gnome-software/Screenshot_from_2017-06-20_11-24-30.png
      :scale: 50%
      :alt: GNOME Software installed application list

#. Click **Remove** at the prompt, and enter your password if prompted:

   .. image:: ../img/gnome-software/Screenshot_from_2017-06-20_11-25-03.png
      :scale: 50%
      :alt: GNOME Software installed application removal password prompt

.. raw:: html

   </details>


.. Mobile PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Mobile PureOS</a></summary>

Applications can be uninstalled from the **Installed** tab by pressing the |delete| (delete) button to the right of the application's name and icon.
You will be asked to confirm that you wish to uninstall the application.

.. image:: ../img/mobile/gnome-software/software-remove-app.png
   :align: center
   :scale: 50%
   :alt: Uninstalling an application

Press **Remove** to confirm that you want to uninstall the application, or press **Cancel** to keep it.

.. raw:: html

   </details>


.. _pureos_sw_management_update:

Update software
---------------

It is good practice to regularly update applications and components to ensure that you have the latest versions of them.
These should contain fixes for any problems that have been reported by users and developers.


.. _pureos_sw_update_gnome_software:

Graphical method
~~~~~~~~~~~~~~~~

Software is updated automatically under normal circumstances but be optionally be updated manually.
This section describes how to update software manually using GNOME Software.

.. Desktop PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Desktop PureOS</a></summary>

#. Start Software and click the reload button in upper left corner:

   .. image:: ../img/gnome-software/update1.png
      :scale: 50%
      :alt: GNOME Software update refresh list button

#. Wait for the upgrades to download:

   .. image:: ../img/gnome-software/update2.png
      :scale: 50%
      :alt: GNOME Software update download

#. Click the **Restart & Install** button once you are ready to install the updates:

   .. image:: ../img/gnome-software/update3.png
      :scale: 50%
      :alt: GNOME Software update restart and install button

.. raw:: html

   </details>


.. Mobile PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Mobile PureOS</a></summary>

#. Ensure that you have enabled a network connection, either via `WLAN <https://docs.puri.sm/Hardware/Librem_5/Using_Your_Phone/WLAN.html>`_ or a mobile data connection.
#. Select the **Updates** tab at the bottom of the screen, which will then display one of the following:
    #. A list of pending updates
    #. A message indicating that the system is looking for updates
    #. A network connection is unavailable

   .. |software-updates-online| image:: ../img/mobile/gnome-software/software-updates.png
      :scale: 50%
      :alt: Looking for updates to applications and system software

   .. |software-updates-offline| image:: ../img/mobile/gnome-software/software-updates-offline.png
      :scale: 50%
      :alt: The network is offline

   .. centered:: |software-updates-online| |software-updates-offline|

#. Press the **Network Settings** button to configure the network connection then return to the **PureOS Store** application and continue.
   If the updates have been found, you will either see a message indicating that the software is up-to-date or a list of updates.

   .. |software-up-to-date| image:: ../img/mobile/gnome-software/software-updates-up-to-date.png
      :scale: 50%
      :alt: The installed software is up-to-date

   .. |software-updates-found| image:: ../img/mobile/gnome-software/software-updates.png
      :scale: 50%
      :alt: The Updates tab showing the pending updates

   .. centered:: |software-up-to-date| |software-updates-found|

   The updates are sorted into two sections: **Requires Restart** and **Application Updates**.

#. Each application requiring an update can be individually updated by pressing the button on the right hand side of its name.
   The amount of data that will be downloaded is shown below this button.
   Alternatively, press the **Update All** button to update all applications that require updates.

   .. note::
      This may require large amounts of data to be downloaded.

When you update an application, the button to the right of it becomes an update indicator which shows the progress being made to download new data.

.. image:: ../img/mobile/gnome-software/software-updating-app.png
   :align: center
   :alt: Updating a component

The application or component will be removed from the list of updates after it has been updated.

If there is a pending operating system (OS) update that requires a system restart, there will be one or more items in the **Requires Restart** section on the page.
See the :ref:`pureos_sw_update_gnome_software_system` section for more information.


.. _pureos_sw_update_gnome_software_system:

Update system software
^^^^^^^^^^^^^^^^^^^^^^

.. Mobile PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Mobile PureOS</a></summary>

Software updates that require the system to restart are shown in the **Requires Restart** section of the **Updates** tab.

.. image:: ../img/mobile/gnome-software/software-updates.png
   :align: center
   :scale: 50%
   :alt: Software updates including one that requires a system restart

You may want to shut down applications before installing an update in this section.
Press the **Download** button to download the update, ready for installation.
Note that the update may be downloaded automatically but not installed depending on the update configuration -- see the :ref:`pureos_sw_update_configuring_updates` section for more information.

When the update is ready to install, the **Download** button will change to **Restart & Update**.

.. image:: ../img/mobile/gnome-software/software-updating-restart.png
   :align: center
   :scale: 50%
   :alt: Ready to install an OS update

Press the button when you are ready to restart the system and install the update.
The screen will fade to black then the system will restart.

.. raw:: html

   </details>


.. _pureos_sw_update_terminal:

Terminal method
~~~~~~~~~~~~~~~

Software is usually updated automatically under normal circumstances, but you may wish to manually update your software.
This section describes how to update software manually using a terminal emulator.

.. note::
   Remember to update and upgrade before installing any package.

Update software repos
^^^^^^^^^^^^^^^^^^^^^

#. :ref:`Launch a terminal emulator <pureos_terminal_launch>` and run the following command:

   .. code-block:: bash

      sudo apt update

#. Enter the password if prompted, then press **Enter**.
   When the command finishes, your software repos (information about available packages-applications which can be installed) will be updated.

Upgrade system
^^^^^^^^^^^^^^

#. :ref:`Launch a terminal emulator <pureos_terminal_launch>` and run the following command:

   .. code-block:: bash

      sudo apt upgrade

   .. note::
      You can also execute ``sudo apt full-upgrade`` to force all packages to upgrade.

#. Enter the password if prompted, then press **Enter**.
#. You will be asked to proceed.
   Press **Enter** if you want this; press **n** and then **Enter** if you do not.

When the command finishes, all the packages you installed will be upgraded to their latest versions available.
Sometimes it is advisable to restart your computer.


.. _pureos_sw_update_terminal_single_command:

One-line command
^^^^^^^^^^^^^^^^

One-line command to update repos and upgrade system afterwards:

.. code-block:: bash

   sudo apt update && sudo apt full-upgrade


.. _pureos_sw_update_configuring_updates:

Configure updates
~~~~~~~~~~~~~~~~~

.. Mobile PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Mobile PureOS</a></summary>

#. Open the application menu and select the **Update Preferences** to configure how updates are handled.

   .. |software-update-preferences-menu| image:: ../img/mobile/gnome-software/software-update-preferences-menu.png
      :alt: Opening the application menu

   .. |software-update-preferences| image:: ../img/mobile/gnome-software/software-update-preferences.png
      :alt: The Update Preferences page

   .. centered:: |software-update-preferences-menu| |software-update-preferences|

#. When you have adjusted the options, press the back button to return to the previous view.

.. raw:: html

   </details>


.. _pureos_sw_update_notifications:

Update notifications
~~~~~~~~~~~~~~~~~~~~

Depending on the configuration, notifications will be shown when software updates are available.
These can be viewed by opening the settings panel at the top of the screen.

.. image:: ../img/mobile/gnome-software/software-updates-notification.png
   :align: center
   :scale: 50%
   :alt: Notifications indicate when software updates are available

You can dismiss a notification by pressing **Not Now** or press **View** for more information.


.. _pureos_sw_sources:

Add software sources
--------------------

This section describes how to add software sources, also known as repositories (repos).
Adding software sources, :ref:`like mirrors <pureos_mirror>`, can speed up the download of packages and updates to your system.

Graphical method
~~~~~~~~~~~~~~~~

.. Desktop PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Desktop PureOS</a></summary>

#. Launch the **Software & Updates** app (aka ``software-properties-gtk``):

   .. image:: ../img/software-properties-gtk/su1.png
      :scale: 50%
      :alt: Software & Updates GUI

#. Click the **Other Software** tab
#. Click the **Add...** button
#. Fill in the path to the software repository you wish to add:

   .. image:: ../img/software-properties-gtk/su2.png
      :scale: 50%
      :alt: Adding a software repository

#. Click the **Add Source** button.
#. Optional: If you need to add keys for the newly added repo, check the **Authentication** tab:

   .. image:: ../img/software-properties-gtk/su4.png
      :scale: 50%
      :alt: Authentication tab

.. raw:: html

   </details>


.. Mobile PureOS collapsible section

.. raw:: html

   <details>
   <summary><a>Mobile PureOS</a></summary>

Packages can be downloaded from a variety of sources.
To configure these, open the menu by pressing the |menu| (menu) button at the top-right of the scren.

.. image:: ../img/mobile/gnome-software/software-menu.png
   :align: center
   :alt: Opening the application menu

Select the **Software Repositories** item to launch a separate tool for adding, removing and configuring the remote repositories containing software that can be downloaded.

.. raw:: html

   </details>


Terminal method
~~~~~~~~~~~~~~~

By default, you should have this line in your ``/etc/apt/sources.list`` file:

.. code-block:: bash

   deb https://repo.pureos.net/pureos byzantium main
   deb https://repo.pureos.net/pureos byzantium-security main
   deb https://repo.pureos.net/pureos byzantium-updates main

If you want to add more repos, just edit this text file and the appropriate lines below this first line.

For example, you can add a PureOS mirror is you're in North America, this will speed up your downloads.
Simply add this line to your ``/etc/apt/sources.list`` file;

.. code-block:: bash

   deb https://mirrors.sonic.net/pureos/repo/pureos/ byzantium main

For Europe, consider using this mirror:

.. code-block:: bash

   deb https://mirror.linux.pizza/pureos byzantium main
   deb https://mirror.linux.pizza/pureos/ byzantium-updates main
   deb https://mirror.linux.pizza/pureos/ byzantium-security main


.. _pureos_sw_upgrade_release:

Upgrade to a newer PureOS release
---------------------------------

PureOS has gone under some big changes over the last year or so.
In addition to the work being done on PureOS to make it convergent on more devices, we have also introduced `a new stable version <https://puri.sm/posts/pureos-rolls-on-as-stable>`_ of PureOS called |StableSuite|.
We still continue to update |OldStableSuite| although not as frequently.
Important updates, like security updates and other important fixes come in now to two dedicated suites of packages called ``amber-updates`` and ``amber-security``.

These ought to have come into your system automatically in a package called ``base-files`` but, if they did not, you can :ref:`add these suites <pureos_sw_sources>` via the Software tool or on the command line.

Simply add these two lines to the ``/etc/apt/sources.list`` file:

.. code-block:: bash

   deb https://repo.pureos.net/pureos/ amber-updates main
   deb https://repo.pureos.net/pureos/ amber-security main

:ref:`Update <pureos_sw_update_terminal_single_command>` to the latest |OldStableSuite| before moving to |StableSuite|.

If you are prepared to migrate to |StableSuite|, you can simply add the repository via the :ref:`GNOME Software tool <pureos_sw_sources>`, or you can edit your ``/etc/apt/source.list`` file.
Here is what the contents of the file should be for |StableSuite|:

.. code-block:: bash

   deb https://repo.pureos.net/pureos/ byzantium main
   deb https://repo.pureos.net/pureos/ byzantium-updates main
   deb https://repo.pureos.net/pureos/ byzantium-security main

Proceed to perform full update.
It is recommended to this via :ref:`terminal command <pureos_sw_update_terminal_single_command>`, so that you can see if any errors come up.

This will update a ton of package on your machine, so be patient until it is done.
If no errors reported, restart the system and you have |StableSuite|, the latest stable PureOS release.