doc/source/install.rst

   1 ===============
   2  install guide
   3 ===============
   4
   5 .. Copyright (c) 2020 mudpy authors. Permission to use, copy,
   6    modify, and distribute this software is granted under terms
   7    provided in the LICENSE file distributed with this software.
   8
   9 This guide provides quick setup instructions for a basic mudpy
  10 installation, sufficient as a starting point for further
  11 configuration and customization.
  12
  13 installation
  14 ------------
  15
  16 There's a :ref:`demo` in the :doc:`coder` guide which will get you
  17 up and running right away if you're familiar with the ``tox``
  18 utility, but you can get by with just a supported Python_
  19 interpreter. It's still easiest to do it from a `git clone`_ or
  20 unpacked tarball_ of the source code so you have sample
  21 configuration to work from. As long as your distro doesn't strip the
  22 ``venv`` module out of Python's standard library, from the top-level
  23 source directory you could basically install it as a normal shell
  24 user with::
  25
  26     python3 -m venv mudpy_venv
  27     mudpy_venv/bin/pip install .
  28
  29 And then you can start the service with::
  30
  31     mudpy_venv/bin/mudpy
  32
  33 If the ``python3`` command above emits an error like *No module
  34 named venv*, then you're probably on a distribution like Debian
  35 which needs the `python3-venv package`_ installed with your package
  36 manager first.
  37
  38 .. _Python: https://python.org/
  39 .. _git clone: https://mudpy.org/code/mudpy/
  40 .. _tarball: https://mudpy.org/dist/mudpy/
  41 .. _python3-venv package: https://packages.debian.org/python3-venv
  42
  43 initialization
  44 --------------
  45
  46 The mudpy service is self-initializing the first time you start it,
  47 though you need some minimum configuration in its config search
  48 path. The installation_ example above uses the sample
  49 :file:`etc/mudpy.conf` configuration provided in the source tree,
  50 but you can edit this or make a modified copy and pass its name as
  51 the only command-line argument to the executable entrypoint::
  52
  53     mudpy_venv/bin/mudpy my_config.yaml
  54
  55 By default it'll only listen on the loopback address, but that's
  56 configurable in the `network settings <.mudpy.network>`_ of course.
  57 The basic element definitions are included in the :file:`share`
  58 directory as well as basic archetype, command and menu element
  59 definitions. The default configuration is set so that if anyone
  60 creates a user named "admin" then that account will start with
  61 administrative privileges, configurable in the `admins limit
  62 <.mudpy.limit.admins>`_.
  63
  64 Using ``pip`` to install in a venv or with its ``--user`` option
  65 takes care of making sure the Python package dependencies listed in
  66 the :file:`requirements.txt` file are available, but it should be
  67 possible to run :file:`mudpy/daemon.py` as a normal python3 script
  68 as long as you've installed your distro's packages of the
  69 dependencies (on Debian/Ubuntu that's python3-passlib_ and
  70 python3-yaml_, they're probably named something similar on other
  71 distros).
  72
  73 .. _python3-passlib: https://packages.debian.org/python3-passlib
  74 .. _python3-yaml: https://packages.debian.org/python3-yaml
  75
  76 platforms
  77 ---------
  78
  79 There's a good chance that some of the file handling and socket
  80 routines are not cross-platform compatible and will only work on
  81 Unix derivatives like Linux, \*BSD or GNU Hurd (possibly also Mac OS
  82 X/Darwin since it's essentially a BSD descendant). All changes to
  83 the codebase are tested on Debian GNU/Linux, but it should at least
  84 work reliably on any Linux distribution with a new enough Python
  85 interpreter. It probably also works on Microsoft Windows under the
  86 WSL (Windows Subsystem for Linux) compatibility layer.