<commit_before>Setup Server
=============

A  ``qcfractal-server`` instance contains a record of all results, task queue,
and collection information and provides an interface to all FractalClients
and ``qcfractal-manager``\s. All data is stored in a local MongoDB. A server
instance should be run on hardware that is for long periods stable (not
shutdown often),  accessible from both compute resources and users via HTTP,
and have access to permanent storage.  This location is often either research
groups local computers, a supercomputer with  appropriately allocated
resources for this task, or the cloud.

.. note::

    Fractal will use a PostgreSQL database backend instead of MongoDB in versions
    after 0.7. Upgrade tools will be provided for converting existing Fractal server
    instances from Mongo to SQL. These docs will be updated at that time to reflect
    the changes as well.


Using the Command Line
----------------------

A ``qcfractal-server`` instance for long-term computation should be created from
the command line like so:

.. code-block:: console

    >>> qcfractal-server mydb

In each case ``qcfractal-server`` requires a database to connect to, in this
case, ``mydb`` is the database name. This command connects to
``localhost::27017`` by default which is MongoDB's default location. Other
MongoDB locations can be passed in with the ``--database-uri`` flag. Multiple
``qcfractal-server`` can be connected to the same MongoDB, but only one
``qcfractal-server`` should be connected to a single database name.

.. note::

    A MongoDB instance must be setup for a ``qcfractal-server``. MongoDB
    can be installed from ``conda`` and comes with ``conda install qcfractal``
    by default. An example setup can be found below:

    .. code-block:: console

        >>> MONGOPATH=/tmp/example
        >>> mkdir -p $MONGOPATH
        >>> mongod --dbpath $MONGOPATH

For small or trial instances of ``qcfractal-server`` an instance can be spun
up with compute with the following lines:

.. code-block:: console

    >>> qcfractal-server mydb --local-manager

This will create a ``qcfractal-manager`` attached to the ``qcfractal-server``
with a ProcessPoolExecutor attached.

Within a Python Script
----------------------

Canonical workflows can be run from a Python script using the ``FractalSnowflake``
instance. With default options a ``FractalSnowflake`` will spin up a database backend
which contains no data and then destroy this database upon shutdown.

.. warning::

    All data inside a ``FractalSnowflake`` is temporary and will be deleted when the
    ``FractalSnowflake`` shuts down.

.. code-block:: python
<commit_msg>Docs: Updates server cli startup to new commands<commit_after>Setup Server
=============

A  ``qcfractal-server`` instance contains a record of all results, task queue,
and collection information and provides an interface to all FractalClients
and ``qcfractal-manager``\s. All data is stored in a PostgreSQL database which is often
handled transparently. A server
instance should be run on hardware that is for long periods stable (not
shutdown often),  accessible from both compute resources and users via HTTP,
and have access to permanent storage.  This location is often either research
groups local computers, a supercomputer with  appropriately allocated
resources for this task, or the cloud.


Using the Command Line
----------------------

The command line is used for ``qcfractal-server`` instances that are long-term
data storage and task distribution engines. To begin, a ``qcfractal-server``
is first initialized using the command line:

.. code-block:: console

    >>> qcfractal-server init

This initialization will create ``~/.qca/qcfractal`` folder (which can be
altered) which contains default specifications for the ``qcfractal-server``
and for the underlying PostgreSQL database. The ``qcfractal-server init
--help`` CLI command will describe all parameterizations of this folder. In
addition to the specification information, a new PostgreSQL database will be
initialized and started in the background. The background PostgreSQL database
consumes virtually no resources when not in use and should not interfere with
your system.

Once a ``qcfractal-server`` instance is initialized the server can then be run
with the ``start`` command:

.. code-block:: console

    >>> qcfractal-server start

The QCFractal server is now ready to accept new connections.


Within a Python Script
----------------------

Canonical workflows can be run from a Python script using the ``FractalSnowflake``
instance. With default options a ``FractalSnowflake`` will spin up a fresh database which
will be removed after shutdown.

.. warning::

    All data inside a ``FractalSnowflake`` is temporary and will be deleted when the
    ``FractalSnowflake`` shuts down.

.. code-block:: python

{'fraction_non_alphanumeric': 0.08813838550247118, 'fraction_numerical': 0.001441515650741351, 'mean_word_length': 3.911021233569262, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 24, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6525102', 'n_tokens_mistral': 1282, 'n_tokens_neox': 1229, 'n_words': 640}