***************
Getting Started
***************

Installation
============

``seamm_webui`` is pip-installable and does not require conda or the rest
of the SEAMM stack to be installed first (though it does need a SEAMM
datastore to point at)::

  pip install seamm_webui

Running it
==========

Start the server, pointed at an existing SEAMM datastore (defaults to
``~/SEAMM/Jobs``)::

  seamm-webui --datastore ~/SEAMM/Jobs

If the datastore has no database yet (``seamm.db``) but there are job directories in
it, the database is built from them when the server starts, as the old Dashboard did:
each job's flowchart and ``job_data.json`` are imported. Such a database has no
accounts from before; to rebuild a database while keeping its accounts and job owners,
use ``seamm-manager datastore rebuild`` instead. Neither converts flowcharts to format
3.0 -- that is ``seamm-manager flowcharts migrate``.

This is fully self-contained: a release install (from PyPI) bundles the
built browser UI, so there's nothing else to start or configure -- visit
the URL it prints and the dashboard itself is what loads (not just the
API). A source/editable install that hasn't run ``npm run build`` in
``frontend/`` falls back to serving the API only.

By default this binds to ``127.0.0.1`` with no login required -- fine for
using it on your own machine. To make it reachable from other machines,
pass a non-loopback ``--host``; real per-user login then becomes required
automatically (``seamm-webui`` refuses to start otherwise), and so does
HTTPS: with no ``--ssl-certfile``/``--ssl-keyfile`` given, a self-signed
certificate is generated once and reused from then on (browsers will warn
about it being untrusted, the same as any self-signed certificate, until
it's trusted or replaced with a real one). See ``seamm-webui --help`` for
the full set of options, and the User Guide for how authentication works.

If the paired JobServer instance (the one actually running submitted jobs,
sharing the same ``--root``) is configured with more than one queue --
different clusters, or a plain local-subprocess queue alongside one or
more real SLURM ones -- ``GET /api/queues`` lists them, for a submission
client (e.g. the SEAMM desktop app's submit dialog) to offer a picker
instead of always using that instance's default; the job list/detail
pages here also show which queue a job ran on (see the User Guide). This
needs no configuration beyond what the JobServer itself already has:
``seamm-webui`` reads the same ``<root>/<jobserver-name>.ini``. The one
case needing an explicit ``--jobserver-name`` is a host running more than
one independent JobServer instance -- it otherwise defaults to this
host's hostname, matching the JobServer's own default.

For a queue with ``transport = ssh`` (a remote SLURM cluster with no
filesystem shared with the JobServer), a running job's files live in a
scratch directory on that remote host and are otherwise only pulled back
once the job finishes. ``seamm-webui`` reuses that same ``seamm_slurm``
staging machinery to pull them back on demand instead -- automatically
when a job's detail page is opened, and again from that page's file
viewer Refresh button -- so files are visible while the job is still
running, not just after. This also needs no separate configuration: it
reads the same ini section (``remote_root``, etc.) the JobServer itself
uses to stage the job out there in the first place.

For setting this up as a persistent daemon (rather than a foreground
terminal command), see :doc:`../developer_guide/installation`.

Accounts for that login mode are created with the companion
``seamm-webui-user`` command, e.g.::

  seamm-webui-user create alice

An existing account's password can be reset the same way (e.g. if it's
forgotten, or was only ever a bootstrap/test default)::

  seamm-webui-user set-password alice

This always prompts for the new password interactively (there's no
``--password`` flag, unlike ``create``) so it's never typed anywhere --
a shell command, a shared terminal session -- where it could be captured.
``seamm-webui-user delete alice`` removes an account entirely (asks for
confirmation unless ``--yes`` is given).

Once one admin account can log in, the same create/reset-password/delete
operations are also available from the web UI's Admin page (see the
:ref:`User Guide <user-guide>`) -- the command line is really only needed
for that first account, before anyone can log in yet.

That should be enough to get started. For more detail about using the
dashboard, see the :ref:`User Guide <user-guide>`.