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