Skip to content

Commit

Permalink
docs: add NCDU info for system storage management tutorial (#568)
Browse files Browse the repository at this point in the history
  • Loading branch information
dfguerrerom authored Feb 27, 2024
2 parents d77f744 + 42ab2dd commit b88ecd6
Show file tree
Hide file tree
Showing 6 changed files with 86 additions and 0 deletions.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/_images/setup/storage/preview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/source/setup/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -37,5 +37,6 @@ For usage questions, ask the `GIS StackExchange community <https://gis.stackexch
gee
nicfi
resource
storage
filezilla
password
85 changes: 85 additions & 0 deletions docs/source/setup/storage.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
Manage Disk Usage
=================

In SEPAL, efficient storage management is crucial due to the limited storage capacity. We highly recommended to regularly audit and clean your storage space to maintain optimal system functionality and your resources under the limits.

For non-expert users, initiating storage cleanup can seem daunting. It's important to start with directories known for accumulating large files, such as :code:`/var/log` (system logs), :code:`/tmp` (temporary files), and personal directories like :code:`~/Downloads` or :code:`~/module_results`. A conservative estimate for high storage usage in these areas can vary depending on individual use cases and system configurations. However, as a general guideline, any single folder occupying more than 1GB of space warrants a closer look, especially if it's not actively used for current projects.

To make things easier, SEPAL has integrated the command line tool called :code:`ncdu` (NCurses Disk Usage), this is a command-line utility that provides a convenient and efficient way to analyze disk usage on the SEPAL environment. It uses a text-based user interface to navigate through directories and view which files and folders are consuming disk space.

Prerequisites
=============

- Access to a terminal
- Start a new session (it can be a t1)

Usage
=====

After starting a session, you can start analyzing disk usage by simply typing :code:`ncdu` in your terminal:

.. code-block:: bash
ncdu
If you want to analyze a specific directory, you can specify the directory path as an argument to the command:

.. code-block:: bash
ncdu /path/to/directory
.. thumbnail:: ../_images/setup/storage/scanning_files.png
:title: NCDU Dashboard
:width: 70%
:align: center


Navigating :code:`ncdu`
-----------------------

- Use the arrow keys (:btn:`<fa-solid fa-square-caret-left>`, :btn:`<fa-solid fa-square-caret-up>`, :btn:`<fa-solid fa-square-caret-right>`, :btn:`<fa-solid fa-square-caret-down>` ) to navigate through the files and directories.
- Press :code:`Enter` to enter a directory.

.. thumbnail:: ../_images/setup/storage/preview.png
:title: NCDU preview
:width: 70%
:align: center

Understanding the Interface
----------------------------

- The size of the files and directories is shown on the left .
- The graphical representation of disk usage is displayed next to the size.
- The percentage of disk space used by each file or directory relative to the parent directory is shown at the beginning of each line.

Advanced Usage
==============

.. Attention::

Be cautious when deleting files or directories. Deleting system files or directories can cause system instability or data loss.

- Press ``d`` to delete a file or directory (be cautious with this operation).
- Press ``q`` to quit :code:`ncdu`.

.. thumbnail:: ../_images/setup/storage/delete_file_confirm.png
:title: NCDU delete confirmation
:width: 70%
:align: center

.. thumbnail:: ../_images/setup/storage/delete_file_progress.png
:title: NCDU delete progress
:width: 70%
:align: center

To see a list of all available options and features, you can use the ``--help`` option:

.. code-block:: bash
ncdu --help
Some useful flags include:

- ``-x``: Stay on the filesystem of the directory being scanned.
- ``-q``: Quick mode, doesn't count sizes of subdirectories.
- ``-o``: Export the results to a file.

0 comments on commit b88ecd6

Please sign in to comment.