Mercurial > libervia-backend
annotate doc/installation.rst @ 4180:b86912d3fd33
plugin IP: fix use of legacy URL + coroutine use:
An https:/salut-a-toi.org URL was used to retrieve external IP, but it's not valid
anymore, resulting in an exception. This feature is currently disabled.
Also moved several methods from legacy inline callbacks to coroutines.
author | Goffi <goffi@goffi.org> |
---|---|
date | Sat, 09 Dec 2023 14:30:54 +0100 |
parents | 3f59a2b141cc |
children | 810f2b80146b |
rev | line source |
---|---|
3022 | 1 .. _installation: |
2 | |
2946 | 3 ============ |
4 Installation | |
5 ============ | |
6 | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
7 These are the instructions to install Libervia using Python. |
3505 | 8 Note that if you are using GNU/Linux, Libervia may already be present on your distribution. |
2946 | 9 |
3505 | 10 Libervia is made of one backend, and several frontends. To use it, the first thing to do is to install the backend. |
2946 | 11 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
12 We recommand to use development version for now, until the release of 0.9. |
2946 | 13 |
14 Development version | |
15 ------------------- | |
16 | |
17 *Note for Arch users: a pkgbuild is available for your distribution on | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
18 AUR, check libervia-backend-hg (as well as other libervia-\* packages).* |
2946 | 19 |
20 You can install the latest development version using pip. You need to | |
21 have the following dependencies installed first: | |
22 | |
3260
e9ecd133773b
doc (installation): updated instructions for backend
Goffi <goffi@goffi.org>
parents:
3022
diff
changeset
|
23 - Python 3 with development headers |
3383 | 24 - Python 3 "venv", which may already be installed with Python 3 |
2946 | 25 - Mercurial |
3383 | 26 - libcairo 2 with development header |
2946 | 27 - libjpeg with development headers |
28 - libgirepository 1.0 with development headers | |
29 - libdbus-1 with development headers | |
30 - libdbus-glib-1 with development headers | |
31 - libxml2 with development headers | |
32 - libxlt2 with development headers | |
33 - D-Bus x11 tools (this doesn't needs X11, it is just needed for dbus-launch) | |
34 - cmake | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
35 - Python GPG package (and its GPG dependencies), those are needed to use all OpenPGP |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
36 related features. We need to use the system package as package version needs to match |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
37 system GPG version. |
2946 | 38 |
39 On Debian and derivatives, you can get all this with following command:: | |
40 | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
41 $ sudo apt-get install python3-dev python3-venv python3-wheel mercurial libxml2-dev libxslt-dev libcairo2-dev libjpeg-dev libgirepository1.0-dev libdbus-1-dev libdbus-glib-1-dev dbus-x11 cmake python3-gpg |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
42 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
43 Installation With pipx |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
44 ~~~~~~~~~~~~~~~~~~~~~~ |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
45 |
4113
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
46 If you have `pipx`_ installed, you can easily install the development version of the |
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
47 backend by entering the following command: |
2946 | 48 |
4113
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
49 .. code-block:: bash |
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
50 |
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
51 $ pipx install --system-site-packages hg+https://repos.goffi.org/libervia-backend#egg=libervia-backend[SVG] |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
52 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
53 Installation With Virtual Environment And pip |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
54 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
55 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
56 Alternatively, you can install a virtual environment, clone the repository, and pip |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
57 install from there. |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
58 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
59 Go in a location where you can install Libervia, for instance your home directory:: |
2946 | 60 |
61 $ cd | |
62 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
63 And enter the following commands (here we install Libervia with SVG support, which is needed to |
3260
e9ecd133773b
doc (installation): updated instructions for backend
Goffi <goffi@goffi.org>
parents:
3022
diff
changeset
|
64 display SVG avatars on some frontends):: |
2946 | 65 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
66 $ python3 -m venv --system-site-packages libervia |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
67 $ source libervia/bin/activate |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
68 $ pip install -U pip wheel |
3774
df836d6f9c8a
doc (installation): fix missing `hg clone` instructions
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
69 $ hg clone https://repos.goffi.org/libervia-backend |
df836d6f9c8a
doc (installation): fix missing `hg clone` instructions
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
70 $ cd libervia-backend |
4113
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
71 $ pip install -e . |
2946 | 72 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
73 Don't worry if you see the following message, Libervia should work anyway:: |
2946 | 74 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
75 Failed building wheel for <some_package_name> |
2946 | 76 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
77 Post Installation |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
78 ~~~~~~~~~~~~~~~~~ |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
79 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
80 After installing Libervia, you need to install the media (you may skip this if you don't |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
81 plan to use any graphical frontend):: |
2946 | 82 |
83 $ cd | |
3776
4d333f249625
doc (installation): `sat_media` is now `libervia-media`
Goffi <goffi@goffi.org>
parents:
3774
diff
changeset
|
84 $ hg clone https://repos.goffi.org/libervia-media |
2946 | 85 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
86 then, create the directory ``~/.config/libervia``:: |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
87 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
88 $ mkdir -p ~/.config/libervia |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
89 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
90 and the file ``~/.config/libervia/libervia.conf`` containing: |
2946 | 91 |
92 .. sourcecode:: cfg | |
93 | |
94 [DEFAULT] | |
3776
4d333f249625
doc (installation): `sat_media` is now `libervia-media`
Goffi <goffi@goffi.org>
parents:
3774
diff
changeset
|
95 media_dir = ~/libervia-media |
2946 | 96 |
3776
4d333f249625
doc (installation): `sat_media` is now `libervia-media`
Goffi <goffi@goffi.org>
parents:
3774
diff
changeset
|
97 Of course, replace ``~/libervia-media`` with the actual path you have used. |
2946 | 98 |
3260
e9ecd133773b
doc (installation): updated instructions for backend
Goffi <goffi@goffi.org>
parents:
3022
diff
changeset
|
99 You can check :ref:`configuration` for details |
2946 | 100 |
101 Usage | |
102 ===== | |
103 | |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
104 To launch the Libervia backend, enter:: |
2946 | 105 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
106 $ libervia-backend |
2946 | 107 |
108 …or, if you want to launch it in foreground:: | |
109 | |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
110 $ libervia-backend fg |
2946 | 111 |
112 You can stop it with:: | |
113 | |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
114 $ libervia-backend stop |
2946 | 115 |
116 To know if backend is launched or not:: | |
117 | |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
118 $ libervia-backend status |
2946 | 119 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
120 **NOTE**: if ``misc/org.libervia.Libervia.service`` is installed correctly (which should |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
121 be done during the installation), the backend is automatically launched when a frontend |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
122 needs it. |
2946 | 123 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
124 You can check that Libervia is installed correctly by trying jp (the backend need to be |
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
125 launched first, check below):: |
2946 | 126 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
127 $ li --version |
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
128 Libervia CLI 0.8.0D « La Cecília » (rev 184c66256bbc [M] (default 2021-06-09 11:35 +0200) +524) Copyright (C) 2009-2021 Jérôme Poisson, Adrien Cossa |
2946 | 129 This program comes with ABSOLUTELY NO WARRANTY; |
130 This is free software, and you are welcome to redistribute it under certain conditions. | |
131 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
132 If you have a similar output, Libervia is working. |
2946 | 133 |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
134 .. note:: |
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
135 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
136 You may see an error message indicating that D-Bus is not launched or that its |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
137 environment variable is not set, this usually happens when launching Libervia on a |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
138 server, without graphic interface like X.org or Wayland (otherwise D-Bus service should |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
139 be launched automatically). In this case please follow instructions below. |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
140 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
141 Launching D-Bus (on servers) |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
143 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
144 You can launch the D-Bus service by creating a shell script with the following content |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
145 in a file named ``dbus_launch.sh``: |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
146 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
147 .. sourcecode:: sh |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
148 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
149 #!/bin/sh |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
150 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
151 DBUS_PATH="/tmp/.dbus.`whoami`" |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
152 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
153 if [ ! -e $DBUS_PATH ]; then |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
154 dbus-launch --sh-syntax > $DBUS_PATH |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
155 chmod 400 $DBUS_PATH |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
156 fi |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
157 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
158 cat $DBUS_PATH |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
159 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
160 Then run it before the backend or frontend by entering:: |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
161 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
162 $ eval $(/path/to/dbus_launch.sh) |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
163 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
164 This will launch the D-Bus daemon if necessary, and set the appropriate environment |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
165 variable. If you use a new shell, be sure to launch the script again in an ``eval`` |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
166 statement to have the environment variable set. You can put this in your ``.zshrc`` (or |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
167 whatever you're using) to make it automatic. |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
168 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
169 If you don't want to use D-Bus, you can use another bridge, e.g. ``pb`` is a good |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
170 choice, by updating your :ref:`configuration` ``[DEFAULT]`` section with ``bridge = |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
171 pb``. |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
172 |
2946 | 173 Frontends |
174 ========= | |
175 | |
176 So far, the following frontends exist and are actively maintained: | |
177 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
178 Libervia Desktop (aka Cagou) |
2946 | 179 desktop/mobile (Android) frontend |
180 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
181 Libervia Web |
2946 | 182 the web frontend |
183 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
184 Libervia TUI (aka Primitivus) |
2946 | 185 Text User Interface |
186 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
187 Libervia CLI (aka jp or li) |
2946 | 188 Command Line Interface |
189 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
190 To launch Libervia TUI, just type:: |
2946 | 191 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
192 $ libervia-tui |
2946 | 193 |
194 then create a profile (XMPP account must already exist). | |
195 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
196 To use Libervia CLI, follow its help (``li`` is a shortcut for ``libervia-cli``):: |
2946 | 197 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
198 $ li --help |
2946 | 199 |
200 | |
201 There are some other frontends: | |
202 | |
203 Bellaciao | |
204 based on Qt, a rich desktop frontend (currently on hold) | |
205 | |
206 Wix | |
207 former desktop frontend based on WxWidgets (deprecated with version 0.6.0) | |
208 | |
209 Sententia | |
210 Emacs frontend developed by a third party (development is currently stalled) | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
211 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
212 .. _pipx: https://pypa.github.io/pipx/ |