.. index:: Hubs
.. _hubs:

Hubs
===========

The hub services are the frontend layer of CoCalc, handling all user-facing traffic and backend coordination.
They communicate using :term:`Conat`, CoCalc's internal messaging system.

**Multi-replica services** (scaled for traffic):

-  ``hub-conat-api``: clients from the web connect via websockets. This
   service also controls the database, provides the ``/api`` endpoints, etc.

   -  During normal usage, it is expected that up to 50 simultaneous
      connections are possible, 30 are great.
   -  It's fine to run 5 or more websocket hubs.
   -  Session-sticky via ingress cookie affinity.

-  ``hub-conat-persist``: stores data in the shared file-system (NFS mode) or a
   dedicated disk (disk mode). This is the persistence layer for Conat.
   Multiple persist server processes run inside each pod using hash-based sharding.

-  ``hub-conat-router``: uses :term:`SocketIO` to route messages between all CoCalc services,
   including projects.

-  ``hub-proxy``: establishes a connection to the projects, requires a
   client with a valid authentication. Also handles file uploads.

   -  During normal usage, at least 50 simultaneous connections are possible.
   -  It's fine to run 5 or more proxy services.
   -  Session-sticky via ingress cookie affinity.

-  ``hub-next``:

   -  Serves dynamic pages like the landing page at ``/``, ``/info``, ``/policies``, etc.
   -  This service also renders shared files of users at ``/share`` or
      even a custom name at
      ``/[user name]/[project nickname]/[share nickname]``.
   -  Finally, it also serves ``/api/v2``.
   -  There should be at least two next services running.

**Single-instance services** (background tasks):

-  ``hub-maintenance-expired``: removes old/expired rows from the database.
-  ``hub-maintenance-syncstrings``: maintenance tasks for synchronized documents.
-  ``hub-mentions``: sends email notifications for ``@name`` mentions in chat messages.
-  ``hub-delete-projects``: periodically unlinks projects that have been marked as deleted
   (controlled by ``hub.deleteProjectsIntervalH``, default: 1 hour).
-  ``hub-stats``: collects statistics about CoCalc itself; serves the ``/stats`` endpoint.

Restart an aspect e.g. via ``kubectl rollout restart deploy hub-next``.

Restart all hubs via ``kubectl rollout restart deploy -l group=hub``.