.. Plom documentation
   Copyright (C) 2020-2023 Colin B. Macdonald
   Copyright (C) 2020 Andrew Rechnitzer
   SPDX-License-Identifier: AGPL-3.0-or-later

Installing the Plom Legacy Server
=================================

The instructions here are for the installation of a Plom server.
This **not** required by your markers; they only need to
:doc:`install the Plom client <install-client>`.

You can either use containers to run a server or install Plom from source.


Container images
----------------

Use either `Podman` or `Docker` to download the latest container image and
launch it::

    docker pull plomgrading/server
    docker run -it --rm -p 41984:41984 plomgrading/server

By default, this will launch the demo server.

.. TODO
   document the demo?


The data for the test is in `/exam` inside the Docker image.  You can use your
own local directory with `-v`::

    mkdir my_test
    docker run -it --rm -P -v $PWD/my_test:/exam plomgrading/server

(here `-P` will use a random high port on the host).

You can override the default command, for example::

    docker run -it --rm -v $PWD/my_test:/exam plomgrading/server plom-create new --demo
    docker run -it --rm -v $PWD/my_test:/exam plomgrading/server plom-legacy-server init
    docker run -it --rm -v $PWD/my_test:/exam plomgrading/server plom-legacy-server users --demo
    docker run -it --rm -P -v $PWD/my_test:/exam plomgrading/server plom-legacy-server launch

Alternatively you can get a shell and work inside the image::

    docker run -it --rm plomgrading/server /bin/bash
    plom-create new --demo


You can also connect a shell to a *running image* using `exec`::

    docker exec -it <name> /bin/bash

where `<name>` can found using ``docker ps``; its something like
`ornery_colin`.


Installation using ``pip``
--------------------------

In theory this should be simply::

    pip install plom

but in practice, there are some caveats:

* you may need to upgrade your `pip`, especially if your system
  if a few years old.  Try ``python3 -m pip install --upgrade pip``.
* your system may need additional dependencies from your system
  package manager (``dnf``, ``apt``, etc).

.. note::

   **TODO**: it would be good to document this better!
   For now, see :doc:`install-from-source`.
   It may also be useful to `examine the Containerfile in the source
   code <https://gitlab.com/plom/plom/-/blob/main/Containerfile.legacy>`_.


After installing, you should be able to run the various Plom commands.
Try running `plom-legacy-server` and you should see something like::

    $ plom-legacy-server --version
    plom-legacy-server 0.14.0