.. index:: Projects

.. _project:
.. _projects:

Projects
===============

User projects run as pods.
You can think of them as a container running a Linux environment with an unprivileged user inside.
Each project has their own ``$HOME``-directory on a shared filesystem.
Their common user is called ``user`` and runs under :term:`UID` ``2001``.

Overall, these project pods will use up most of the resources,
because the services mentioned above scale with a much smaller factor in the number of users.

Their resource requests and limits are configured via quota settings (only admins can do that), or via "licenses" (see :ref:`licenses`).
This means there could be projects requesting a significant chunk of available CPU or memory resources.

For this CoCalc setup, the "request" is calculated from the limits via an over-commit ratio.
This is set via the global site configuration settings, i.e. ``global.settings.default_quotas``
or that same filed in Admin → Site Settings.
The parameter ``cpu_oc: 10`` means the cpu over-commit ratio is 1:10 – which is fine for interactive use,
because most of the time projects wait for user input.
Similarly ``mem_oc: 5`` means the memory over-commit ratio is 1:5.

Main challenges

- You have to plan/adjust the size and number of nodes to match the overall requests for projects.
- Users are sensitive to interrupted projects, because they can't
  continue working and their intermediate state in e.g. notebooks is
  lost. Hence you can't just willy-nilly delete projects.
- Users are also sensitive to slow startup times.
  That's why the :ref:`prepull` service exists, pulling the large project images before marking
  the node ready for running these projects.
- You can also partition the cluster :ref:`heterogeneously <heterogeneous>`,
  such that some projects run only on specific nodes, while all other projects
  end up in a common pool of project nodes.

.. note::

    New since version ``3.0.0``: similar to :ref:`datastore`,
    the software for the project server controlling each project,
    is mounted from a sidecar.
    This untangles the software users are running in a project from the required infrastructure necessary for CoCalc.
    In turn, this makes it easier to create :ref:`customized software environments <ops-software-env>`.