install.rst 7.32 KB
Newer Older
mathieui's avatar
mathieui committed
1 2
.. _install:

mathieui's avatar
mathieui committed
3
Installing poezio
4 5
=================

6
.. warning:: Python 3.5 or above is **required**.
mathieui's avatar
mathieui committed
7
             To install it on a distribution that doesn't provide it, see :ref:`pyenv <pyenv-install>`.
8

mathieui's avatar
mathieui committed
9
poezio in the GNU/Linux distributions
10 11 12 13 14 15
-------------------------------------

As far as I know, Poezio is available in the following distributions, you just
have to install it by using the package manager of the distribution, if you're
using one of these.

mathieui's avatar
mathieui committed
16 17
- **Archlinux**: poezio_ and poezio-git_ packages are in the AUR
  (use your favourite AUR wrapper to install them)
18
- **Gentoo**:  `net-im/poezio`_
mathieui's avatar
mathieui committed
19 20 21
- **Fedora**: The stable poezio package was out of date for a long time in
  Fedora, but now thanks to Casper, there is an `up-to-date package`_ in
  the repos since F19.
22
- **Debian**: A stable package is provided since buster_ thanks to debacle.
23 24 25
- **Nix** (and **NixOS**): The last stable version of poezio is availalble in
  the unstable branch of `nixpkgs`. Use ``nix-env -f "<nixpkgs>" -iA poezio``
  to install poezio for the current user.
mathieui's avatar
mathieui committed
26
- **OpenBSD**: a poezio port_ is available
27

28
(If another distribution provides a poezio package, please tell us and we will
mathieui's avatar
mathieui committed
29
add it to the list)
30

mathieui's avatar
mathieui committed
31 32
Thank to all the maintainers who took time to make and maintain those packages!

mathieui's avatar
mathieui committed
33 34
Install from source
-------------------
35

36 37
Stable version
~~~~~~~~~~~~~~
38

mathieui's avatar
mathieui committed
39
`Stable version`_ packages are available in standalone (dependencies provided)
mathieui's avatar
mathieui committed
40
and poezio-only packages (both with prebuilt html doc for convenience).
41

mathieui's avatar
mathieui committed
42 43 44
Those versions are also available on pypi_ (using pip3, for example), and it is
recommended to install them this way if you absolutely want to **install** poezio
and your distribution provides no package.
45

46 47
Development version
~~~~~~~~~~~~~~~~~~~
48

49 50 51 52
The stable versions of poezio are more like snapshots of states of
development we deem acceptable. There is always an incentive to
use the development version, like new features, bug fixes, and more
support. Therefore, you might want to use the git version.
53 54 55

.. code-block:: bash

56
    git clone https://lab.louiz.org/poezio/poezio
57
    cd poezio
58

59 60 61
"""""""
General
"""""""
62

63
Poezio is a python3.5 (and above)-only application, so you will first need that.
64

65 66 67 68 69 70 71
Packages required for building poezio and deps:

- make
- gcc
- libidn and libidn-dev, only if you want to use cython_ (see below)
- python3-devel (or equivalent)
- python3-setuptools
72 73 74 75 76 77 78 79 80 81 82 83
- python3-pip
- python3-venv
- libffi-dev (for pycares, needed by slixmpp)
- pyasn1 and pyasn1-modules (needed by slixmpp)

On Debian, you can install the dependencies as follows:

.. code-block:: bash

    apt install python3-dev make gcc python3-setuptools python3-pip python3-venv libffi-dev
    pip3 install --user pyasn1 pyasn1-modules

84 85

Then you can run ``make`` to build it the poezio C extension module.
mathieui's avatar
mathieui committed
86 87
If you downloaded the standalone stable package, you are finished here and can skip
to :ref:`running poezio <poezio-run-label>`.
88

89
Poezio needs two libraries to run:
90

mathieui's avatar
mathieui committed
91 92
- aiodns_
- slixmpp_
93
- slixmpp can make use of cython_ to compile performance-critical modules and be faster
mathieui's avatar
mathieui committed
94 95

.. versionchanged:: 0.9
96

97

mathieui's avatar
mathieui committed
98
.. note:: We provide an ``update.sh`` script that creates a virtualenv and
mathieui's avatar
mathieui committed
99 100 101
          downloads all the required and optional dependencies inside it.
          we recommend using it with the git version of poezio, in order
          to keep everything up-to-date.
102

mathieui's avatar
mathieui committed
103 104
If you dont want to use the update script for whatever reason, install the
following dependencies by hand; otherwise, skip to the
mathieui's avatar
mathieui committed
105
:ref:`installation part <poezio-install-label>`.
106 107


mathieui's avatar
mathieui committed
108 109 110 111
""""""""
slixmpp
""""""""

112
Poezio depends on slixmpp, a non-threaded fork of the SleekXMPP library.
113 114 115

.. code-block:: bash

116
    git clone https://lab.louiz.org/poezio/slixmpp
117 118
    python3 setup.py install --user

119

mathieui's avatar
mathieui committed
120 121 122 123
""""""
aiodns
""""""

124
The aiodns library is required in order to properly resolve XMPP domains (with SRV records).
mathieui's avatar
mathieui committed
125

126 127 128

.. code-block:: bash

ge0rg's avatar
ge0rg committed
129
    pip3 install --user aiodns
mathieui's avatar
mathieui committed
130 131

This will also install pycares, which aiodns uses.
132

133

mathieui's avatar
mathieui committed
134 135 136 137 138 139 140 141 142 143 144 145
""""""""
Building
""""""""

If you dont run the ``update.sh`` script, you need to manually build the C
module used by poezio:

.. code-block:: bash

    make


146 147
.. _poezio-install-label:

148 149
Installation
~~~~~~~~~~~~
150

mathieui's avatar
mathieui committed
151 152 153
.. note::

    The update.sh + launch.sh method is the recommended way of using and upgrading
154
    the devel version of poezio. Installing should only be done with stable versions.
mathieui's avatar
mathieui committed
155
    And preferably using your distributions package manager.
mathieui's avatar
mathieui committed
156

157 158 159

If you skipped the installation of the dependencies and you only want to run
poezio without a system-wide install, do, in the :file:`poezio` directory:
160 161 162 163 164 165

.. code-block:: bash

    ./update.sh


166 167 168 169 170
.. note::

    You should probably install cython (for python3) on your system using your
    package manager, since the installation from pypi takes a long time.

171 172 173 174 175 176
.. note::

    If you want to use a custom directory for the virtualenv used by poezio,
    you can use the ``$POEZIO_VENV`` environment variable to set use
    another path (the default is :file:`poezio-venv`).

177 178 179 180 181 182 183 184 185 186 187 188
.. note::

    The python version used can be customized using the ``$POEZIO_PYTHON``
    env variable.

    If your distribution's python3 does not have a ``venv`` module, install
    the package corresponding to that module (probably ``python3-venv``).


.. versionchanged:: 0.12
    Previously there was a ``$POEZIO_VENV_COMMAND`` env variable to define
    the command. Now it is required to use ``$POEZIO_PYTHON``.
189 190


mathieui's avatar
mathieui committed
191
If you really want to install it, run as root (or sudo in ubuntu or whatever):
192 193 194

.. code-block:: bash

mathieui's avatar
mathieui committed
195
    make install
196

197

mathieui's avatar
mathieui committed
198 199 200 201 202 203 204
.. _poezio-run-label:

Running
~~~~~~~

If you didn’t install poezio, you can run it from the source directory
with:
205 206 207

.. code-block:: bash

mathieui's avatar
mathieui committed
208 209
    ./launch.sh

210

mathieui's avatar
mathieui committed
211
If you did, it should be in the ``$PATH`` as ``poezio``, so run:
212 213 214 215 216

.. code-block:: bash

    poezio

mathieui's avatar
mathieui committed
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
Docker images
-------------

poezio is available on the docker hub in the `poezio/poezio`_ repository
in which ``poezio/poezio:latest`` is the latest built git version, and
stable versions are tagged with their numbers. The image is based off
alpine linux and we tried to keep the image size to a minimum (<100MiB).

You can therefore just fetch the images with docker pull:

.. code-block:: bash

    docker pull poezio/poezio

In order to run poezio with non-temporary config and logs, and to have
mathieui's avatar
mathieui committed
232 233
the right colors, you have to share the ``TERM`` env var and some directories
that should be created beforehand:
mathieui's avatar
mathieui committed
234 235 236

.. code-block:: bash

mathieui's avatar
mathieui committed
237
    mkdir -p ~/.config/poezio ~/.local/share/poezio
mathieui's avatar
mathieui committed
238 239 240 241 242 243
    docker run -it -e TERM -v ~/.config/poezio:/home/poezio-user/.config/poezio -v ~/.local/share/poezio:/home/poezio-user/.local/share/poezio poezio/poezio


If you don’t trust images distributed on the docker hub, you can rebuild the
image from the Dockerfile at the root of the git repository.

244
.. _stable sources: https://dev.louiz.org/project/poezio/download
mathieui's avatar
mathieui committed
245 246
.. _slixmpp: https://dev.louiz.org/projects/slixmpp
.. _aiodns: https://github.com/saghul/aiodns
mathieui's avatar
mathieui committed
247 248
.. _poezio: https://aur.archlinux.org/packages/poezio/
.. _poezio-git: https://aur.archlinux.org/packages/poezio-git/
249
.. _up-to-date package: https://apps.fedoraproject.org/packages/poezio
mathieui's avatar
mathieui committed
250
.. _pypi: https://pypi.python.org/pypi/poezio
251
.. _cython: http://cython.org
mathieui's avatar
mathieui committed
252 253
.. _bgo-overlay: https://bgo.zugaina.org/
.. _port: http://ports.su/net/poezio
mathieui's avatar
mathieui committed
254
.. _poezio/poezio: https://hub.docker.com/r/poezio/poezio/
255
.. _buster: https://packages.debian.org/buster/poezio
256
.. _net-im/poezio: https://packages.gentoo.org/packages/net-im/poezio