src/postorius/doc/setup.rst

   1 ============
   2 Installation
   3 ============
   4
   5 .. note::
   6     This installation guide covers Postorius, the web user interface for
   7     GNU Mailman 3. To install GNU Mailman follow the instructions in the `documentation`_.
   8
   9
  10 .. _documentation: http://docs.mailman3.org/en/latest/
  11
  12 Install Postorius
  13 =================
  14
  15 Postorius supports Python 3.6+ and Django 2.2+. This information could however
  16 be out-of-date at a future time. Please refer to the the setup.py for the
  17 latest supported version of Django.
  18
  19
  20 Latest release
  21 --------------
  22
  23 If you just want to install the latest release of Postorius, install it from
  24 PyPi:
  25
  26 ::
  27
  28     $ pip install postorius
  29
  30
  31 Latest dev version
  32 ------------------
  33
  34 If you want to always be up to date with the latest development version, you
  35 should install Postorius using git:
  36
  37 ::
  38
  39     $ git clone https://gitlab.com/mailman/postorius.git
  40     $ cd postorius
  41     $ pip install -e .
  42
  43 .. note::
  44     This note only pertains to development installs and should not be used when
  45     doing production installs.
  46
  47     When setting up or running your local dev environment, you may run into some
  48     errors. You may want to consider installing mailman modules from source as
  49     changes may not yet be published to PyPI. Example usage below:
  50
  51 ::
  52
  53     $ pip install -U git+https://gitlab.com/mailman/mailmanclient.git
  54
  55 Setup your django project
  56 =========================
  57
  58 Since you have now installed the necessary packages to run Postorius, it's
  59 time to setup your Django site.
  60
  61 You can find an example project in ``example_project`` in the root of
  62 ``postorius'`` git repository.
  63
  64 Change the database setting in ``example_project/settings.py`` to
  65 your preferred database, if you want something other than SQlite.
  66
  67 .. note::
  68     Detailed information on how to use different database engines can be found
  69     in the `Django documentation`_.
  70
  71 .. _Django documentation: https://docs.djangoproject.com/en/1.9/ref/settings/#databases
  72
  73 Third, prepare the database:
  74
  75 ::
  76
  77     $ cd example_project
  78     $ python manage.py migrate
  79
  80 This will create the ``postorius.db`` file (if you are using SQLite) and will setup all the
  81 necessary db tables.
  82
  83 To create a superuser which will act as an admin account for Postorius, run the
  84 following commands::
  85
  86     $ cd example_project
  87     $ python manage.py createsuperuser
  88
  89
  90 Running the development server
  91 ==============================
  92
  93 The quickest way to run Postorius is to just start the development server:
  94
  95 ::
  96
  97     $ cd example_project
  98     $ python manage.py runserver
  99
 100
 101 .. warning::
 102     You should use the development server only locally. While it's possible to
 103     make your site publicly available using the dev server, you should never
 104     do that in a production environment.