Revert "No longer run setup.py in docs builds"
[mudpy.git] / doc / source / admin.rst
1 =============
2  admin 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 basic management, configuration and
10 troubleshooting tips for mudpy administrators.
11
12 .. _admin-accounts:
13
14 admin accounts
15 --------------
16
17 Either create an account named *admin* or modify the main
18 configuration file (for example, :file:`etc/mudpy.yaml`) and change
19 the ``.mudpy.limit.admins`` list to include the name of your initial
20 admin user. Once you have at least one administrative user, that
21 user can so something like :command:`set account.someuser
22 administrator True` to elevate another account's access. It's
23 probably best to empty or remove the ``.mudpy.limit.admins list``
24 from the configuration before making the service publicly
25 accessible.
26
27 While the service isn't running you can also edit the accounts.yaml
28 file (probably :file:`data/accounts.yaml` unless you've changed the
29 default data path) and add a line like
30 ``account.someuser.administrator: true`` for any already existing
31 account in that file. In future, a separate system command-line
32 utility may be provided to make pre-seeding administrator accounts
33 possible at time of installation so that the service doesn't need to
34 be started with an initially insecure configuration.
35
36 content creation
37 ----------------
38
39 Once you've created and awakened an avatar for an an
40 :ref:`administrator <admin-accounts>`, you can use the interactive
41 command-line interface to create or destroy elements and set or
42 delete facets on them. A set of sample elements are available in the
43 source tree and included by default from the sample configuration
44 file (specified in its ``_load`` list). You can also just edit those
45 files with a text editor or create a new directory with your own
46 YAML file in it to load instead.
47
48 See the built-in :command:`help` as an administrator for the
49 :command:`create`, :command:`destroy`, :command:`set` and
50 :command:`delete` commands. For example, you can set an arbitrary
51 value on a facet of any element like::
52
53     set account.someuser myperm True
54
55 This would add or update a *myperm* facet to the account element for
56 the *someuser* user to have the value *True*.
57
58 troubleshooting
59 ---------------
60
61 The administrative :command:`show` command provides a number of
62 useful inspection tools. Here's an example testing with the
63 :command:`show result` subcommand from an active session with a
64 couple of avatars awake, comparing with the output from related
65 :command:`show group` and :command:`show element` invocations::
66
67     > show group actor
68
69     These are the elements in the "actor" group:
70
71        actor.avatar_admin_0
72        actor.avatar_luser0_0
73
74     > show result actor.universe.groups['actor'].keys()
75
76     dict_keys(['avatar_admin_0', 'avatar_luser0_0'])
77
78     > show element actor.avatar_luser0_0
79
80     These are the properties of the "actor.avatar_luser0_0" element (in
81     "/home/fungi/src/mudpy.org/mudpy/data/actor.yaml"):
82
83        gender: female
84        inherit: ['archetype.avatar', 'archetype.actor']
85        location: area.0,0,0
86        name: Keyo
87
88     > show result actor.universe.contents['actor.avatar_luser0_0'].get('name')
89
90     'Keyo'
91
92 Note that for safety the :command:`show result` executes within the context of
93 a command handler with only Python's :code:`__builtins__`, the :code:`mudpy`
94 library package, and the active :code:`universe` available.