pub-solar/matrix-docker-ansible-deploy
5
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

sync with previous repo

Browse source
This commit is contained in:
Michael Collins 2021-08-13 16:05:57 +08:00
parent 83a90f1cd1
commit 98e6cd685d
641 changed files with 43857 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1820
CHANGELOG.md Normal file
View file

File diff suppressed because it is too large Load diff

661
LICENSE Normal file
View file

@ -0,0 +1,661 @@
GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU Affero General Public License is a free, copyleft license for
software and other kinds of works, specifically designed to ensure
cooperation with the community in the case of network server software.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
our General Public Licenses are intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
Developers that use our General Public Licenses protect your rights
with two steps: (1) assert copyright on the software, and (2) offer
you this License which gives you legal permission to copy, distribute
and/or modify the software.
A secondary benefit of defending all users' freedom is that
improvements made in alternate versions of the program, if they
receive widespread use, become available for other developers to
incorporate. Many developers of free software are heartened and
encouraged by the resulting cooperation. However, in the case of
software used on network servers, this result may fail to come about.
The GNU General Public License permits making a modified version and
letting the public access it on a server without ever releasing its
source code to the public.
The GNU Affero General Public License is designed specifically to
ensure that, in such cases, the modified source code becomes available
to the community. It requires the operator of a network server to
provide the source code of the modified version running there to the
users of that server. Therefore, public use of a modified version, on
a publicly accessible server, gives the public access to the source
code of the modified version.
An older license, called the Affero General Public License and
published by Affero, was designed to accomplish similar goals. This is
a different license, not a version of the Affero GPL, but Affero has
released a new version of the Affero GPL which permits relicensing under
this license.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU Affero General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Remote Network Interaction; Use with the GNU General Public License.
Notwithstanding any other provision of this License, if you modify the
Program, your modified version must prominently offer all users
interacting with it remotely through a computer network (if your version
supports such interaction) an opportunity to receive the Corresponding
Source of your version by providing access to the Corresponding Source
from a network server at no charge, through some standard or customary
means of facilitating copying of software. This Corresponding Source
shall include the Corresponding Source for any work covered by version 3
of the GNU General Public License that is incorporated pursuant to the
following paragraph.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the work with which it is combined will remain governed by version
3 of the GNU General Public License.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU Affero General Public License from time to time. Such new versions
will be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU Affero General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU Affero General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU Affero General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If your software can interact with users remotely through a computer
network, you should also make sure that it provides a way for users to
get its source. For example, if your program is a web application, its
interface could display a "Source" link that leads users to an archive
of the code. There are many ways you could offer source, and different
solutions will be better for different programs; see section 13 for the
specific requirements.
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU AGPL, see
<https://www.gnu.org/licenses/>.

163
README.md
View file

@ -1,89 +1,142 @@
# matrix-docker-ansible-deploy
[![Support room on Matrix](https://img.shields.io/matrix/matrix-docker-ansible-deploy:devture.com.svg?label=%23matrix-docker-ansible-deploy%3Adevture.com&logo=matrix&style=for-the-badge&server_fqdn=matrix.devture.com)](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) [![donate](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/s.pantaleev/donate)
Our testing fork of https://github.com/spantaleev/matrix-docker-ansible-deploy
# Matrix (An open network for secure, decentralized communication) server setup using Ansible and Docker
## Getting started
## Purpose
To make it easy for you to get started with GitLab, here's a list of recommended next steps.
This [Ansible](https://www.ansible.com/) playbook is meant to help you run your own [Matrix](http://matrix.org/) homeserver, along with the [various services](#supported-services) related to that.
Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
That is, it lets you join the Matrix network using your own `@<username>:<your-domain>` identifier, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
## Add your files
We run all services in [Docker](https://www.docker.com/) containers (see [the container images we use](docs/container-images.md)), which lets us have a predictable and up-to-date setup, across multiple supported distros (see [prerequisites](docs/prerequisites.md)) and [architectures](docs/alternative-architectures.md) (x86/amd64 being recommended).
- [ ] [Create](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
- [ ] [Add files using the command line](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
[Installation](docs/README.md) (upgrades) and some maintenance tasks are automated using [Ansible](https://www.ansible.com/) (see [our Ansible guide](docs/ansible.md)).
```
cd existing_repo
git remote add origin https://gitlab.com/GoMatrixHosting/matrix-docker-ansible-deploy.git
git branch -M main
git push -uf origin main
```
## Integrate with your tools
## Supported services
- [ ] [Set up project integrations](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/user/project/integrations/)
Using this playbook, you can get the following services configured on your server:
## Collaborate with your team
- (optional, default) a [Synapse](https://github.com/matrix-org/synapse) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network
- [ ] [Invite team members and collaborators](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/user/project/members/)
- [ ] [Create a new merge request](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
- [ ] [Automatically close issues from merge requests](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
- [ ] [Automatically merge when pipeline succeeds](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
- (optional) [Amazon S3](https://aws.amazon.com/s3/) storage for Synapse's content repository (`media_store`) files using [Goofys](https://github.com/kahing/goofys)
## Test and Deploy
- (optional, default) [PostgreSQL](https://www.postgresql.org/) database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible.
Use the built-in continuous integration in GitLab.
- (optional, default) a [coturn](https://github.com/coturn/coturn) STUN/TURN server for WebRTC audio/video calls
- [ ] [Get started with GitLab CI/CD](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/ci/quick_start/index.html)
- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://docs.gitlab.com/ee/user/application_security/sast/)
- (optional, default) free [Let's Encrypt](https://letsencrypt.org/) SSL certificate, which secures the connection to the Synapse server and the Element web UI
***
- (optional, default) an [Element](https://app.element.io/) ([formerly Riot](https://element.io/previously-riot)) web UI, which is configured to connect to your own Synapse server by default
# Editing this README
- (optional, default) a [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server
When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://gitlab.com/-/experiment/new_project_readme_content:8733cc273e622025d22ff0078c9cffce?https://www.makeareadme.com/) for this template.
- (optional, default) an [Exim](https://www.exim.org/) mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server)
## Suggestions for a good README
Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
- (optional, default) an [nginx](http://nginx.org/) web server, listening on ports 80 and 443 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md)
## Name
Choose a self-explaining name for your project.
- (optional, advanced) the [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) REST authentication password provider module
## Description
Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
- (optional, advanced) the [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) password provider module
## Badges
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
- (optional, advanced) the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider module
- (optional, advanced) the [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) spam checker module
- (optional, advanced) the [Matrix Corporal](https://github.com/devture/matrix-corporal) reconciliator and gateway for a managed Matrix server
- (optional) the [mautrix-telegram](https://github.com/tulir/mautrix-telegram) bridge for bridging your Matrix server to [Telegram](https://telegram.org/)
- (optional) the [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) bridge for bridging your Matrix server to [WhatsApp](https://www.whatsapp.com/)
- (optional) the [mautrix-facebook](https://github.com/tulir/mautrix-facebook) bridge for bridging your Matrix server to [Facebook](https://facebook.com/)
- (optional) the [mautrix-hangouts](https://github.com/tulir/mautrix-hangouts) bridge for bridging your Matrix server to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts)
- (optional) the [mautrix-instagram](https://github.com/tulir/mautrix-instagram) bridge for bridging your Matrix server to [Instagram](https://instagram.com/)
- (optional) the [mautrix-signal](https://github.com/tulir/mautrix-signal) bridge for bridging your Matrix server to [Signal](https://www.signal.org/)
- (optional) the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge for bridging your Matrix server to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat)
- (optional) the [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) bridge for bridging your Matrix server to [Discord](https://discordapp.com/)
- (optional) the [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) bridge for bridging your Matrix server to [Slack](https://slack.com/)
- (optional) the [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.)
- (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS - see [docs/configuring-playbook-bridge-matrix-bridge-sms.md](docs/configuring-playbook-bridge-matrix-bridge-sms.md) for setup documentation
- (optional) the [Heisenbridge](https://github.com/hifi/heisenbridge) for bridging your Matrix server to IRC bouncer-style - see [docs/configuring-playbook-bridge-heisenbridge.md](docs/configuring-playbook-bridge-heisenbridge.md) for setup documentation
- (optional) the [mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-mx-puppet-skype.md](docs/configuring-playbook-bridge-mx-puppet-skype.md) for setup documentation
- (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation
- (optional) the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-instagram.md](docs/configuring-playbook-bridge-mx-puppet-instagram.md) for setup documentation
- (optional) the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge for Twitter-DMs ([Twitter](https://twitter.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-twitter.md](docs/configuring-playbook-bridge-mx-puppet-twitter.md) for setup documentation
- (optional) the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge for [Discord](https://discordapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-discord.md](docs/configuring-playbook-bridge-mx-puppet-discord.md) for setup documentation
- (optional) the [mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) bridge for [GroupMe](https://groupme.com/) - see [docs/configuring-playbook-bridge-mx-puppet-groupme.md](docs/configuring-playbook-bridge-mx-puppet-groupme.md) for setup documentation
- (optional) the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge for [Steam](https://steamapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-steam.md](docs/configuring-playbook-bridge-mx-puppet-steam.md) for setup documentation
- (optional) [Email2Matrix](https://github.com/devture/email2matrix) for relaying email messages to Matrix rooms - see [docs/configuring-playbook-email2matrix.md](docs/configuring-playbook-email2matrix.md) for setup documentation
- (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients - see [docs/configuring-playbook-dimension.md](docs/configuring-playbook-dimension.md) for setup documentation
- (optional) [Etherpad](https://etherpad.org), an open source collaborative text editor - see [docs/configuring-playbook-etherpad.md](docs/configuring-playbook-etherpad.md) for setup documentation
- (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform - see [docs/configuring-playbook-jitsi.md](docs/configuring-playbook-jitsi.md) for setup documentation
- (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms - see [docs/configuring-playbook-bot-matrix-reminder-bot.md](docs/configuring-playbook-bot-matrix-reminder-bot.md) for setup documentation
- (optional) [Go-NEB](https://github.com/matrix-org/go-neb) multi functional bot written in Go - see [docs/configuring-playbook-bot-go-neb.md](docs/configuring-playbook-bot-go-neb.md) for setup documentation
- (optional) [Mjolnir](https://github.com/matrix-org/mjolnir), a moderation tool for Matrix - see [docs/configuring-playbook-bot-mjolnir.md](docs/configuring-playbook-bot-mjolnir.md) for setup documentation
- (optional) [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin), a web UI tool for administrating users and rooms on your Matrix server - see [docs/configuring-playbook-synapse-admin.md](docs/configuring-playbook-synapse-admin.md) for setup documentation
- (optional) [matrix-registration](https://github.com/ZerataX/matrix-registration), a simple python application to have a token based matrix registration - see [docs/configuring-playbook-matrix-registration.md](docs/configuring-playbook-matrix-registration.md) for setup documentation
- (optional) the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI - see [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) for setup documentation
- (optional) the [Sygnal](https://github.com/matrix-org/sygnal) push gateway - see [Setting up the Sygnal push gateway](docs/configuring-playbook-sygnal.md) for setup documentation
- (optional) the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client - see [docs/configuring-playbook-client-hydrogen.md](docs/configuring-playbook-client-hydrogen.md) for setup documentation
Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
**Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need.
Sticking with the defaults (which install a subset of the above components) is the best choice, especially for a new installation.
You can always re-run the playbook later to add or remove components.
## Visuals
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
## Installation
Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
## Usage
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
To configure and install Matrix on your own server, follow the [README in the docs/ directory](docs/README.md).
## Changes
This playbook evolves over time, sometimes with backward-incompatible changes.
When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up with what's new.
## Support
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
## Roadmap
If you have ideas for releases in the future, it is a good idea to list them in the README.
- Matrix room: [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com)
## Contributing
State if you are open to contributions and what your requirements are for accepting them.
- IRC channel: `#matrix-docker-ansible-deploy` on the [Libera Chat](https://libera.chat/) IRC network (irc.libera.chat:6697)
For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
- GitHub issues: [spantaleev/matrix-docker-ansible-deploy/issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues)
You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
## Authors and acknowledgment
Show your appreciation to those who have contributed to the project.
## Services by the community
## License
For open source projects, say how it is licensed.
## Project status
If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
- [etke.cc](https://etke.cc) - matrix-docker-ansible-deploy and system stuff "as a service". That service will create your matrix homeserver on your domain and server (doesn't matter if it's cloud provider or on an old laptop in the corner of your room), (optional) maintains it (server's system updates, cleanup, security adjustments, tuning, etc.; matrix homeserver updates & maintenance) and (optional) provide full-featured email service for your domain
- [GoMatrixHosting](https://gomatrixhosting.com) - matrix-docker-ansible-deploy "as a service" with [Ansible AWX](https://github.com/ansible/awx). Members can be assigned a server from DigitalOcean, or they can connect their on-premises server. This AWX system can manage the updates, configuration, import and export, backups, and monitoring on its own. For more information [see our GitLab group](https://gitlab.com/GoMatrixHosting) or come [visit us on Matrix](https://matrix.to/#/#general:gomatrixhosting.com).

6
ansible.cfg Normal file
View file

@ -0,0 +1,6 @@
[defaults]
retry_files_enabled = False
stdout_callback = yaml
[connection]
pipelining = True

39
docs/README.md Normal file
View file

@ -0,0 +1,39 @@
# Table of Contents
- [FAQ](faq.md) - lots of questions and answers. Jump to [Prerequisites](prerequisites.md) to avoid reading too much and to just start a guided installation.
- [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook
- [Configuring your DNS server](configuring-dns.md)
- [Getting this playbook's source code](getting-the-playbook.md)
- [Configuring the playbook](configuring-playbook.md)
- [Installing](installing.md)
- **Importing data from another server installation**
- [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)
- [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)
- [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
- [Registering users](registering-users.md)
- [Updating users passwords](updating-users-passwords.md)
- [Configuring service discovery via .well-known](configuring-well-known.md)
- [Maintenance / checking if services work](maintenance-checking-services.md)
- [Maintenance / upgrading services](maintenance-upgrading-services.md)
- [Maintenance / Synapse](maintenance-synapse.md)
- [Maintenance / PostgreSQL](maintenance-postgres.md)
- [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)
- [Uninstalling](uninstalling.md)

26
docs/alternative-architectures.md Normal file
View file

@ -0,0 +1,26 @@
# Alternative architectures
As stated in the [Prerequisites](prerequisites.md), currently only `x86_64` is fully supported. However, it is possible to set the target architecture, and some tools can be built on the host or other measures can be used.
To that end add the following variable to your `vars.yaml` file:
```yaml
matrix_architecture: <your-matrix-server-architecture>
```
Currently supported architectures are the following:
- `amd64` (the default)
- `arm64`
- `arm32`
so for the Raspberry Pi, the following should be in your `vars.yaml` file:
```yaml
matrix_architecture: "arm32"
```
## Implementation details
For `amd64`, prebuilt container images (see the [container images we use](container-images.md)) are used everywhere, because all images are available for this architecture.
For other architectures, components which have a prebuilt image make use of it. If the component is not available for the specific architecture, [self-building](self-building.md) will be used. Not all components support self-building though, so your mileage may vary.

73
docs/ansible.md Normal file
View file

@ -0,0 +1,73 @@
# Running this playbook
This playbook is meant to be run using [Ansible](https://www.ansible.com/).
Ansible typically runs on your local computer and carries out tasks on a remote server.
If your local computer cannot run Ansible, you can also run Ansible on some server somewhere (including the server you wish to install to).
## Supported Ansible versions
Ansible 2.7.1 or newer is required ([last discussion about Ansible versions](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/743)).
Note: Ubuntu 20.04 ships with Ansible 2.9.6 which is a buggy version (see this [bug](https://bugs.launchpad.net/ubuntu/+source/ansible/+bug/1880359)), which can't be used in combination with a host running new systemd (more details in [#517](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/517), [#669](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/669)). If this problem affects you, you can: avoid running Ubuntu 20.04 on your host; run Ansible from another machine targeting your host; or try to upgrade to a newer Ansible version (see below).
## Checking your Ansible version
In most cases, you won't need to worry about the Ansible version.
The playbook will try to detect it and tell you if you're on an unsupported version.
To manually check which version of Ansible you're on, run: `ansible --version`.
If you're on an old version of Ansible, you should [upgrade Ansible to a newer version](#upgrading-ansible) or [use Ansible via Docker](#using-ansible-via-docker).
## Upgrading Ansible
Depending on your distribution, you may be able to upgrade Ansible in a few different ways:
- by using an additional repository (PPA, etc.), which provides newer Ansible versions. See instructions for [CentOS](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-rhel-centos-or-fedora), [Debian](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-debian), or [Ubuntu](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-ubuntu) on the Ansible website.
- by removing the Ansible package (`yum remove ansible` or `apt-get remove ansible`) and installing via [pip](https://pip.pypa.io/en/stable/installing/) (`pip install ansible`).
If using the `pip` method, do note that the `ansible-playbook` binary may not be on the `$PATH` (https://linuxconfig.org/linux-path-environment-variable), but in some more special location like `/usr/local/bin/ansible-playbook`. You may need to invoke it using the full path.
**Note**: Both of the above methods are a bad way to run system software such as Ansible.
If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software.
## Using Ansible via Docker
Alternatively, you can run Ansible on your computer from inside a Docker container (powered by the [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
Here's a sample command to get you started (run this from the playbook's directory):
```bash
docker run -it --rm \
-w /work \
-v `pwd`:/work \
-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
--entrypoint=/bin/sh \
docker.io/devture/ansible:2.9.14-r0
```
The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`).
If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that part.
Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container.
The `/work` directory contains the playbook's code.
You can execute `ansible-playbook` commands as per normal now.
### If you don't use SSH keys for authentication
If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`).
To authenticate at your server using a password, you need to add a package. So, when you are in the shell of the ansible docker container (the previously used `docker run -it ...` command), run:
```bash
apk add sshpass
```
Then, to be asked for the password whenever running an `ansible-playbook` command add `--ask-pass` to the arguments of the command.

44
docs/configuring-awx-system.md Normal file
View file

@ -0,0 +1,44 @@
# Configuring AWX System (optional)
An AWX setup for managing multiple Matrix servers.
This section is used in an AWX system that can create and manage multiple [Matrix](http://matrix.org/) servers. You can issue members an AWX login to their own 'organisation', which they can use to manage/configure 1 to N servers.
Members can be assigned a server from Digitalocean, or they can connect their own on-premises server. This script is free to use in a commercial context with the 'MemberPress Plus' and 'WP Oauth Sever' addons. It can also be run in a non-commercial context.
The AWX system is arranged into 'members' each with their own 'subscriptions'. After creating a subscription the user enters the 'provision stage' where they defined the URLs they will use, the servers location and whether or not there's already a website at the base domain. They then proceed onto the 'deploy stage' where they can configure their Matrix server.
This system can manage the updates, configuration, import and export, backups and monitoring on its own. It is an extension of the popular deploy script [spantaleev/matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy).
## Other Required Playbooks
The following repositories allow you to copy and use this setup:
[Create AWX System](https://gitlab.com/GoMatrixHosting/create-awx-system) - Creates and configures the AWX system for you.
[Ansible Create Delete Subscription Membership](https://gitlab.com/GoMatrixHosting/ansible-create-delete-subscription-membership) - Used by the AWX system to create memberships and subscriptions. Also includes other administrative playbooks for updates, backups and restoring servers.
[Ansible Provision Server](https://gitlab.com/GoMatrixHosting/ansible-provision-server) - Used by AWX members to perform initial configuration of their DigitalOcean or On-Premises server.
## Testing Fork For This Playbook
Updates to this section are trailed here:
[GoMatrixHosting Matrix Docker Ansible Deploy](https://gitlab.com/GoMatrixHosting/gomatrixhosting-matrix-docker-ansible-deploy)
## Does I need an AWX setup to use this? How do I configure it?
Yes, you'll need to configure an AWX instance, the [Create AWX System](https://gitlab.com/GoMatrixHosting/create-awx-system) repository makes it easy to do. Just follow the steps listed in ['/docs/Installation_AWX.md' of that repository](https://gitlab.com/GoMatrixHosting/create-awx-system/-/blob/master/docs/Installation_AWX.md).
For simpler installation steps you can use to get started with this system, check out our minimal installation guide at ['/doc/Installation_Minimal_AWX.md of that repository'](https://gitlab.com/GoMatrixHosting/create-awx-system/-/blob/master/docs/Installation_Minimal_AWX.md).
## Does I need a front-end WordPress site? And a DigitalOcean account?
You do not need a front-end WordPress site or any of the mentioned WordPress plugins to use this setup. It can be run on it's own in a non-commercial context.
You also don't need a DigitalOcean account, but this will limit you to only being able to connect 'On-Premises' servers.

23
docs/configuring-captcha.md Normal file
View file

@ -0,0 +1,23 @@
(Adapted from the [upstream project](https://github.com/matrix-org/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
# Overview
Captcha can be enabled for this home server. This file explains how to do that.
The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google.
## Getting keys
Requires a site/secret key pair from:
<http://www.google.com/recaptcha/admin>
Must be a reCAPTCHA **v2** key using the "I'm not a robot" Checkbox option
## Setting ReCaptcha Keys
Once registered as above, set the following values:
```yaml
matrix_synapse_enable_registration_captcha: true
matrix_synapse_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_synapse_recaptcha_private_key: 'YOUR_SECRET_KEY'
```

71
docs/configuring-dns.md Normal file
View file

@ -0,0 +1,71 @@
# Configuring your DNS server
To set up Matrix on your domain, you'd need to do some DNS configuration.
To use an identifier like `@<username>:<your-domain>`, you don't actually need
to install anything on the actual `<your-domain>` server.
You do, however need to instruct the Matrix network that Matrix services for `<your-domain>` are delegated
over to `matrix.<your-domain>`.
As we discuss in [Server Delegation](howto-server-delegation.md), there are 2 different ways to set up such delegation:
- either by serving a `https://<your-domain>/.well-known/matrix/server` file (from the base domain!)
- or by using a `_matrix._tcp` DNS SRV record (don't confuse this with the `_matrix-identity._tcp` SRV record described below)
This playbook mostly discusses the well-known file method, because it's easier to manage with regard to certificates.
If you decide to go with the alternative method ([Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced)), please be aware that the general flow that this playbook guides you through may not match what you need to do.
## DNS settings for services enabled by default
| Type | Host | Priority | Weight | Port | Target |
| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
| A | `matrix` | - | - | - | `matrix-server-IP` |
| CNAME | `element` | - | - | - | `matrix.<your-domain>` |
Be mindful as to how long it will take for the DNS records to propagate.
If you are using Cloudflare DNS, make sure to disable the proxy and set all records to `DNS only`. Otherwise, fetching certificates will fail.
## DNS settings for optional services/features
| Type | Host | Priority | Weight | Port | Target |
| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
| SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.<your-domain>` |
| CNAME | `dimension` | - | - | - | `matrix.<your-domain>` |
| CNAME | `jitsi` | - | - | - | `matrix.<your-domain>` |
| CNAME | `stats` | - | - | - | `matrix.<your-domain>` |
| CNAME | `goneb` | - | - | - | `matrix.<your-domain>` |
| CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
## Subdomains setup
As the table above illustrates, you need to create 2 subdomains (`matrix.<your-domain>` and `element.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` record is fine).
The `element.<your-domain>` subdomain may be necessary, because this playbook installs the [Element](https://github.com/vector-im/element-web) web client for you.
If you'd rather instruct the playbook not to install Element (`matrix_client_element_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `element.<your-domain>` DNS record.
The `dimension.<your-domain>` subdomain may be necessary, because this playbook could install the [Dimension integrations manager](http://dimension.t2bot.io/) for you. Dimension installation is disabled by default, because it's only possible to install it after the other Matrix services are working (see [Setting up Dimension](configuring-playbook-dimension.md) later). If you do not wish to set up Dimension, feel free to skip the `dimension.<your-domain>` DNS record.
The `jitsi.<your-domain>` subdomain may be necessary, because this playbook could install the [Jitsi video-conferencing platform](https://jitsi.org/) for you. Jitsi installation is disabled by default, because it may be heavy and is not a core required component. To learn how to install it, see our [Jitsi](configuring-playbook-jitsi.md) guide. If you do not wish to set up Jitsi, feel free to skip the `jitsi.<your-domain>` DNS record.
The `stats.<your-domain>` subdomain may be necessary, because this playbook could install [Grafana](https://grafana.com/) and setup performance metrics for you. Grafana installation is disabled by default, it is not a core required component. To learn how to install it, see our [metrics and graphs guide](configuring-playbook-prometheus-grafana.md). If you do not wish to set up Grafana, feel free to skip the `stats.<your-domain>` DNS record. It is possible to install Prometheus without installing Grafana, this would also not require the `stats.<your-domain>` subdomain.
The `goneb.<your-domain>` subdomain may be necessary, because this playbook could install the [Go-NEB](https://github.com/matrix-org/go-neb) bot. The installation of Go-NEB is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Go-NEB guide](configuring-playbook-bot-go-neb.md). If you do not wish to set up Go-NEB, feel free to skip the `goneb.<your-domain>` DNS record.
The `sygnal.<your-domain>` subdomain may be necessary, because this playbook could install the [Sygnal](https://github.com/matrix-org/sygnal) push gateway. The installation of Sygnal is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Sygnal guide](configuring-playbook-sygnal.md). If you do not wish to set up Sygnal (you probably don't, unless you're also developing/building your own Matrix apps), feel free to skip the `sygnal.<your-domain>` DNS record.
The `hydrogen.<your-domain>` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client. The installation of Hydrogen is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Hydrogen guide](configuring-playbook-client-hydrogen.md). If you do not wish to set up Hydrogen, feel free to skip the `hydrogen.<your-domain>` DNS record.
## `_matrix-identity._tcp` SRV record setup
To make the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server (which this playbook installs for you) enable its federation features, set up an SRV record that looks like this:
- Name: `_matrix-identity._tcp` (use this text as-is)
- Content: `10 0 443 matrix.<your-domain>` (replace `<your-domain>` with your own)
This is an optional feature. See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.
Note: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
When you're done with the DNS configuration and ready to proceed, continue with [Getting the playbook](getting-the-playbook.md).

52
docs/configuring-playbook-base-domain-serving.md Normal file
View file

@ -0,0 +1,52 @@
# Serving the base domain
This playbook sets up services on your Matrix server (`matrix.DOMAIN`).
To have this server officially be responsible for Matrix services for the base domain (`DOMAIN`), you need to set up [Server Delegation](howto-server-delegation.md).
This is normally done by [configuring well-known](configuring-well-known.md) files on the base domain.
People who don't have a separate server to dedicate to the base domain have trouble arranging this.
Usually, there are 2 options:
- either get a separate server for the base domain, just for serving the files necessary for [Server Delegation via a well-known file](howto-server-delegation.md#server-delegation-via-a-well-known-file)
- or, arrange for the Matrix server to serve the base domain. This either involves you [using your own webserver](configuring-playbook-own-webserver.md) or making the integrated webserver (`matrix-nginx-proxy`) serve the base domain for you.
This documentation page tells you how to do the latter. With some easy changes, we make it possible to serve the base domain from the Matrix server via the integrated webserver (`matrix-nginx-proxy`).
Just **adjust your DNS records**, so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then use the following configuration**:
```yaml
matrix_nginx_proxy_base_domain_serving_enabled: true
```
Doing this, the playbook will:
- obtain an SSL certificate for the base domain, just like it does for all other domains (see [how we handle SSL certificates](configuring-playbook-ssl-certificates.md))
- serve the `/.well-known/matrix/*` files which are necessary for [Federation Server Discovery](configuring-well-known.md#introduction-to-client-server-discovery) (also see [Server Delegation](howto-server-delegation.md)) and [Client-Server discovery](configuring-well-known.md#introduction-to-client-server-discovery)
- serve a simple homepage at `https://DOMAIN` with content `Hello from DOMAIN` (configurable via the `matrix_nginx_proxy_base_domain_homepage_template` variable). You can also [serve a more complicated static website](#serving-a-static-website-at-the-base-domain).
## Serving a static website at the base domain
By default, when "serving the base domain" is enabled, the playbook hosts a simple `index.html` webpage in `/matrix/nginx-proxy/data/matrix-domain`.
The content of this page is taken from the `matrix_nginx_proxy_base_domain_homepage_template` variable.
If you'd like to host your own static website (more than a single `index.html` page) at the base domain, you can disable the creation of this default `index.html` page like this:
```yaml
matrix_nginx_proxy_base_domain_homepage_enabled: false
```
With this configuration, Ansible will no longer mess around with the `/matrix/nginx-proxy/data/matrix-domain/index.html` file.
You are then free to upload any static website files to `/matrix/nginx-proxy/data/matrix-domain` and they will get served at the base domain.
## Serving a more complicated website at the base domain
If you'd like to serve an even more complicated (dynamic) website from the Matrix server, relying on the playbook to serve the base domain is not the best choice.
Instead, we recommend that you switch to [using your own webserver](configuring-playbook-own-webserver.md) (preferrably nginx). You can then make that webserver host anything you wish, and still easily plug in Matrix services into it.

226
docs/configuring-playbook-bot-go-neb.md Normal file
View file

@ -0,0 +1,226 @@
# Setting up Go-NEB (optional)
The playbook can install and configure [Go-NEB](https://github.com/matrix-org/go-neb) for you.
Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.
See the project's [documentation](https://github.com/matrix-org/go-neb) to learn what it does and why it might be useful to you.
## Registering the bot user
The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver.
You **need to register the bot user manually** before setting up the bot.
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
## Getting an access token
If you use curl, you can get an access token like this:
```
curl -X POST --header 'Content-Type: application/json' -d '{
"identifier": { "type": "m.id.user", "user": "bot.go-neb" },
"password": "a strong password",
"type": "m.login.password"
}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
```
Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token), but doing so might lead to decryption problems. That warning comes from [here](https://github.com/matrix-org/go-neb#quick-start).
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
matrix_bot_go_neb_enabled: true
# You need at least 1 client.
# Use the access token you obtained in the step above.
matrix_bot_go_neb_clients:
- UserID: "@goneb:{{ matrix_domain }}"
AccessToken: "MDASDASJDIASDJASDAFGFRGER"
DeviceID: "DEVICE1"
HomeserverURL: "{{ matrix_homeserver_container_url }}"
Sync: true
AutoJoinRooms: true
DisplayName: "Go-NEB!"
AcceptVerificationFromUsers: [":{{ matrix_domain }}"]
- UserID: "@another_goneb:{{ matrix_domain }}"
AccessToken: "MDASDASJDIASDJASDAFGFRGER"
DeviceID: "DEVICE2"
HomeserverURL: "{{ matrix_homeserver_container_url }}"
Sync: false
AutoJoinRooms: false
DisplayName: "Go-NEB!"
AcceptVerificationFromUsers: ["^@admin:{{ matrix_domain }}"]
# Optional, for use with the github_cmd, github_webhooks or jira services
matrix_bot_go_neb_realms:
- ID: "github_realm"
Type: "github"
Config: {} # No need for client ID or Secret as Go-NEB isn't generating OAuth URLs
# Optional. The list of *authenticated* sessions which Go-NEB is aware of.
matrix_bot_go_neb_sessions:
- SessionID: "your_github_session"
RealmID: "github_realm"
UserID: "@YOUR_USER_ID:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
Config:
# Populate these fields by generating a "Personal Access Token" on github.com
AccessToken: "YOUR_GITHUB_ACCESS_TOKEN"
Scopes: "admin:org_hook,admin:repo_hook,repo,user"
# The list of services which Go-NEB is aware of.
# Delete or modify this list as appropriate.
# See the docs for /configureService for the full list of options:
# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest
# You need at least 1 service.
matrix_bot_go_neb_services:
- ID: "echo_service"
Type: "echo"
UserID: "@goneb:{{ matrix_domain }}"
Config: {}
# Can be obtained from https://developers.giphy.com/dashboard/
- ID: "giphy_service"
Type: "giphy"
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
Config:
api_key: "qwg4672vsuyfsfe"
use_downsized: false
# This service has been dead for over a year :/
- ID: "guggy_service"
Type: "guggy"
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
Config:
api_key: "2356saaqfhgfe"
# API Key via https://developers.google.com/custom-search/v1/introduction
# CX via http://www.google.com/cse/manage/all
# https://stackoverflow.com/questions/6562125/getting-a-cx-id-for-custom-search-google-api-python
# 'Search the entire web' and 'Image search' enabled for best results
- ID: "google_service"
Type: "google"
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
Config:
api_key: "AIzaSyA4FD39m9"
cx: "AIASDFWSRRtrtr"
# Get a key via https://api.imgur.com/oauth2/addclient
# Select "oauth2 without callback url"
- ID: "imgur_service"
Type: "imgur"
UserID: "@imgur:{{ matrix_domain }}" # requires a Syncing client
Config:
client_id: "AIzaSyA4FD39m9"
client_secret: "somesecret"
- ID: "wikipedia_service"
Type: "wikipedia"
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
Config:
- ID: "rss_service"
Type: "rssbot"
UserID: "@another_goneb:{{ matrix_domain }}"
Config:
feeds:
"http://lorem-rss.herokuapp.com/feed?unit=second&interval=60":
rooms: ["!qmElAGdFYCHoCJuaNt:{{ matrix_domain }}"]
must_include:
author:
- author1
description:
- lorem
- ipsum
must_not_include:
title:
- Lorem
- Ipsum
- ID: "github_cmd_service"
Type: "github"
UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
Config:
RealmID: "github_realm"
# Make sure your BASE_URL can be accessed by Github!
- ID: "github_webhook_service"
Type: "github-webhook"
UserID: "@another_goneb:{{ matrix_domain }}"
Config:
RealmID: "github_realm"
ClientUserID: "@YOUR_USER_ID:{{ matrix_domain }}" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
Rooms:
"!someroom:id":
Repos:
"matrix-org/synapse":
Events: ["push", "issues"]
"matrix-org/dendron":
Events: ["pull_request"]
"!anotherroom:id":
Repos:
"matrix-org/synapse":
Events: ["push", "issues"]
"matrix-org/dendron":
Events: ["pull_request"]
- ID: "slackapi_service"
Type: "slackapi"
UserID: "@slackapi:{{ matrix_domain }}"
Config:
Hooks:
"hook1":
RoomID: "!someroom:id"
MessageType: "m.text" # default is m.text
- ID: "alertmanager_service"
Type: "alertmanager"
UserID: "@alertmanager:{{ matrix_domain }}"
Config:
# This is for information purposes only. It should point to Go-NEB path as follows:
# `/services/hooks/<base64 encoded service ID>`
# Where in this case "service ID" is "alertmanager_service"
# Make sure your BASE_URL can be accessed by the Alertmanager instance!
webhook_url: "http://localhost/services/hooks/YWxlcnRtYW5hZ2VyX3NlcnZpY2U"
# Each room will get the notification with the alert rendered with the given template
rooms:
"!someroomid:domain.tld":
text_template: "{{range .Alerts -}} [{{ .Status }}] {{index .Labels \"alertname\" }}: {{index .Annotations \"description\"}} {{ end -}}"
html_template: "{{range .Alerts -}} {{ $severity := index .Labels \"severity\" }} {{ if eq .Status \"firing\" }} {{ if eq $severity \"critical\"}} <font color='red'><b>[FIRING - CRITICAL]</b></font> {{ else if eq $severity \"warning\"}} <font color='orange'><b>[FIRING - WARNING]</b></font> {{ else }} <b>[FIRING - {{ $severity }}]</b> {{ end }} {{ else }} <font color='green'><b>[RESOLVED]</b></font> {{ end }} {{ index .Labels \"alertname\"}} : {{ index .Annotations \"description\"}} <a href=\"{{ .GeneratorURL }}\">source</a><br/>{{end -}}"
msg_type: "m.text" # Must be either `m.text` or `m.notice`
```
## Installing
Don't forget to add `goneb.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
To use the bot, invite it to any existing Matrix room (`/invite @whatever_you_chose:DOMAIN` where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain, make sure you have permission from the room owner if that's not you).
Basic usage is like this: `!echo hi` or `!imgur puppies` or `!giphy matrix`
If you enabled the github_cmd service you can get the supported commands via `!github help`
You can also refer to the upstream [Documentation](https://github.com/matrix-org/go-neb).

59
docs/configuring-playbook-bot-matrix-reminder-bot.md Normal file
View file

@ -0,0 +1,59 @@
# Setting up matrix-reminder-bot (optional)
The playbook can install and configure [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for you.
It's a bot you can use to **schedule one-off & recurring reminders and alarms**.
See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage) to learn what it does and why it might be useful to you.
## Registering the bot user
By default, the playbook will set up the bot with a username like this: `@bot.matrix-reminder-bot:DOMAIN`.
(to use a different username, adjust the `matrix_bot_matrix_reminder_bot_matrix_user_id_localpart` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-reminder-bot password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_matrix_reminder_bot_enabled: true
# Adjust this to whatever password you chose when registering the bot user
matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT
# Adjust this to your timezone
matrix_bot_matrix_reminder_bot_reminders_timezone: Europe/London
```
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
To use the bot, start a chat with `@bot.matrix-reminder-bot:DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You can also add the bot to any existing Matrix room (`/invite @bot.matrix-reminder-bot:DOMAIN`).
Basic usage is like this: `!remindme in 2 minutes; This is a test`
Send `!help commands` to the room to see the bot's help menu for additional commands.
You can also refer to the upstream [Usage documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage).

132
docs/configuring-playbook-bot-mjolnir.md Normal file
View file

@ -0,0 +1,132 @@
# Setting up Mjolnir (optional)
The playbook can install and configure the [Mjolnir](https://github.com/matrix-org/mjolnir) moderation bot for you.
See the project's [documentation](https://github.com/matrix-org/mjolnir) to learn what it does and why it might be useful to you.
## 1. Register the bot account
The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
You **need to register the bot user manually** before setting up the bot.
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.mjolnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
If you would like Mjolnir to be able to deactivate users, move aliases, shutdown rooms, etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
## 2. Get an access token
If you use curl, you can get an access token like this:
```
curl -X POST --header 'Content-Type: application/json' -d '{
"identifier": { "type": "m.id.user", "user": "bot.mjolnir" },
"password": "PASSWORD_FOR_THE_BOT",
"type": "m.login.password"
}' 'https://matrix.DOMAIN/_matrix/client/r0/login'
```
Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token).
## 3. Make sure the account is free from rate limiting
You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. [Currently there is no Synapse config option for this](https://github.com/matrix-org/synapse/issues/6286) so you have to manually edit the Synapse database. Manually editing the Synapse database is rarely a good idea but in this case it is required. Please ask for help if you are uncomfortable with these steps.
1. Copy the statement below into a text editor.
```
INSERT INTO ratelimit_override VALUES ('@bot.mjolnir:DOMAIN', 0, 0);
```
1. Change the username (`@bot.mjolnir:DOMAIN`) to the username you used when you registered the bot's account. You must change `DOMAIN` to your server's domain.
1. Get a database terminal by following these steps: [maintenance-postgres.md#getting-a-database-terminal](maintenance-postgres.md#getting-a-database-terminal)
1. Connect to Synapse's database by typing `\connect synapse` into the database terminal
1. Paste in the `INSERT INTO` command that you edited and press enter.
You can run `SELECT * FROM ratelimit_override;` to see if it worked. If the output looks like this:
```
user_id | messages_per_second | burst_count
-----------------------+---------------------+-------------
@bot.mjolnir:raim.ist | 0 | 0`
```
then you did it correctly.
## 4. Create a management room
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room. The room must be unencrypted since the playbook does not support installing Pantalaimon yet.
Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element you can do this by going to the room's settings, clicking Advanced, and then coping the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:DOMAIN`.
Finally invite the `@bot.mjolnir:DOMAIN` account you created earlier into the room.
## 5. Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with the your own values.
```yaml
matrix_bot_mjolnir_enabled: true
matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
```
## 6. Adding mjolnir synapse antispam module (optional)
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled: true
matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_invites: true
matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_messages: false
matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_usernames: false
matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
```
## 7. Installing
After configuring the playbook, run the [installation](installing.md) command:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
You can refer to the upstream [documentation](https://github.com/matrix-org/mjolnir) for additional ways to use and configure mjolnir. Check out their [quickstart guide](https://github.com/matrix-org/mjolnir#quickstart-guide) for some basic commands you can give to the bot.
You can configure additional options by adding the `matrix_bot_mjolnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file.
For example to change mjolnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file.
```yaml
matrix_bot_mjolnir_configuration_extension_yaml: |
# Your custom YAML configuration goes here.
# This configuration extends the default starting configuration (`matrix_bot_mjolnir_configuration_yaml`).
#
# You can override individual variables from the default configuration, or introduce new ones.
#
# If you need something more special, you can take full control by
# completely redefining `matrix_bot_mjolnir_configuration_yaml`.
recordIgnoredInvites: true
```

53
docs/configuring-playbook-bridge-appservice-discord.md Normal file
View file

@ -0,0 +1,53 @@
# Setting up Appservice Discord (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) bridge supported by the playbook.
The playbook can install and configure [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) for you.
See the project's [documentation](https://github.com/Half-Shot/matrix-appservice-discord/blob/master/README.md) to learn what it does and why it might be useful to you.
## Setup Instructions
Instructions loosely based on [this](https://github.com/Half-Shot/matrix-appservice-discord#setting-up).
1. Create a Discord Application [here](https://discordapp.com/developers/applications).
2. Retrieve Client ID.
3. Create a bot from the Bot tab and retrieve the Bot token.
4. Enable the bridge with the following configuration in your `vars.yml` file:
```yaml
matrix_appservice_discord_enabled: true
matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
```
5. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
6. Retrieve Discord invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).
7. Invite the Bot to Discord servers you wish to bridge. Administrator permission is recommended.
8. Room addresses follow this syntax: `#_discord_guildid_channelid`. You can easily find the guild and channel ids by logging into Discord in a browser and opening the desired channel. The URL will have this format: `discordapp.com/channels/guild_id/channel_id`. Once you have figured out the appropriate room addrss, you can join by doing `/join #_discord_guildid_channelid` in your Matrix client.
Other configuration options are available via the `matrix_appservice_discord_configuration_extension_yaml` variable.
## Getting Administrator access in a room
By default, you won't have Administrator access in rooms created by the bridge.
To [adjust room access privileges](#adjusting-room-access-privileges) or do various other things (change the room name subsequently, etc.), you'd wish to become an Administrator.
There's the Discord bridge's guide for [setting privileges on bridge managed rooms](https://github.com/Half-Shot/matrix-appservice-discord/blob/master/docs/howto.md#set-privileges-on-bridge-managed-rooms). To do the same with our container setup, run the following command on the server:
```sh
docker exec -it matrix-appservice-discord \
/bin/sh -c 'cp /cfg/registration.yaml /tmp/discord-registration.yaml && cd /tmp && node /build/tools/adminme.js -c /cfg/config.yaml -m "!ROOM_ID:SERVER" -u "@USER:SERVER" -p 100'
```
## Adjusting room access privileges
All rooms created by the bridge are **listed publicly** in your server's directory and **joinable by everyone** by default.
To get more control of them, [make yourself a room Administrator](#getting-administrator-access-in-a-room) first.
You can then unlist the room from the directory and change the join rules.

61
docs/configuring-playbook-bridge-appservice-irc.md Normal file
View file

@ -0,0 +1,61 @@
# Setting up Appservice IRC (optional)
**Note**: bridging to [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) can also happen via the [Heisenbridge](configuring-playbook-bridge-heisenbridge.md) bridge supported by the playbook.
The playbook can install and configure the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge for you.
See the project's [documentation](https://github.com/matrix-org/matrix-appservice-irc/blob/master/HOWTO.md) to learn what it does and why it might be useful to you.
You'll need to use the following playbook configuration:
```yaml
matrix_appservice_irc_enabled: true
matrix_appservice_irc_ircService_servers:
irc.example.com:
name: "ExampleNet"
port: 6697
ssl: true
sasl: false
allowExpiredCerts: false
sendConnectionMessages: true
botConfig:
enabled: true
nick: "MatrixBot"
joinChannelsIfNoUsers: true
privateMessages:
enabled: true
federate: true
dynamicChannels:
enabled: true
createAlias: true
published: true
joinRule: public
groupId: +myircnetwork:localhost
federate: true
aliasTemplate: "#irc_$CHANNEL"
membershipLists:
enabled: false
floodDelayMs: 10000
global:
ircToMatrix:
initial: false
incremental: false
matrixToIrc:
initial: false
incremental: false
matrixClients:
userTemplate: "@irc_$NICK"
displayName: "$NICK (IRC)"
joinAttempts: -1
ircClients:
nickTemplate: "$DISPLAY[m]"
allowNickChanges: true
maxClients: 30
idleTimeout: 10800
reconnectIntervalMs: 5000
concurrentReconnectLimit: 50
lineLimit: 3
```
You then need to start a chat with `@irc_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

112
docs/configuring-playbook-bridge-appservice-slack.md Normal file
View file

@ -0,0 +1,112 @@
# Setting up Appservice Slack (optional)
**Note**: bridging to [Slack](https://slack.com) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) bridge supported by the playbook.
The playbook can install and configure [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) for you.
See the project's [documentation](https://github.com/matrix-org/matrix-appservice-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
## Setup Instructions:
loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Setup)
1. Create a new Matrix room to act as the administration control room. Note its internal room ID. This can
be done in Riot by making a message, opening the options for that message and choosing "view source". The
room ID will be displayed near the top.
2. Enable the bridge with the following configuration in your `vars.yml` file:
```yaml
matrix_appservice_slack_enabled: true
matrix_appservice_slack_control_room_id: "Your matrix admin room id"
```
3. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
4. Invite the bridge bot user into the admin room:
```
/invite @slackbot:MY.DOMAIN
```
Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
5. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
Name the app "matrixbot" (or anything else you'll remember).
Select the team/workspace this app will belong to.
Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
6. Click on Event Subscriptions and enable them and use the request url `https://matrix.DOMAIN/appservice-slack`. Then add the following events and save:
Bot User Events:
- team_domain_change
- message.channels
- message.groups (if you want to bridge private channels)
- reaction_added
- reaction_removed
7. Click on OAuth & Permissions and add the following scopes:
- chat:write:bot
- users:read
- reactions:write
If you want to bridge files, also add the following:
- files:write:user
Note: In order to make Slack files visible to matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
8. Click on Install App and Install App to Workspace. Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
9. For each channel you would like to bridge, perform the following steps:
* Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like !aBcDeF:example.com.
* Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for slack and `/invite @slackbot:MY.DOMAIN` for matrix.
* Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel id>/details/`.
* Issue a link command in the administration control room with these collected values as arguments:
with file bridging:
```
link --channel_id CHANNELID --room !the-matrix:room.id --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
```
without file bridging:
```
link --channel_id CHANNELID --room !the-matrix:room.id --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
```
These arguments can be shortened to single-letter forms:
```
link -I CHANNELID -R !the-matrix:room.id -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
```
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
10. Unlinking
Channels can be unlinked again like this:
```
unlink --room !the-matrix:room.id
```
Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
## Troubleshooting
* as always, check the logs:
`journalctl -fu matrix-appservice-slack`
* linking: "Room is now pending-name"
This typically means that you haven't used the correct slack channel id. Unlink the room and recheck 'Determine the "channel ID"' from above.
* Messages work from M to S, but not the other way around
Check you logs, if they say something like
`WARN SlackEventHandler Ignoring message from unrecognised slack channel id : %s (%s) <the channel id> <some other id>`
then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link
your room multiple times without unlinking it after each failed attempt.

63
docs/configuring-playbook-bridge-appservice-webhooks.md Normal file
View file

@ -0,0 +1,63 @@
# Setting up Appservice Webhooks (optional)
The playbook can install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) for you.
This bridge provides support for Slack-compatible webhooks.
Setup Instructions:
loosely based on [this](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md)
1. All you basically need is to adjust your `inventory/host_vars/matrix.<domain-name>/vars.yml`:
```yaml
matrix_appservice_webhooks_enabled: true
matrix_appservice_webhooks_api_secret: '<your_secret>'
```
2. In case you want to change the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
you can adjust this in `inventory/host_vars/matrix.<domain-name>/vars.yml` as well.
*Note*: default value is: `info` and availabe log levels are : `info`, `verbose`
```yaml
matrix_appservice_webhooks_log_level: '<log_level>'
```
3. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
4. If you're using the [Dimension Integration Manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge by opening the Dimension integration manager -> Settings -> Bridges and selecting edit action for "Webhook Bridge". Press "Add self-hosted Bridge" button and populate "Provisioning URL" & "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.
5. Invite the bridge bot user to your room:
- either with `/invite @_webhook:<domain.name>` (*Note*: Make sure you have administration permissions in your room)
- or simply add the bridge bot to a private channel (personal channels imply you being an administrator)
6. Send a message to the bridge bot in order to receive a private message including the webhook link.
```
!webhook
```
7. The JSON body for posting messages will have to look like this:
```json
{
"text": "Hello world!",
"format": "plain",
"displayName": "My Cool Webhook",
"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
}
```
You can test this via curl like so:
```
curl --header "Content-Type: application/json" \
--data '{
"text": "Hello world!",
"format": "plain",
"displayName": "My Cool Webhook",
"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
}' \
<the link you've gotten in 5.>
```

38
docs/configuring-playbook-bridge-heisenbridge.md Normal file
View file

@ -0,0 +1,38 @@
# Setting up Heisenbridge (optional)
**Note**: bridging to [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) can also happen via the [matrix-appservice-irc](configuring-playbook-bridge-appservice-irc.md) bridge supported by the playbook.
The playbook can install and configure [Heisenbridge](https://github.com/hifi/heisenbridge) - the bouncer-style [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) bridge for you.
See the project's [README](https://github.com/hifi/heisenbridge/blob/master/README.md) to learn what it does and why it might be useful to you. You can also take a look at [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I).
## Configuration
Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/matrix-bridge-heisenbridge/defaults/main.yml).
At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.DOMAIN/vars.yml`):
```yaml
matrix_heisenbridge_enabled: true
# set owner (optional)
matrix_heisenbridge_owner: "@you:your-homeserver"
# to enable identd on host port 113/TCP (optional)
matrix_heisenbridge_identd_enabled: true
```
That's it! A registration file is automatically generated during the setup phase.
Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` will be made the owner.
If you are not using a local user you must set it as otherwise you can't DM it at all.
## Usage
After the bridge is successfully running just DM `@heisenbridge:your-homeserver` to start setting it up.
Help is available for all commands with the `-h` switch.
If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.
You can also learn the basics by watching [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I).
If you encounter issues or feel lost you can join the project room at [#heisenbridge:vi.fi](https://matrix.to/#/#heisenbridge:vi.fi) for help.

37
docs/configuring-playbook-bridge-matrix-bridge-sms.md Normal file
View file

@ -0,0 +1,37 @@
# Setting up matrix-sms-bridge (optional)
The playbook can install and configure [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for you.
See the project page to learn what it does and why it might be useful to you.
**The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.**
To enable the bridge just use the following
playbook configuration:
```yaml
matrix_sms_bridge_enabled: true
# (optional but recommended) a room id to a default room
matrix_sms_bridge_default_room: ""
# (optional but recommended) configure your server location
matrix_sms_bridge_default_region: DE
matrix_sms_bridge_default_timezone: Europe/Berlin
# Settings to connect to android-sms-gateway-server
matrix_sms_bridge_provider_android_baseurl: https://192.168.24.24:9090
matrix_sms_bridge_provider_android_username: admin
matrix_sms_bridge_provider_android_password: supeSecretPassword
# (optional) if your android-sms-gateway-server uses a self signed vertificate, the bridge needs a "truststore". This can be the certificate itself.
matrix_sms_bridge_provider_android_truststore_local_path: android-sms-gateway-server.p12
matrix_sms_bridge_provider_android_truststore_password: 123
```
## Usage
Read the [user guide](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md#user-guide) to see how this bridge works.

118
docs/configuring-playbook-bridge-mautrix-facebook.md Normal file
View file

@ -0,0 +1,118 @@
# Setting up Mautrix Facebook (optional)
The playbook can install and configure [mautrix-facebook](https://github.com/tulir/mautrix-facebook) for you.
See the project's [documentation](https://github.com/tulir/mautrix-facebook/blob/master/ROADMAP.md) to learn what it does and why it might be useful to you.
```yaml
matrix_mautrix_facebook_enabled: true
```
There are some additional things you may wish to configure about the bridge before you continue.
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
```yaml
matrix_mautrix_facebook_configuration_extension_yaml: |
bridge:
encryption:
allow: true
default: true
```
If you would like to be able to administrate the bridge from your account it can be configured like this:
```yaml
matrix_mautrix_facebook_configuration_extension_yaml: |
bridge:
permissions:
'@YOUR_USERNAME:YOUR_DOMAIN': admin
```
You may wish to look at `roles/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` to find other things you would like to configure.
## Set up Double Puppeting
If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Facebook", "initial_device_display_name": "Mautrix-Facebook"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Facebook` device some time in the future, as that would break the Double Puppeting feature
## Usage
You then need to start a chat with `@facebookbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/facebook/authentication.html).
If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
## Set up community-grouping
This is an **optional feature** that you may wish to enable.
The Facebook bridge can create a Matrix community for you, which would contain all your chats and contacts.
For this to work, the bridge's bot needs to have permissions to create communities (also referred to as groups).
Since the bot is a non-admin user, you need to enable such group-creation for non-privileged users in [Synapse's settings](configuring-playbook-synapse.md).
Here's an example configuration:
```yaml
matrix_synapse_configuration_extension_yaml: |
enable_group_creation: true
group_creation_prefix: "unofficial/"
matrix_mautrix_facebook_configuration_extension_yaml: |
bridge:
community_template: "unofficial/facebook_{localpart}={server}"
```
Once the bridge is restarted, it would create a community and invite you to it. You need to accept the community invitation manually.
If you don't see all your contacts, you may wish to send a `sync` message to the bot.
## Troubleshooting
### Facebook rejecting login attempts and forcing you to change password
If your Matrix server is in a wildly different location than where you usually use your Facebook account from, the bridge's login attempts may be outright rejected by Facebook. Along with that, Facebook may even force you to change the account's password.
If you happen to run into this problem while [setting up bridging](#usage), try to first get a successful session up by logging in to Facebook through the Matrix server's IP address.
The easiest way to do this may be to use [sshuttle](https://sshuttle.readthedocs.io/) to proxy your traffic through the Matrix server.
Example command for proxying your traffic through the Matrix server:
```
sshuttle -r root@matrix.DOMAIN:22 0/0
```
Once connected, you should be able to verify that you're browsing the web through the Matrix server's IP by checking [icanhazip](https://icanhazip.com/).
Then proceed to log in to [Facebook/Messenger](https://www.facebook.com/).
Once logged in, proceed to [set up bridging](#usage).

58
docs/configuring-playbook-bridge-mautrix-hangouts.md Normal file
View file

@ -0,0 +1,58 @@
# Setting up Mautrix Hangouts (optional)
The playbook can install and configure [mautrix-hangouts](https://github.com/tulir/mautrix-hangouts) for you.
See the project's [documentation](https://github.com/tulir/mautrix-hangouts/wiki#usage) to learn what it does and why it might be useful to you.
To enable the [Google Hangouts](https://hangouts.google.com/) bridge just use the following playbook configuration:
```yaml
matrix_mautrix_hangouts_enabled: true
```
## Set up Double Puppeting
If you'd like to use [Double Puppeting](https://github.com/tulir/mautrix-hangouts/wiki/Authentication#double-puppeting) (hint: you most likely do), you have 2 ways of going about it.
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Hangouts", "initial_device_display_name": "Mautrix-Hangouts"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Hangouts` device some time in the future, as that would break the Double Puppeting feature
## Usage
Once the bot is enabled you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions.
Automatic login may not work. If it does not, reload the page and select the "Manual login" checkbox before starting. Manual login involves logging into your Google account normally and then manually getting the OAuth token from browser cookies with developer tools.
Once logged in, recent chats should show up as new conversations automatically. Other chats will get portals as you receive messages.
You can learn more about authentication from the bridge's [official documentation on Authentication](https://github.com/tulir/mautrix-hangouts/wiki/Authentication).
After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.

17
docs/configuring-playbook-bridge-mautrix-instagram.md Normal file
View file

@ -0,0 +1,17 @@
# Setting up Mautrix Instagram (optional)
The playbook can install and configure [mautrix-instagram](https://github.com/tulir/mautrix-instagram) for you.
See the project's [documentation](https://docs.mau.fi/bridges/python/instagram/index.html) to learn what it does and why it might be useful to you.
```yaml
matrix_mautrix_instagram_enabled: true
```
## Usage
You then need to start a chat with `@instagrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account.
You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/instagram/authentication.html).

46
docs/configuring-playbook-bridge-mautrix-signal.md Normal file
View file

@ -0,0 +1,46 @@
# Setting up Mautrix Signal (optional)
The playbook can install and configure [mautrix-signal](https://github.com/tulir/mautrix-signal) for you.
See the project's [documentation](https://github.com/tulir/mautrix-signal/wiki) to learn what it does and why it might be useful to you.
**Note/Prerequisite**: If you're running with the Postgres database server integrated by the playbook (which is the default), you don't need to do anything special and can easily proceed with installing. However, if you're [using an external Postgres server](configuring-playbook-external-postgres.md), you'd need to manually prepare a Postgres database for this bridge and adjust the variables related to that (`matrix_mautrix_signal_database_*`).
Use the following playbook configuration:
```yaml
matrix_mautrix_signal_enabled: true
```
## Set up Double Puppeting
If you'd like to use [Double Puppeting](https://github.com/tulir/mautrix-signal/wiki/Authentication#double-puppeting) (hint: you most likely do), you have 2 ways of going about it.
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Signal", "initial_device_display_name": "Mautrix-Signal"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Signal` device some time in the future, as that would break the Double Puppeting feature
## Usage
You then need to start a chat with `@signalbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

52
docs/configuring-playbook-bridge-mautrix-telegram.md Normal file
View file

@ -0,0 +1,52 @@
# Setting up Mautrix Telegram (optional)
The playbook can install and configure [mautrix-telegram](https://github.com/tulir/mautrix-telegram) for you.
See the project's [documentation](https://github.com/tulir/mautrix-telegram/wiki#usage) to learn what it does and why it might be useful to you.
You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then use the following playbook configuration:
```yaml
matrix_mautrix_telegram_enabled: true
matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
```
## Set up Double Puppeting
If you'd like to use [Double Puppeting](https://github.com/tulir/mautrix-telegram/wiki/Authentication#replacing-telegram-accounts-matrix-puppet-with-matrix-account) (hint: you most likely do), you have 2 ways of going about it.
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging.
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Telegram", "initial_device_display_name": "Mautrix-Telegram"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send `login-matrix` to the bot and follow instructions about how to send the access token to it
- make sure you don't log out the `Mautrix-Telegram` device some time in the future, as that would break the Double Puppeting feature
## Usage
You then need to start a chat with `@telegrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
If you want to use the relay-bot feature ([relay bot documentation](https://github.com/tulir/mautrix-telegram/wiki/Relay-bot)), which allows anonymous user to chat with telegram users, use the following additional playbook configuration:
```yaml
matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN
```

45
docs/configuring-playbook-bridge-mautrix-whatsapp.md Normal file
View file

@ -0,0 +1,45 @@
# Setting up Mautrix Whatsapp (optional)
The playbook can install and configure [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) for you.
See the project's [documentation](https://github.com/tulir/mautrix-whatsapp/wiki) to learn what it does and why it might be useful to you.
Use the following playbook configuration:
```yaml
matrix_mautrix_whatsapp_enabled: true
```
## Set up Double Puppeting
If you'd like to use [Double Puppeting](https://github.com/tulir/mautrix-whatsapp/wiki/Authentication#replacing-whatsapp-accounts-matrix-puppet-with-matrix-account) (hint: you most likely do), you have 2 ways of going about it.
### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Whatsapp", "initial_device_display_name": "Mautrix-Whatsapp"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Whatsapp` device some time in the future, as that would break the Double Puppeting feature
## Usage
You then need to start a chat with `@whatsappbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

34
docs/configuring-playbook-bridge-mx-puppet-discord.md Normal file
View file

@ -0,0 +1,34 @@
# Setting up MX Puppet Discord (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridge supported by the playbook.
The playbook can install and configure
[mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) for you.
See the project page to learn what it does and why it might be useful to you.
To enable the [Discord](https://discordapp.com/) bridge just use the following
playbook configuration:
```yaml
matrix_mx_puppet_discord_enabled: true
```
## Usage
Once the bot is enabled you need to start a chat with `Discord Puppet Bridge` with
the handle `@_discordpuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
domain, not the `matrix.` domain).
Three authentication methods are available, Legacy Token, OAuth and xoxc token.
See mx-puppet-discord [documentation](https://github.com/matrix-discord/mx-puppet-discord)
for more information about how to configure the bridge.
Once logged in, send `list` to the bot user to list the available rooms.
Clicking rooms in the list will result in you receiving an invitation to the
bridged room.
Also send `help` to the bot to see the commands available.

36
docs/configuring-playbook-bridge-mx-puppet-groupme.md Normal file
View file

@ -0,0 +1,36 @@
# Setting up MX Puppet GroupMe (optional)
The playbook can install and configure
[mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) for you.
See the project page to learn what it does and why it might be useful to you.
To enable the [GroupMe](https://groupme.com/) bridge just use the following
playbook configuration:
```yaml
matrix_mx_puppet_groupme_enabled: true
```
## Usage
Once the bot is enabled you need to start a chat with `GroupMe Puppet Bridge` with
the handle `@_groupmepuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
domain, not the `matrix.` domain).
One authentication method is available.
To link your GroupMe account, go to [dev.groupme.com](https://dev.groupme.com/), sign in, and select "Access Token" from the top menu. Copy the token and message the bridge with:
```
link <access token>
```
Once logged in, send `listrooms` to the bot user to list the available rooms.
Clicking rooms in the list will result in you receiving an invitation to the
bridged room.
Also send `help` to the bot to see the commands available.

36
docs/configuring-playbook-bridge-mx-puppet-instagram.md Normal file
View file

@ -0,0 +1,36 @@
# Setting up mx-puppet-instagram (optional)
The playbook can install and configure
[mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) for you.
This allows you to bridge Instagram DirectMessages into Matrix.
To enable the [Instagram](https://www.instagram.com/) bridge just use the following
playbook configuration:
```yaml
matrix_mx_puppet_instagram_enabled: true
```
## Usage
Once the bot is enabled, you need to start a chat with `Instagram Puppet Bridge` with
the handle `@_instagrampuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
domain, not the `matrix.` domain).
Send `link <username> <password>` to the bridge bot to link your instagram account.
The `list` commands shows which accounts are linked and which `puppetId` is associated.
For double-puppeting, you probably want to issue these commands:
- `settype $puppetId puppet` to enable puppeting for the link (instead of relaying)
- `setautoinvite $puppetId 1` to automatically invite you to chats
- `setmatrixtoken $accessToken` to set the access token to enable puppeting from the other side (the "double" in double puppeting)
If you are linking only one Instagram account, your `$puppetId` is probably 1, but use the `list` command find out.
The `help` command shows which commands are available, though at the time of writing, not every command is fully implemented.

30
docs/configuring-playbook-bridge-mx-puppet-skype.md Normal file
View file

@ -0,0 +1,30 @@
# Setting up MX Puppet Skype (optional)
The playbook can install and configure
[mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) for you.
See the project page to learn what it does and why it might be useful to you.
To enable the [Skype](https://www.skype.com/) bridge just use the following
playbook configuration:
```yaml
matrix_mx_puppet_skype_enabled: true
```
## Usage
Once the bot is enabled you need to start a chat with `Skype Puppet Bridge` with
the handle `@_skypepuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
domain, not the `matrix.` domain).
Send `link <username> <password>` to the bridge bot to link your skype account.
Once logged in, send `list` to the bot user to list the available rooms.
Clicking rooms in the list will result in you receiving an invitation to the
bridged room.
Also send `help` to the bot to see the commands available.

34
docs/configuring-playbook-bridge-mx-puppet-slack.md Normal file
View file

@ -0,0 +1,34 @@
# Setting up MX Puppet Slack (optional)
**Note**: bridging to [Slack](https://slack.com) can also happen via the [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) bridge supported by the playbook.
The playbook can install and configure
[mx-puppet-slack](https://github.com/Sorunome/mx-puppet-slack) for you.
See the project page to learn what it does and why it might be useful to you.
To enable the [Slack](https://slack.com/) bridge just use the following
playbook configuration:
```yaml
matrix_mx_puppet_slack_enabled: true
```
## Usage
Once the bot is enabled you need to start a chat with `Slack Puppet Bridge` with
the handle `@_slackpuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
domain, not the `matrix.` domain).
Three authentication methods are available, Legacy Token, OAuth and xoxc token.
See mx-puppet-slack [documentation](https://github.com/Sorunome/mx-puppet-slack)
for more information about how to configure the bridge.
Once logged in, send `list` to the bot user to list the available rooms.
Clicking rooms in the list will result in you receiving an invitation to the
bridged room.
Also send `help` to the bot to see the commands available.

32
docs/configuring-playbook-bridge-mx-puppet-steam.md Normal file
View file

@ -0,0 +1,32 @@
# Setting up MX Puppet Steam (optional)
The playbook can install and configure
[mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) for you.
See the project page to learn what it does and why it might be useful to you.
To enable the [Steam](https://steampowered.com/) bridge just use the following
playbook configuration:
```yaml
matrix_mx_puppet_steam_enabled: true
```
## Usage
Once the bot is enabled you need to start a chat with `Steam Puppet Bridge` with
the handle `@_steampuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
domain, not the `matrix.` domain).
Three authentication methods are available, Legacy Token, OAuth and xoxc token.
See mx-puppet-steam [documentation](https://github.com/icewind1991/mx-puppet-steam)
for more information about how to configure the bridge.
Once logged in, send `list` to the bot user to list the available rooms.
Clicking rooms in the list will result in you receiving an invitation to the
bridged room.
Also send `help` to the bot to see the commands available.

34
docs/configuring-playbook-bridge-mx-puppet-twitter.md Normal file
View file

@ -0,0 +1,34 @@
# Setting up MX Puppet Twitter (optional)
The playbook can install and configure
[mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) for you.
See the project page to learn what it does and why it might be useful to you.
To enable the [Twitter](https://twitter.com) bridge, make an app on [developer.twitter.com](https://developer.twitter.com/en/apps)
and fill out the following playbook configuration.
```yaml
matrix_mx_puppet_twitter_enabled: true
matrix_mx_puppet_twitter_consumer_key: ''
matrix_mx_puppet_twitter_consumer_secret: ''
matrix_mx_puppet_twitter_access_token: ''
matrix_mx_puppet_twitter_access_token_secret: ''
matrix_mx_puppet_twitter_environment: ''
```
## Usage
Once the bot is enabled you need to start a chat with `Twitter Puppet Bridge` with
the handle `@_twitterpuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
domain, not the `matrix.` domain).
To log in, use `link` and click the link.
Once logged in, send `list` to the bot user to list the available rooms.
Clicking rooms in the list will result in you receiving an invitation to the
bridged room.
Also send `help` to the bot to see the commands available.

41
docs/configuring-playbook-client-element.md Normal file
View file

@ -0,0 +1,41 @@
# Configuring Element (optional)
By default, this playbook installs the [Element](https://github.com/vector-im/element-web) Matrix client web application.
If that's okay, you can skip this document.
## Disabling Element
If you'd like for the playbook to not install Element (or to uninstall it if it was previously installed), you can disable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_client_element_enabled: false
```
## Configuring Element settings
The playbook provides some customization variables you could use to change Element's settings.
Their defaults are defined in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/matrix-client-element/templates/config.json.j2`](../roles/matrix-client-element/templates/config.json.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for an Element setting you wish to change:
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Element's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/matrix-client-element/templates/config.json.j2)) by making use of the `matrix_client_element_configuration_extension_json_` variable. You can find information about this in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml).
## Themes
To change the look of Element, you can define your own themes manually by using the `matrix_client_element__settingDefaults_custom_themes` setting.
Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_element_themes_enabled: true`).
If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
Note that for a custom theme to work well, all Element instances that you use must have the same theme installed.

21
docs/configuring-playbook-client-hydrogen.md Normal file
View file

@ -0,0 +1,21 @@
# Configuring Hydrogen (optional)
This playbook can install the [Hydrogen](https://github.com/vector-im/hydrogen-web) Matrix web client for you.
Hydrogen is a lightweight web client that supports mobile and legacy web browsers.
Hydrogen can be installed alongside or instead of Element.
If you'd like Hydrogen to be installed, add the following to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_client_hydrogen_enabled: true
```
You will also need to add a DNS record so that Hydrogen can be accessed.
By default Hydrogen will use https://hydrogen.DOMAIN so you will need to create an CNAME record
for `hydrogen`. See [Configuring DNS](configuring-dns.md).
If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):
```yaml
matrix_server_fqn_hydrogen: "helium.{{ matrix_domain }}"
```

97
docs/configuring-playbook-dimension.md Normal file
View file

@ -0,0 +1,97 @@
# Setting up Dimension (optional)
**[Dimension](https://dimension.t2bot.io) can only be installed after Matrix services are installed and running.**
If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) flow and come back here later.
**Note**: enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
## Prerequisites
This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and an [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environment. This is handled automatically based on the value of `matrix_synapse_federation_enabled`.
Other important prerequisite is the `dimension.<your-domain>` DNS record being set up correctly. See [Configuring your DNS server](configuring-dns.md) on how to set up DNS record correctly.
## Enable
[Dimension integrations manager](https://dimension.t2bot.io) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_dimension_enabled: true
```
## Define admin users
These users can modify the integrations this Dimension supports. Admin interface is accessible by opening Dimension in Element and clicking the settings icon.
Add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_dimension_admins:
- "@user1:{{ matrix_domain }}"
- "@user2:{{ matrix_domain }}"
```
## Access token
We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username).
Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
You are required to specify an access token (belonging to this new user) for Dimension to work.
To get an access token for the Dimension user, you can follow one of two options:
*Through an interactive login*:
1. In a private browsing session (incognito window), open Element.
2. Log in with the `dimension` user and its password.
1. Set the display name and avatar, if required.
2. In the settings page choose "Help & About", scroll down to the bottom and click `Access Token: <click to reveal>`.
3. Copy the highlighted text to your configuration.
4. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
*With CURL*
```
curl -X POST --header 'Content-Type: application/json' -d '{
"identifier": { "type": "m.id.user", "user": "YourDimensionUsername" },
"password": "YourDimensionPassword",
"type": "m.login.password"
}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
```
*Change the "YourDimensionUser/Pass" URL accordigly*
**Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
Add access token to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_dimension_access_token: "YOUR ACCESS TOKEN HERE"
```
For more information on how to acquire an access token, visit [https://t2bot.io/docs/access_tokens](https://t2bot.io/docs/access_tokens).
## Installation
After these variables have been set, please run the following command to re-run setup and to restart Dimension:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Jitsi domain
By default Dimension will use [jitsi.riot.im](https://jitsi.riot.im/) as the `conferenceDomain` of [Jitsi](https://jitsi.org/) audio/video conference widgets. For users running [a self-hosted Jitsi instance](./configuring-playbook-jitsi.md), you will likely want the widget to use your own Jitsi instance. Currently there is no way to configure this via the playbook, see [this issue](https://github.com/turt2live/matrix-dimension/issues/345) for details.
In the interim until the above limitation is resolved, an admin user needs to configure the domain via the admin ui once dimension is running. In Element, go to *Manage Integrations* &rightarrow; *Settings* &rightarrow; *Widgets* &rightarrow; *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
## Additional features
To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it.
To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/matrix-dimension/defaults/main.yml) of the Dimension component.
You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).

27
docs/configuring-playbook-dynamic-dns.md Normal file
View file

@ -0,0 +1,27 @@
# Dynamic DNS
## Setup
Most cloud providers / ISPs will charge you extra for a static IP address. If you're
not hosting a highly reliable homeserver you can workaround this via dynamic DNS. To
set this up, you'll need to get the username/password from your DNS provider. For
google domains, this process is described [here](https://support.google.com/domains/answer/6147083).
After you've gotten the proper credentials you can add the following config to your `inventory/host_vars/matrix.DOMAIN/vars.yml`:
```yaml
matrix_dynamic_dns_enabled: true
matrix_dynamic_dns_domain_configurations:
- provider: domains.google.com
protocol: dyndn2
username: XXXXXXXXXXXXXXXX
password: XXXXXXXXXXXXXXXX
domain: "{{ matrix_domain }}"
```
## Additional Reading
Additional resources:
- https://matrix.org/docs/guides/free-small-matrix-server

55
docs/configuring-playbook-email.md Normal file
View file

@ -0,0 +1,55 @@
# Adjusting email-sending settings (optional)
By default, this playbook sets up an [Exim](https://www.exim.org/) email server through which all Matrix services send emails.
The email server would attempt to deliver emails directly to their final destination.
This may or may not work, depending on your domain configuration (SPF settings, etc.)
By default, emails are sent from `matrix@<your-domain-name>` (as specified by the `matrix_mailer_sender_address` playbook variable).
**Note**: If you are using a Google Cloud instance, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so you need to relay email through another SMTP server as described below.
## Firewall settings
No matter whether you send email directly (the default) or you relay email through another host (see how below), you'll probably need to allow outgoing traffic for TCP ports 25/587 (depending on configuration).
## Relaying email through another SMTP server
If you'd like to relay email through another SMTP server, feel free to redefine a few playbook variables.
Example:
```yaml
matrix_mailer_sender_address: "another.sender@example.com"
matrix_mailer_relay_use: true
matrix_mailer_relay_host_name: "mail.example.com"
matrix_mailer_relay_host_port: 587
matrix_mailer_relay_auth: true
matrix_mailer_relay_auth_username: "another.sender@example.com"
matrix_mailer_relay_auth_password: "some-password"
```
**Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.
### Configuations for sending emails using Sendgrid
An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `matrix_mailer_sender_address`.
The only other thing you need to change is the `matrix_mailer_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
Note that the `matrix_mailer_relay_auth_username` is literally the string `apikey`, it's always the same for Sendgrid.
```yaml
matrix_mailer_sender_address: "arbitrary@email.com"
matrix_mailer_relay_use: true
matrix_mailer_relay_host_name: "smtp.sendgrid.net"
matrix_mailer_relay_host_port: 587
matrix_mailer_relay_auth: true
matrix_mailer_relay_auth_username: "apikey"
matrix_mailer_relay_auth_password: "<your api key password>"
```
## Troubleshooting
If you're having trouble with email not being delivered, it may be useful to inspect the mailer logs: `journalctl -f -u matrix-mailer`.

80
docs/configuring-playbook-email2matrix.md Normal file
View file

@ -0,0 +1,80 @@
# Setting up Email2Matrix (optional)
The playbook can install and configure [email2matrix](https://github.com/devture/email2matrix) for you.
See the project's [documentation](https://github.com/devture/email2matrix/blob/master/docs/README.md) to learn what it does and why it might be useful to you.
## Preparation
### Port availability
Ensure that port 25 is available on your Matrix server and open in your firewall.
If you have `postfix` or some other email server software installed, you may need to manually remove it first (unless you need it, of course).
If you really need to run an email server on the Matrix machine for other purposes, it may be possible to run Email2Matrix on another port (with a configuration like `matrix_email2matrix_smtp_host_bind_port: "127.0.0.01:2525"`) and have your other email server relay messages there.
For details about using Email2Matrix alongside [Postfix](http://www.postfix.org/), see [here](https://github.com/devture/email2matrix/blob/master/docs/setup_with_postfix.md).
### Creating a user
Before enabling Email2Matrix, you'd most likely wish to create a dedicated user (or more) that would be sending messages on the Matrix side.
Refer to [Registering users](registering-users.md) for ways to do that. A regular (non-admin) user works best.
### Creating a shared room
After creating a sender user, you should create one or more Matrix rooms that you share with that user.
It doesn't matter who creates and owns the rooms and who joins later (you or the sender user).
What matters is that both you and the sender user are part of the same room and that the sender user has enough privileges in the room to be able to send messages there.
Inviting additional people to the room is okay too.
Take note of each room's room id (different clients show the room id in a different place).
You'll need the room id when doing [Configuration](#configuration) below.
### Obtaining an access token for the sender user
In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it.
To do this, you can execute a command like this:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "email2matrix" }, "password": "MATRIX_PASSWORD_FOR_THE_USER", "type": "m.login.password", "device_id": "Email2Matrix", "initial_device_display_name": "Email2Matrix"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
Take note of the `access_token` value. You'll need the access token when doing [Configuration](#configuration) below.
## Configuration
After doing the preparation steps above, adjust your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration like this:
```yaml
matrix_email2matrix_enabled: true
matrix_email2matrix_matrix_mappings:
- MailboxName: "my-mailbox"
MatrixRoomId: "!someRoom:DOMAIN"
MatrixHomeserverUrl: "https://matrix.DOMAIN"
MatrixUserId: "@email2matrix:DOMAIN"
MatrixAccessToken: "ACCESS_TOKEN_GOES_HERE"
IgnoreSubject: false
IgnoreBody: false
SkipMarkdown: false
- MailboxName: "my-mailbox2"
MatrixRoomId: "!anotherRoom:DOMAIN"
MatrixHomeserverUrl: "https://matrix.DOMAIN"
MatrixUserId: "@email2matrix:DOMAIN"
MatrixAccessToken: "ACCESS_TOKEN_GOES_HERE"
IgnoreSubject: true
IgnoreBody: false
SkipMarkdown: true
```
You can also set `MatrixHomeserverUrl` to `http://matrix-synapse:8008`, instead of the public `https://matrix.DOMAIN`.
However, that's more likely to break in the future if you switch to another server implementation than Synapse.
Re-run the playbook (`--tags=setup-email2matrix,start`) and try sending an email to `my-mailbox@matrix.DOMAIN`.

31
docs/configuring-playbook-etherpad.md Normal file
View file

@ -0,0 +1,31 @@
# Setting up Etherpad (optional)
[Etherpad](https://etherpad.org) is is an open source collaborative text editor that can be embedded in a Matrix chat room using the [Dimension integrations manager](https://dimension.t2bot.io)
When enabled together with the Jitsi audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
## Prerequisites
For the self-hosted Etherpad instance to be available to your users, you must first enable and configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md)
## Installing
[Etherpad](https://etherpad.org) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_etherpad_enabled: true
```
## Set Dimension default to the self-hosted Etherpad
The Dimension administrator users can configure the default URL template. The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab. Replace `scalar.vector.im` with your own Dimension domain.
### Removing the integrated Etherpad chat
If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
Example: `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false`
## Known issues
If your Etherpad widget fails to load, this might be due to Dimension generating a Pad name so long, the Etherpad app rejects it.
`$roomId_$padName` can end up being longer than 50 characters. You can avoid having this problem by altering the template so it only contains the three word random identifier `$padName`.

25
docs/configuring-playbook-external-postgres.md Normal file
View file

@ -0,0 +1,25 @@
# Using an external PostgreSQL server (optional)
By default, this playbook would set up a PostgreSQL database server on your machine, running in a Docker container.
If that's alright, you can skip this.
If you'd like to use an external PostgreSQL server that you manage, you can edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`).
It should be something like this:
```yaml
matrix_postgres_enabled: false
# Rewire Synapse to use your external Postgres server
matrix_synapse_database_host: "your-postgres-server-hostname"
matrix_synapse_database_user: "your-postgres-server-username"
matrix_synapse_database_password: "your-postgres-server-password"
matrix_synapse_database_database: "your-postgres-server-database-name"
```
The database (as specified in `matrix_synapse_database_database`) must exist and be accessible with the given credentials.
It must be empty or contain a valid Synapse database. If empty, Synapse would populate it the first time it runs.
**Note**: the external server that you specify in `matrix_synapse_database_host` must be accessible from within the `matrix-synapse` Docker container (and possibly other containers too). This means that it either needs to be a publicly accessible hostname or that it's a hostname on the same Docker network where all containers installed by this playbook run (a network called `matrix` by default). Using a local PostgreSQL instance on the host (running on the same machine, but not in a container) is not possible.
The connection to your external Postgres server **will not be SSL encrypted**, as [we don't support that yet](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/89).

49
docs/configuring-playbook-federation.md Normal file
View file

@ -0,0 +1,49 @@
# Controlling Matrix federation (optional)
By default, your server federates with the whole Matrix network.
That is, people on your server can communicate with people on any other Matrix server.
## Federating only with select servers
To make your server only federate with servers of your choosing, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_synapse_federation_domain_whitelist:
- example.com
- another.com
```
If you wish to disable federation, you can do that with an empty list (`[]`), or better yet by completely disabling federation (see below).
## Exposing the room directory over federation
By default, your server's public rooms directory is not exposed to other servers via federation.
If you wish to expose it, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_synapse_allow_public_rooms_over_federation: true
```
## Disabling federation
To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_synapse_federation_enabled: false
```
With that, your server's users will only be able to talk among themselves, but not to anyone who is on another server.
**Disabling federation does not necessarily disable the federation port** (`8448`). Services like [Dimension](configuring-playbook-dimension.md) and [ma1sd](configuring-playbook-ma1sd.md) normally rely on `openid` APIs exposed on that port. Even if you disable federation and only if necessary, we may still be exposing the federation port and serving the `openid` APIs there. To override this and completely disable Synapse's federation port use:
```yaml
# This stops the federation port on the Synapse side (normally `matrix-synapse:8048` on the container network).
matrix_synapse_federation_port_enabled: false
# This removes the `8448` virtual host from the matrix-nginx-proxy reverse-proxy server.
matrix_nginx_proxy_proxy_matrix_federation_api_enabled: false
```

168
docs/configuring-playbook-jitsi.md Normal file
View file

@ -0,0 +1,168 @@
# Jitsi
The playbook can install the [Jitsi](https://jitsi.org/) video-conferencing platform and integrate it with [Element](configuring-playbook-client-element.md).
Jitsi installation is **not enabled by default**, because it's not a core component of Matrix services.
The setup done by the playbook is very similar to [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet). You can refer to the documentation there for many of the options here.
## Prerequisites
Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record. See [Configuring DNS](configuring-dns.md).
You may also need to open the following ports to your server:
- `4443/tcp` - RTP media fallback over TCP
- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`matrix_jitsi_jvb_stun_servers`](../roles/matrix-jitsi/defaults/main.yml)).
## Installation
Add this to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
```yaml
matrix_jitsi_enabled: true
# Run `bash inventory/scripts/jitsi-generate-passwords.sh` to generate these passwords,
# or define your own strong passwords manually.
matrix_jitsi_jicofo_component_secret: ""
matrix_jitsi_jicofo_auth_password: ""
matrix_jitsi_jvb_auth_password: ""
matrix_jitsi_jibri_recorder_password: ""
matrix_jitsi_jibri_xmpp_password: ""
```
## (Optional) Configure Jitsi authentication and guests mode
By default the Jitsi Meet instance does not require any kind of login and is open to use for anyone without registration.
If you're fine with such an open Jitsi instance, please skip to [Apply changes](#apply-changes).
If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow this step to enable Jitsi's authentication and guests mode. With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join. If a registered host is not yet present, guests are put on hold in individual waiting rooms.
Add these two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
```yaml
matrix_jitsi_enable_auth: true
matrix_jitsi_enable_guests: true
```
### (Optional) LDAP authentication
The default authentication mode of Jitsi is `internal`, however LDAP is also supported. An example LDAP configuration could be:
```yaml
matrix_jitsi_enable_auth: true
matrix_jitsi_auth_type: ldap
matrix_jitsi_ldap_url: "ldap://ldap.DOMAIN"
matrix_jitsi_ldap_base: "OU=People,DC=DOMAIN
#matrix_jitsi_ldap_binddn: ""
#matrix_jitsi_ldap_bindpw: ""
matrix_jitsi_ldap_filter: "uid=%u"
matrix_jitsi_ldap_auth_method: "bind"
matrix_jitsi_ldap_version: "3"
matrix_jitsi_ldap_use_tls: true
matrix_jitsi_ldap_tls_ciphers: ""
matrix_jitsi_ldap_tls_check_peer: true
matrix_jitsi_ldap_tls_cacert_file: "/etc/ssl/certs/ca-certificates.crt"
matrix_jitsi_ldap_tls_cacert_dir: "/etc/ssl/certs"
matrix_jitsi_ldap_start_tls: false
```
For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet#authentication-using-ldap) and the [saslauthd `LDAP_SASLAUTHD`](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD) documentation.
## (Optional) Making your Jitsi server work on a LAN
By default the Jitsi Meet instance does not work with a client in LAN (Local Area Network), even if others are connected from WAN. There are no video and audio. In the case of WAN to WAN everything is ok.
The reason is the Jitsi VideoBridge git to LAN client the IP address of the docker image instead of the host. The [documentation](https://github.com/jitsi/docker-jitsi-meet#running-behind-nat-or-on-a-lan-environment) of Jitsi in docker suggest to add `DOCKER_HOST_ADDRESS` in enviornment variable to make it work.
Here is how to do it in the playbook.
Add these two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
```yaml
matrix_jitsi_jvb_container_extra_arguments:
- '--env "DOCKER_HOST_ADDRESS=<Local IP adress of the host>"'
```
## (Optional) Fine tune Jitsi
Sample **additional** `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration to save up resources (explained below):
```yaml
matrix_jitsi_web_custom_config_extension: |
config.enableLayerSuspension = true;
config.disableAudioLevels = true;
// Limit the number of video feeds forwarded to each client
config.channelLastN = 4;
matrix_jitsi_web_config_resolution_width_ideal_and_max: 480
matrix_jitsi_web_config_resolution_height_ideal_and_max: 240
```
You may want to **suspend unused video layers** until they are requested again, to save up resources on both server and clients.
Read more on this feature [here](https://jitsi.org/blog/new-off-stage-layer-suppression-feature/)
For this add this line to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
You may wish to **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved.
You may want to **limit the number of video feeds forwarded to each client**, to save up resources on both server and clients. As clients’ bandwidth and CPU may not bear the load, use this setting to avoid lag and crashes.
This feature is found by default in other webconference applications such as Office 365 Teams (limit is set to 4).
Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/master/doc/last-n.md) and performance evaluation on this [study](https://jitsi.org/wp-content/uploads/2016/12/nossdav2015lastn.pdf).
You may want to **limit the maximum video resolution**, to save up resources on both server and clients.
## Apply changes
Then re-run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
## Required if configuring Jitsi with internal authentication: register new users
Until this gets integrated into the playbook, we need to register new users / meeting hosts for Jitsi manually.
Please SSH into your matrix host machine and execute the following command targeting the `matrix-jitsi-prosody` container:
```bash
docker exec matrix-jitsi-prosody prosodyctl --config /config/prosody.cfg.lua register <USERNAME> meet.jitsi <PASSWORD>
```
Run this command for each user you would like to create, replacing `<USERNAME>` and `<PASSWORD>` accordingly. After you've finished, please exit the host.
**If you get an error** like this: "Error: Account creation/modification not supported.", it's likely that you had previously installed Jitsi without auth/guest support. In such a case, you should look into [Rebuilding your Jitsi installation](#rebuilding-your-jitsi-installation).
## Usage
You can use the self-hosted Jitsi server in multiple ways:
- **by adding a widget to a room via Element** (the one configured by the playbook at `https://element.DOMAIN`). Just start a voice or a video call in a room containing more than 2 members and that would create a Jitsi widget which utilizes your self-hosted Jitsi server.
- **by adding a widget to a room via the Dimension Integration Manager**. You'll have to point the widget to your own Jitsi server manually. See our [Dimension](./configuring-playbook-dimension.md) documentation page for more details. Naturally, Dimension would need to be installed first (the playbook doesn't install it by default).
- **directly (without any Matrix integration)**. Just go to `https://jitsi.DOMAIN`
**Note**: Element apps on mobile devices currently [don't support joining meetings on a self-hosted Jitsi server](https://github.com/vector-im/riot-web/blob/601816862f7d84ac47547891bd53effa73d32957/docs/jitsi.md#mobile-app-support).
## Troubleshooting
### Rebuilding your Jitsi installation
**If you ever run into any trouble** or **if you change configuration (`matrix_jitsi_*` variables) too much**, we urge you to rebuild your Jitsi setup.
We normally don't require such manual intervention for other services, but Jitsi services generate a lot of configuration files on their own.
These files are not all managed by Ansible (at least not yet), so you may sometimes need to delete them all and start fresh.
To rebuild your Jitsi configuration:
- SSH into the server and do this:
- stop all Jitsi services (`systemctl stop matrix-jitsi-*`).
- remove all Jitsi configuration & data (`rm -rf /matrix/jitsi`)
- ask Ansible to set up Jitsi anew and restart services (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-jitsi,start`)

32
docs/configuring-playbook-ldap-auth.md Normal file
View file

@ -0,0 +1,32 @@
# Setting up the LDAP authentication password provider module (optional, advanced)
The playbook can install and configure the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider for you.
See that project's documentation to learn what it does and why it might be useful to you.
If you decide that you'd like to let this playbook install it for you, you need some configuration like this:
```yaml
matrix_synapse_ext_password_provider_ldap_enabled: true
matrix_synapse_ext_password_provider_ldap_uri: "ldap://ldap.mydomain.tld:389"
matrix_synapse_ext_password_provider_ldap_start_tls: true
matrix_synapse_ext_password_provider_ldap_base: "ou=users,dc=example,dc=com"
matrix_synapse_ext_password_provider_ldap_attributes_uid: "uid"
matrix_synapse_ext_password_provider_ldap_attributes_mail: "mail"
matrix_synapse_ext_password_provider_ldap_attributes_name: "cn"
matrix_synapse_ext_password_provider_ldap_bind_dn: ""
matrix_synapse_ext_password_provider_ldap_bind_password: ""
matrix_synapse_ext_password_provider_ldap_filter: ""
```
## Authenticating only using a password provider
If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it:
```yaml
matrix_synapse_password_config_localdb_enabled: false
```
## Using ma1sd Identity Server for authentication
If you wish to use the ma1sd Identity Server for LDAP authentication instead of [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) consult [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication).

135
docs/configuring-playbook-ma1sd.md Normal file
View file

@ -0,0 +1,135 @@
# Adjusting ma1sd Identity Server configuration (optional)
By default, this playbook configures an [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you.
This server is private by default, potentially at the expense of user discoverability.
*ma1sd is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.*
**Note**: enabling ma1sd (which is also the default), means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
## Disabling ma1sd
ma1sd, being an Identity Server, is not strictly needed. It is only used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some [enhanced features](https://github.com/ma1uta/ma1sd/#features).
If you'd like for the playbook to not install ma1sd (or to uninstall it if it was previously installed), you can disable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_ma1sd_enabled: false
```
## Matrix.org lookup forwarding
To ensure maximum discovery, you can make your identity server also forward lookups to the central matrix.org Identity server (at the cost of potentially leaking all your contacts information).
Enabling this is discouraged and you'd better [learn more](https://github.com/ma1uta/ma1sd/blob/master/docs/features/identity.md#lookups) before proceeding.
Enabling matrix.org forwarding can happen with the following configuration:
```yaml
matrix_ma1sd_matrixorg_forwarding_enabled: true
```
## Customizing email templates
If you'd like to change the default email templates used by ma1sd, take a look at the `matrix_ma1sd_threepid_medium_email_custom_` variables
(in the `roles/matrix-ma1sd/defaults/main.yml` file.
## ma1sd-controlled Registration
To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) feature of ma1sd, you can make use of the following variables:
- `matrix_synapse_enable_registration` - to enable user-initiated registration in Synapse
- `matrix_synapse_enable_registration_captcha` - to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring_captcha.md) documentation.
- `matrix_synapse_registrations_require_3pid` - to control the types of 3pid (`'email'`, `'msisdn'`) required by the Synapse server for registering
- variables prefixed with `matrix_nginx_proxy_proxy_matrix_3pid_registration_` (e.g. `matrix_nginx_proxy_proxy_matrix_3pid_registration_enabled`) - to configure the integrated nginx webserver to send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality
- `matrix_ma1sd_configuration_extension_yaml` - to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`.
**Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) or the `openid` APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the `openid` APIs (only!) on the federation port. Make sure the federation port (usually `https://matrix.DOMAIN:8448`) is whitelisted in your firewall (even if you don't actually use/need federation).
## Authentication
[Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver. The following configuration can be used to authenticate against an LDAP server:
```yaml
matrix_synapse_ext_password_provider_rest_auth_enabled: true
# matrix-ma1sd is the hostname of the ma1sd Docker container
matrix_synapse_ext_password_provider_rest_auth_endpoint: "http://matrix-ma1sd:8090"
matrix_ma1sd_configuration_extension_yaml: |
ldap:
enabled: true
connection:
host: ldapHostnameOrIp
tls: false
port: 389
baseDNs: ['OU=Users,DC=example,DC=org']
bindDn: CN=My ma1sd User,OU=Users,DC=example,DC=org
bindPassword: TheUserPassword
```
## Additional features
What this playbook configures for your is some bare minimum Identity Server functionality, so that you won't need to rely on external 3rd party services.
A few variables can be toggled in this playbook to alter the ma1sd configuration that gets generated.
Still, ma1sd can do much more.
You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
To use a more custom configuration, you can define a `matrix_ma1sd_configuration_extension_yaml` string variable
and put your configuration in it.
To learn more about how to do this, refer to the information about `matrix_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
## Example: SMS verification
If your use case requires mobile verification, it is quite simple to integrate ma1sd with [Twilio](https://www.twilio.com/), an online telephony services gateway. Their prices are reasonable for low-volume projects and integration can be done with the following configuration:
```yaml
matrix_ma1sd_configuration_extension_yaml: |
threepid:
medium:
msisdn:
connectors:
twilio:
account_sid: '<secret-SID>'
auth_token: '<secret-token>'
number: '+<msisdn-number>'
```
## Example: Open Registration for every Domain
If you want to open registration for any domain, you have to setup the allowed domains with ma1sd's `blacklist` and `whitelist`. The default behavior when neither the `blacklist`, nor the `whitelist` match, is to allow registration. Beware: you can't block toplevel domains (aka `.xy`) because the internal architecture of ma1sd doesn't allow that.
```yaml
matrix_ma1sd_configuration_extension_yaml: |
register:
policy:
allowed: true
threepid:
email:
domain:
blacklist: ~
whitelist: ~
```
## Troubleshooting
If email address validation emails sent by ma1sd are not reaching you, you should look into [Adjusting email-sending settings](configuring-playbook-email.md).
If you'd like additional logging information, temporarily enable verbose logging for ma1sd.
Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`):
```yaml
matrix_ma1sd_verbose_logging: true
```

92
docs/configuring-playbook-matrix-corporal.md Normal file
View file

@ -0,0 +1,92 @@
# Setting up Matrix Corporal (optional, advanced)
-------------------------------------
**WARNING**: This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal](https://github.com/devture/matrix-corporal). If you're unsure whether you have such a need, you most likely don't.
-------------------------------------
The playbook can install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you.
In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment.
See that project's documentation to learn what it does and why it might be useful to you.
If you decide that you'd like to let this playbook install it for you, you'd need to also:
- (required) [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md)
- (optional, but encouraged) [set up the REST authentication password provider module](configuring-playbook-rest-auth.md)
## Playbook configuration
You would then need some configuration like this:
```yaml
# The Shared Secret Auth password provider module is required for Corporal to work.
# See configuring-playbook-shared-secret-auth.md
matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true
matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: YOUR_SHARED_SECRET_GOES_HERE
# When matrix-corporal is acting as the primary authentication provider,
# you need to set up the REST authentication password provider module
# to make Interactive User Authentication work.
# This is necessary for certain user actions (like E2EE, device management, etc).
#
# See configuring-playbook-rest-auth.md
matrix_synapse_ext_password_provider_rest_auth_enabled: true
matrix_synapse_ext_password_provider_rest_auth_endpoint: "http://matrix-corporal:41080/_matrix/corporal"
matrix_corporal_enabled: true
matrix_corporal_policy_provider_config: |
{
"Type": "http",
"Uri": "https://intranet.example.com/matrix/policy",
"AuthorizationBearerToken": "SOME_SECRET",
"CachePath": "/var/cache/matrix-corporal/last-policy.json",
"ReloadIntervalSeconds": 1800,
"TimeoutMilliseconds": 300
}
# If you also want to enable Matrix Corporal's HTTP API..
matrix_corporal_http_api_enabled: true
matrix_corporal_http_api_auth_token: "AUTH_TOKEN_HERE"
# If you need to change matrix-corporal's user id from the default (matrix-corporal).
# In any case, you need to make sure this Matrix user is created on your server.
matrix_corporal_corporal_user_id_local_part: "matrix-corporal"
# Because Corporal peridoically performs lots of user logins from the same IP,
# you may need raise Synapse's ratelimits.
# The values below are just an example. Tweak to your use-case (number of users, etc.)
matrix_synapse_rc_login:
address:
per_second: 50
burst_count: 300
account:
per_second: 0.17
burst_count: 3
failed_attempts:
per_second: 0.17
burst_count: 3
```
Matrix Corporal operates with a specific Matrix user on your server.
By default, it's `matrix-corporal` (controllable by the `matrix_corporal_reconciliation_user_id_local_part` setting, see above).
No matter what Matrix user id you configure to run it with, make sure that:
- the Matrix Corporal user is created by [registering it](registering-users.md). Use a password you remember, as you'll need to log in from time to time to create or join rooms
- the Matrix Corporal user is joined and has Admin/Moderator-level access to any rooms you want it to manage
## Matrix Corporal files
The following local filesystem paths are mounted in the `matrix-corporal` container and can be used in your configuration (or policy):
- `/matrix/corporal/config` is mounted at `/etc/matrix-corporal` (read-only)
- `/matrix/corporal/var` is mounted at `/var/matrix-corporal` (read and write)
- `/matrix/corporal/cache` is mounted at `/var/cache/matrix-corporal` (read and write)
As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config`) needs to refer to these files via the local container paths - `/etc/matrix-corporal` (read-only), `/var/matrix-corporal` (read and write), `/var/cache/matrix-corporal` (read and write).

66
docs/configuring-playbook-matrix-registration.md Normal file
View file

@ -0,0 +1,66 @@
# Setting up matrix-registration (optional)
The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you.
> matrix-registration is a simple python application to have a token based matrix registration.
Use matrix-registration to **create unique registration links**, which people can use to register on your Matrix server. It allows you to **keep your server's registration closed (private)**, but still allow certain people (these having a special link) to register a user account.
**matrix-registration** provides 2 things:
- **an API for creating registration tokens** (unique registration links). This API can be used via `curl` or via the playbook (see [Usage](#usage) below)
- **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.DOMAIN/matrix-registration`
## Installing
Adjust your playbook configuration (your `inventory/host_vars/matrix.DOMAIN/vars.yml` file):
```yaml
matrix_registration_enabled: true
# Generate a strong secret using: `pwgen -s 64 1`.
matrix_registration_admin_secret: "ENTER_SOME_SECRET_HERE"
```
Then, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
**matrix-registration** gets exposed at `https://matrix.DOMAIN/matrix-registration`
It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) - for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using `curl`.
We make the most common APIs easy to use via the playbook (see below).
### Creating registration tokens
To **create a new user registration token (link)**, use this command:
```bash
ansible-playbook -i inventory/hosts setup.yml \
--tags=generate-matrix-registration-token \
--extra-vars="one_time=yes ex_date=2021-12-31"
```
The above command creates and returns a **one-time use** token, which **expires** on the 31st of December 2021.
Adjust the `one_time` and `ex_date` variables as you see fit.
Share the unique registration link (generated by the command above) with users to let them register on your Matrix server.
### Listing registration tokens
To **list the existing user registration tokens**, use this command:
```bash
ansible-playbook -i inventory/hosts setup.yml \
--tags=list-matrix-registration-tokens
```

84
docs/configuring-playbook-nginx.md Normal file
View file

@ -0,0 +1,84 @@
# Configure Nginx (optional, advanced)
By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
If that's alright, you can skip this.
## Using Nginx status
This will serve a statuspage to the hosting machine only. Useful for monitoring software like [longview](https://www.linode.com/docs/platform/longview/longview-app-for-nginx/)
```yaml
matrix_nginx_proxy_proxy_matrix_nginx_status_enabled: true
```
This will serve the status page under the following addresses:
- `http://matrix.DOMAIN/nginx_status` (using HTTP)
- `https://matrix.DOMAIN/nginx_status` (using HTTPS)
By default, if ```matrix_nginx_proxy_nginx_status_enabled``` is enabled, access to the status page would be allowed from the local IP address of the server. If you wish to allow access from other IP addresses, you can provide them as a list:
```yaml
matrix_nginx_proxy_proxy_matrix_nginx_status_allowed_addresses:
- 8.8.8.8
- 1.1.1.1
```
## Adjusting SSL in your server
You can adjust how the SSL is served by the nginx server using the `matrix_nginx_proxy_ssl_preset` variable. We support a few presets, based on the Mozilla Server Side TLS
Recommended configurations. These presets influence the TLS Protocol, the SSL Cipher Suites and the `ssl_prefer_server_ciphers` variable of nginx.
Possible values are:
- `"modern"` - For Modern clients that support TLS 1.3, with no need for backwards compatibility
- `"intermediate"` (**default**) - Recommended configuration for a general-purpose server
- `"old"` - Services accessed by very old clients or libraries, such as Internet Explorer 8 (Windows XP), Java 6, or OpenSSL 0.9.8
**Be really carefull when setting it to `"modern"`**. This could break comunication with other Matrix servers, limiting your federation posibilities.
Besides changing the preset (`matrix_nginx_proxy_ssl_preset`), you can also directly override these 3 variables:
- `matrix_nginx_proxy_ssl_protocols`: for specifying the supported TLS protocols.
- `matrix_nginx_proxy_ssl_prefer_server_ciphers`: for specifying if the server or the client choice when negotiating the cipher. It can set to `on` or `off`.
- `matrix_nginx_proxy_ssl_ciphers`: for specifying the SSL Cipher suites used by nginx.
For more information about these variables, check the `roles/matrix-nginx-proxy/defaults/main.yml` file.
## Synapse + OpenID Connect for Single-Sign-On
If you want to use OpenID Connect as an SSO provider (as per the [Synapse OpenID docs](https://github.com/matrix-org/synapse/blob/develop/docs/openid.md)), you need to use the following configuration (in your `vars.yml` file) to instruct nginx to forward `/_synapse/oidc` to Synapse:
```yaml
matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_oidc_api_enabled: true
```
## Disable Nginx access logs
This will disable the access logging for nginx.
```yaml
matrix_nginx_proxy_access_log_enabled: false
```
## Additional configuration
This playbook also allows for additional configuration to be applied to the nginx server.
If you want this playbook to obtain and renew certificates for other domains, then you can set the `matrix_ssl_additional_domains_to_obtain_certificates_for` variable (as mentioned in the [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) documentation as well). Make sure that you have set the DNS configuration for the domains you want to include to point at your server.
```yaml
matrix_ssl_additional_domains_to_obtain_certificates_for:
- domain.one.example
- domain.two.example
```
You can include additional nginx configuration by setting the `matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks` variable.
```yaml
matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks:
- |
# These lines will be included in the nginx configuration.
# This is at the top level of the file, so you will need to define all of the `server { ... }` blocks.
- |
# For advanced use, have a look at the template files in `roles/matrix-nginx-proxy/templates/nginx/conf.d`
```

232
docs/configuring-playbook-own-webserver.md Normal file
View file

@ -0,0 +1,232 @@
# Using your own webserver, instead of this playbook's nginx proxy (optional, advanced)
By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
If that's alright, you can skip this.
If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that,
and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can.
There are **2 ways you can go about it**, if you'd like to use your own webserver:
- [Method 1: Disabling the integrated nginx reverse-proxy webserver](#method-1-disabling-the-integrated-nginx-reverse-proxy-webserver)
- [Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy](#method-2-fronting-the-integrated-nginx-reverse-proxy-webserver-with-another-reverse-proxy)
## Method 1: Disabling the integrated nginx reverse-proxy webserver
This method is about completely disabling the integrated nginx reverse-proxy webserver and replicating its behavior using another webserver.
For an alternative, make sure to check Method #2 as well.
### Preparation
No matter which external webserver you decide to go with, you'll need to:
1) Make sure your web server user (something like `http`, `apache`, `www-data`, `nginx`) is part of the `matrix` group. You should run something like this: `usermod -a -G matrix nginx`. This allows your webserver user to access files owned by the `matrix` group. When using an external nginx webserver, this allows it to read configuration files from `/matrix/nginx-proxy/conf.d`. When using another server, it would make other files, such as `/matrix/static-files/.well-known`, accessible to it.
2) Edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to disable the integrated nginx server:
```yaml
matrix_nginx_proxy_enabled: false
```
3) **If you'll manage SSL certificates by yourself**, edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to disable SSL certificate retrieval:
```yaml
matrix_ssl_retrieval_method: none
```
**Note**: During [installation](installing.md), unless you've disabled SSL certificate management (`matrix_ssl_retrieval_method: none`), the playbook would need 80 to be available, in order to retrieve SSL certificates. **Please manually stop your other webserver while installing**. You can start it back up afterwards.
### Using your own external nginx webserver
Once you've followed the [Preparation](#preparation) guide above, it's time to set up your external nginx server.
Even with `matrix_nginx_proxy_enabled: false`, the playbook still generates some helpful files for you in `/matrix/nginx-proxy/conf.d`.
Those configuration files are adapted for use with an external web server (one not running in the container network).
You can most likely directly use the config files installed by this playbook at: `/matrix/nginx-proxy/conf.d`. Just include them in your own `nginx.conf` like this: `include /matrix/nginx-proxy/conf.d/*.conf;`
Note that if your nginx version is old, it might not like our default choice of SSL protocols (particularly the fact that the brand new `TLSv1.3` protocol is enabled). You can override the protocol list by redefining the `matrix_nginx_proxy_ssl_protocols` variable. Example:
```yaml
# Custom protocol list (removing `TLSv1.3`) to suit your nginx version.
matrix_nginx_proxy_ssl_protocols: "TLSv1.2"
```
If you are experiencing issues, try updating to a newer version of Nginx. As a data point in May 2021 a user reported that Nginx 1.14.2 was not working for them. They were getting errors about socket leaks. Updating to Nginx 1.19 fixed their issue.
### Using your own external Apache webserver
Once you've followed the [Preparation](#preparation) guide above, you can take a look at the [examples/apache](../examples/apache) directory for a sample configuration.
### Using your own external caddy webserver
After following the [Preparation](#preparation) guide above, you can take a look at the [examples/caddy](../examples/caddy) directory for a sample configuration.
### Using your own HAproxy reverse proxy
After following the [Preparation](#preparation) guide above, you can take a look at the [examples/haproxy](../examples/haproxy) directory for a sample configuration. In this case HAproxy is used as a reverse proxy and a simple Nginx container is used to serve statically `.well-known` files.
### Using another external webserver
Feel free to look at the [examples/apache](../examples/apache) directory, or the [template files in the matrix-nginx-proxy role](../roles/matrix-nginx-proxy/templates/conf.d/).
## Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy
This method is about leaving the integrated nginx reverse-proxy webserver be, but making it not get in the way (using up important ports, trying to retrieve SSL certificates, etc.).
If you wish to use another webserver, the integrated nginx reverse-proxy webserver usually gets in the way because it attempts to fetch SSL certificates and binds to ports 80, 443 and 8448 (if Matrix Federation is enabled).
You can disable such behavior and make the integrated nginx reverse-proxy webserver only serve traffic locally (or over a local network).
You would need some configuration like this:
```yaml
# Do not retrieve SSL certificates. This shall be managed by another webserver or other means.
matrix_ssl_retrieval_method: none
# Do not try to serve HTTPS, since we have no SSL certificates.
# Disabling this also means services will be served on the HTTP port
# (`matrix_nginx_proxy_container_http_host_bind_port`).
matrix_nginx_proxy_https_enabled: false
# Do not listen for HTTP on port 80 globally (default), listen on the loopback interface.
# If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
matrix_nginx_proxy_container_http_host_bind_port: '127.0.0.1:81'
# Likewise, expose the Matrix Federation port on the loopback interface.
# Since `matrix_nginx_proxy_https_enabled` is set to `false`, this federation port will serve HTTP traffic.
# If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
#
# You'd most likely need to expose it publicly on port 8448 (8449 was chosen for the local port to prevent overlap).
matrix_nginx_proxy_container_federation_host_bind_port: '127.0.0.1:8449'
# Coturn relies on SSL certificates that have already been obtained.
# Since we don't obtain any certificates (`matrix_ssl_retrieval_method: none` above), it won't work by default.
# An alternative is to tweak some of: `matrix_coturn_tls_enabled`, `matrix_coturn_tls_cert_path` and `matrix_coturn_tls_key_path`.
matrix_coturn_enabled: false
```
With this, nginx would still be in use, but it would not bother with anything SSL related or with taking up public ports.
All services would be served locally on `127.0.0.1:81` and `127.0.0.1:8449` (as per the example configuration above).
You can then set up another reverse-proxy server on ports 80/443/8448 for all of the expected domains and make traffic go to these local ports.
The expected domains vary depending on the services you have enabled (`matrix.DOMAIN` for sure; `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN` are optional).
### Sample configuration for running behind Traefik 2.0
Below is a sample configuration for using this playbook with a [Traefik](https://traefik.io/) 2.0 reverse proxy.
```yaml
# Disable generation and retrieval of SSL certs
matrix_ssl_retrieval_method: none
# Configure Nginx to only use plain HTTP
matrix_nginx_proxy_https_enabled: false
# Don't bind any HTTP or federation port to the host
# (Traefik will proxy directly into the containers)
matrix_nginx_proxy_container_http_host_bind_port: ''
matrix_nginx_proxy_container_federation_host_bind_port: ''
# Disable Coturn because it needs SSL certs
# (Clients can, though exposing IP address, use Matrix.org TURN)
matrix_coturn_enabled: false
# All containers need to be on the same Docker network as Traefik
# (This network should already exist and Traefik should be using this network)
matrix_docker_network: 'traefik'
matrix_nginx_proxy_container_extra_arguments:
# May be unnecessary depending on Traefik config, but can't hurt
- '--label "traefik.enable=true"'
# The Nginx proxy container will receive traffic from these subdomains
- '--label "traefik.http.routers.matrix-nginx-proxy.rule=Host(`{{ matrix_server_fqn_matrix }}`,`{{ matrix_server_fqn_element }}`,`{{ matrix_server_fqn_dimension }}`,`{{ matrix_server_fqn_jitsi }}`)"'
# (The 'web-secure' entrypoint must bind to port 443 in Traefik config)
- '--label "traefik.http.routers.matrix-nginx-proxy.entrypoints=web-secure"'
# (The 'default' certificate resolver must be defined in Traefik config)
- '--label "traefik.http.routers.matrix-nginx-proxy.tls.certResolver=default"'
# The Nginx proxy container uses port 8080 internally
- '--label "traefik.http.services.matrix-nginx-proxy.loadbalancer.server.port=8080"'
matrix_synapse_container_extra_arguments:
# May be unnecessary depending on Traefik config, but can't hurt
- '--label "traefik.enable=true"'
# The Synapse container will receive traffic from this subdomain
- '--label "traefik.http.routers.matrix-synapse.rule=Host(`{{ matrix_server_fqn_matrix }}`)"'
# (The 'synapse' entrypoint must bind to port 8448 in Traefik config)
- '--label "traefik.http.routers.matrix-synapse.entrypoints=synapse"'
# (The 'default' certificate resolver must be defined in Traefik config)
- '--label "traefik.http.routers.matrix-synapse.tls.certResolver=default"'
# The Synapse container uses port 8048 internally
- '--label "traefik.http.services.matrix-synapse.loadbalancer.server.port=8048"'
```
This method uses labels attached to the Nginx and Synapse containers to provide the Traefik Docker provider with the information it needs to proxy `matrix.DOMAIN`, `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN`. Some [static configuration](https://docs.traefik.io/v2.0/reference/static-configuration/file/) is required in Traefik; namely, having endpoints on ports 443 and 8448 and having a certificate resolver.
Note that this configuration on its own does **not** redirect traffic on port 80 (plain HTTP) to port 443 for HTTPS, which may cause some issues, since the built-in Nginx proxy usually does this. If you are not already doing this in Traefik, it can be added to Traefik in a [file provider](https://docs.traefik.io/v2.0/providers/file/) as follows:
```toml
[http]
[http.routers]
[http.routers.redirect-http]
entrypoints = ["web"] # The 'web' entrypoint must bind to port 80
rule = "HostRegexp(`{host:.+}`)" # Change if you don't want to redirect all hosts to HTTPS
service = "dummy" # Unused, but all routers need services (for now)
middlewares = ["https"]
[http.services]
[http.services.dummy.loadbalancer]
[[http.services.dummy.loadbalancer.servers]]
url = "localhost"
[http.middlewares]
[http.middlewares.https.redirectscheme]
scheme = "https"
permanent = true
```
You can use the following `docker-compose.yml` as example to launch Traefik.
```yaml
version: "3.3"
services:
traefik:
image: "traefik:v2.3"
restart: always
container_name: "traefik"
networks:
- traefik
command:
- "--api.insecure=true"
- "--providers.docker=true"
- "--providers.docker.network=traefik"
- "--providers.docker.exposedbydefault=false"
- "--entrypoints.web-secure.address=:443"
- "--entrypoints.synapse.address=:8448"
- "--certificatesresolvers.default.acme.tlschallenge=true"
- "--certificatesresolvers.default.acme.email=YOUR EMAIL"
- "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json"
ports:
- "443:443"
- "8448:8448"
volumes:
- "./letsencrypt:/letsencrypt"
- "/var/run/docker.sock:/var/run/docker.sock:ro"
networks:
traefik:
external: true
```

32
docs/configuring-playbook-postgres-backup.md Normal file
View file

@ -0,0 +1,32 @@
# Setting up postgres backup (optional)
The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you.
## Adjusting the playbook configuration
Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable Postgres backup:
```yaml
matrix_postgres_backup_enabled: true
```
Refer to the table below for additional configuration variables and their default values.
| Name | Default value | Description |
| :-------------------------------- | :--------------------------- | :--------------------------------------------------------------- |
|`matrix_postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
|`matrix_postgres_backup_schedule`| `'@daily'` |Cron-schedule specifying the interval between postgres backups.|
|`matrix_postgres_backup_keep_days`|`7`|Number of daily backups to keep|
|`matrix_postgres_backup_keep_weeks`|`4`|Number of weekly backups to keep|
|`matrix_postgres_backup_keep_months`|`12`|Number of monthly backups to keep|
|`matrix_postgres_backup_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Storagepath for the database backups|
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```

68
docs/configuring-playbook-prometheus-grafana.md Normal file
View file

@ -0,0 +1,68 @@
# Enabling metrics and graphs for your Matrix server (optional)
It can be useful to have some (visual) insight into the performance of your homeserver.
You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
Remember to add `stats.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
```yaml
matrix_prometheus_enabled: true
matrix_prometheus_node_exporter_enabled: true
matrix_grafana_enabled: true
matrix_grafana_anonymous_access: false
# This has no relation to your Matrix user id. It can be any username you'd like.
# Changing the username subsequently won't work.
matrix_grafana_default_admin_user: "some_username_chosen_by_you"
# Changing the password subsequently won't work.
matrix_grafana_default_admin_password: "some_strong_password_chosen_by_you"
```
By default, a [Grafana](https://grafana.com/) web user-interface will be available at `https://stats.<your-domain>`.
## What does it do?
Name | Description
-----|----------
`matrix_prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
`matrix_prometheus_node_exporter_enabled`|[Node Exporter](https://prometheus.io/docs/guides/node-exporter/) is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
`matrix_grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
`matrix_grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
`matrix_grafana_default_admin_user`<br>`matrix_grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
## Security and privacy
Metrics and resulting graphs can contain a lot of information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `matrix_prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
## Collecting metrics to an external Prometheus server
If you wish, you could expose homeserver metrics without enabling (installing) Prometheus and Grafana via the playbook. This may be useful for hooking Matrix services to an external Prometheus/Grafana installation.
To do this, you may be interested in the following variables:
Name | Description
-----|----------
`matrix_synapse_metrics_enabled`|Set this to `true` to make Synapse expose metrics (locally, on the container network)
`matrix_nginx_proxy_proxy_synapse_metrics`|Set this to `true` to make matrix-nginx-proxy expose the Synapse metrics at `https://matrix.DOMAIN/_synapse/metrics`
`matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled`|Set this to `true` to password-protect (using HTTP Basic Auth) `https://matrix.DOMAIN/_synapse/metrics` (the username is always `prometheus`, the password is defined in `matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_key`)
`matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_key`|Set this to a password to use for HTTP Basic Auth for protecting `https://matrix.DOMAIN/_synapse/metrics` (the username is always `prometheus` - it's not configurable)
`matrix_server_fqn_grafana`|Use this variable to override the domain at which the Grafana web user-interface is at (defaults to `stats.DOMAIN`).
## More information
- [Understanding Synapse Performance Issues Through Grafana Graphs](https://github.com/matrix-org/synapse/wiki/Understanding-Synapse-Performance-Issues-Through-Grafana-Graphs) at the Synapse Github Wiki
- [The Prometheus scraping rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus) (we use v2)
- [The Synapse Grafana dashboard](https://github.com/matrix-org/synapse/tree/master/contrib/grafana)
- [The Node Exporter dashboard](https://github.com/rfrail3/grafana-dashboards) (for generic non-synapse performance graphs)

29
docs/configuring-playbook-prometheus-postgres.md Normal file
View file

@ -0,0 +1,29 @@
# Enabling metrics and graphs for Postgres (optional)
Expanding on the metrics exposed by the [synapse exporter and the node exporter](configuring-playbook-prometheus-grafana.md), the playbook enables the [postgres exporter](https://github.com/prometheus-community/postgres_exporter) that exposes more detailed information about what's happening on your postgres database.
You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_prometheus_postgres_exporter_enabled: true
# the role creates a postgres user as credential. You can configure these if required:
matrix_prometheus_postgres_exporter_database_username: 'matrix_prometheus_postgres_exporter'
matrix_prometheus_postgres_exporter_database_password: 'some-password'
```
## What does it do?
Name | Description
-----|----------
`matrix_prometheus_postgres_exporter_enabled`|Enable the postgres prometheus exporter. This sets up the docker container, connects it to the database and adds a 'job' to the prometheus config which tells prometheus about this new exporter. The default is 'false'
`matrix_prometheus_postgres_exporter_database_username`| The 'username' for the user that the exporter uses to connect to the database. The default is 'matrix_prometheus_postgres_exporter'
`matrix_prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database.
## More information
- [The PostgresSQL dashboard](https://grafana.com/grafana/dashboards/9628) (generic postgres dashboard)

24
docs/configuring-playbook-rest-auth.md Normal file
View file

@ -0,0 +1,24 @@
# Setting up the REST authentication password provider module (optional, advanced)
The playbook can install and configure [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) for you.
See that project's documentation to learn what it does and why it might be useful to you.
If you decide that you'd like to let this playbook install it for you, you need some configuration like this:
```yaml
matrix_synapse_ext_password_provider_rest_auth_enabled: true
matrix_synapse_ext_password_provider_rest_auth_endpoint: "http://matrix-ma1sd:8090"
matrix_synapse_ext_password_provider_rest_auth_registration_enforce_lowercase: false
matrix_synapse_ext_password_provider_rest_auth_registration_profile_name_autofill: true
matrix_synapse_ext_password_provider_rest_auth_login_profile_name_autofill: false
```
## Authenticating only using a password provider
If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it:
```yaml
matrix_synapse_password_config_localdb_enabled: false
```

39
docs/configuring-playbook-riot-web.md Normal file
View file

@ -0,0 +1,39 @@
# Configuring Riot-web (optional)
By default, this playbook **used to install** the [Riot-web](https://github.com/vector-im/riot-web) Matrix client web application.
Riot has since been [renamed to Element](https://element.io/blog/welcome-to-element/).
- to learn more about Element and its configuration, see our dedicated [Configuring Element](configuring-playbook-client-element.md) documentation page
- to learn how to migrate from Riot to Element, see [Migrating to Element](#migrating-to-element) below
## Migrating to Element
### Migrating your custom settings
If you have custom `matrix_riot_web_` variables in your `inventory/host_vars/matrix.DOMAIN/vars.yml` file, you'll need to rename them (`matrix_riot_web_` -> `matrix_client_element_`).
Some other playbook variables (but not all) with `riot` in their name are also renamed. The playbook checks and warns if you are using the old name for some commonly used ones.
### Domain migration
We used to set up Riot at the `riot.DOMAIN` domain. The playbook now sets up Element at `element.DOMAIN` by default.
There are a few options for handling this:
- (**avoiding changes** - using the old `riot.DOMAIN` domain and avoiding DNS changes) -- to keep using `riot.DOMAIN` instead of `element.DOMAIN`, override the domain at which the playbook serves Element: `matrix_server_fqn_element: "riot.{{ matrix_domain }}"`
- (**embracing changes** - using only `element.DOMAIN`) - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.DOMAIN` in this case. If so, you may also wish to remove old SSL certificates (`rm -rf /matrix/ssl/config/live/riot.DOMAIN`) and renewal configuration (`rm -f /matrix/ssl/config/renewal/riot.DOMAIN.conf`), so that `certbot` would stop trying to renew them.
- (**embracing changes and transitioning smoothly** - using both `element.DOMAIN` and `riot.DOMAIN`) - to serve Element at the new domain (`element.DOMAIN`) and to also have `riot.DOMAIN` redirect there - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)) and enable Riot to Element redirection (`matrix_nginx_proxy_proxy_riot_compat_redirect_enabled: true`).
### Re-running the playbook
As always, after making the necessary DNS and configuration adjustments, re-run the playbook to apply the changes:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```

187
docs/configuring-playbook-s3.md Normal file
View file

@ -0,0 +1,187 @@
# Storing Matrix media files on Amazon S3 (optional)
By default, this playbook configures your server to store Synapse's content repository (`media_store`) files on the local filesystem.
If that's alright, you can skip this.
If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
Using a Goofys-backed media store works, but performance may not be ideal. If possible, try to use a region which is close to your Matrix server.
If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.
## Amazon S3
You'll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example security policy:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1400105486000",
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::your-bucket-name",
"arn:aws:s3:::your-bucket-name/*"
]
}
]
}
```
You then need to enable S3 support in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`).
It would be something like this:
```yaml
matrix_s3_media_store_enabled: true
matrix_s3_media_store_bucket_name: "your-bucket-name"
matrix_s3_media_store_aws_access_key: "access-key-goes-here"
matrix_s3_media_store_aws_secret_key: "secret-key-goes-here"
matrix_s3_media_store_region: "eu-central-1"
```
## Using other S3-compatible object stores
You can use any S3-compatible object store by **additionally** configuring these variables:
```yaml
matrix_s3_media_store_custom_endpoint_enabled: true
# Example: "https://storage.googleapis.com"
matrix_s3_media_store_custom_endpoint: "your-custom-endpoint"
```
### Backblaze B2
To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html):
- create a new **private** bucket through its user interface (you can call it something like `matrix-DOMAIN-media-store`)
- note the **Endpoint** for your bucket (something like `s3.us-west-002.backblazeb2.com`)
- adjust its lifecycle rules to use the following **custom** rules:
- File Path: *empty value*
- Days Till Hide: *empty value*
- Days Till Delete: `1`
- go to [App Keys](https://secure.backblaze.com/app_keys.htm) and use the **Add a New Application Key** to create a new one
- restrict it to the previously created bucket (e.g. `matrix-DOMAIN-media-store`)
- give it *Read & Write* access
Copy the `keyID` and `applicationKey`.
You need the following *additional* playbook configuration (on top of what you see above):
```yaml
matrix_s3_media_store_bucket_name: "YOUR_BUCKET_NAME_GOES_HERE"
matrix_s3_media_store_aws_access_key: "YOUR_keyID_GOES_HERE"
matrix_s3_media_store_aws_secret_key: "YOUR_applicationKey_GOES_HERE"
matrix_s3_media_store_custom_endpoint_enabled: true
matrix_s3_media_store_custom_endpoint: "https://s3.us-west-002.backblazeb2.com" # this may be different for your bucket
```
If you have local media store files and wish to migrate to Backblaze B2 subsequently, follow our [migration guide to Backblaze B2](#migrating-to-backblaze-b2) below instead of applying this configuration as-is.
## Migrating from local filesystem storage to S3
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before migrating your local media store to an S3-backed one.
Follow one of the guides below for a migration path from a locally-stored media store to one stored on S3-compatible storage:
- [Migrating to any S3-compatible storage (universal, but likely slow)](#migrating-to-any-s3-compatible-storage-universal-but-likely-slow)
- [Migrating to Backblaze B2](#migrating-to-backblaze-b2)
### Migrating to any S3-compatible storage (universal, but likely slow)
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
1. Proceed with the steps below without stopping Matrix services
2. Start by adding the base S3 configuration in your `vars.yml` file (seen above, may be different depending on the S3 provider of your choice)
3. In addition to the base configuration you see above, add this to your `vars.yml` file:
```yaml
matrix_s3_media_store_path: /matrix/s3-media-store
```
This enables S3 support, but mounts the S3 storage bucket to `/matrix/s3-media-store` without hooking it to your homeserver yet. Your homeserver will still continue using your local filesystem for its media store.
5. Run the playbook to apply the changes: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
6. Do an **initial sync of your files** by running this **on the server** (it may take a very long time):
```sh
sudo -u matrix -- rsync --size-only --ignore-existing -avr /matrix/synapse/storage/media-store/. /matrix/s3-media-store/.
```
You may need to install `rsync` manually.
7. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
8. Start the S3 service by running this **on the server**: `systemctl start matrix-goofys`
9. Sync the files again by re-running the `rsync` command you see in step #6
10. Stop the S3 service by running this **on the server**: `systemctl stop matrix-goofys`
11. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
12. Remove the `matrix_s3_media_store_path` configuration from your `vars.yml` file (undoing step #3 above)
13. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
14. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
15. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
### Migrating to Backblaze B2
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
1. While all Matrix services are running, run the following command on the server:
(you need to adjust the 3 `--env` line below with your own data)
```sh
docker run -it --rm -w /work \
--env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
--env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
--env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
-v /matrix/synapse/storage/media-store/:/work \
--entrypoint=/bin/sh \
docker.io/tianon/backblaze-b2:2.1.0 \
-c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET > /dev/null && b2 sync /work/ b2://$B2_BUCKET_NAME'
```
This is some initial file sync, which may take a very long time.
2. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
3. Run the command from step #1 again.
Doing this will sync any new files that may have been created locally in the meantime.
Now that Matrix services aren't running, we're sure to get Backblaze B2 and your local media store fully in sync.
4. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
5. Put the [Backblaze B2 settings seen above](#backblaze-b2) in your `vars.yml` file
6. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
7. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
8. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`

23
docs/configuring-playbook-shared-secret-auth.md Normal file
View file

@ -0,0 +1,23 @@
# Setting up the Shared Secret Auth password provider module (optional, advanced)
The playbook can install and configure [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) for you.
See that project's documentation to learn what it does and why it might be useful to you.
If you decide that you'd like to let this playbook install it for you, you need some configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`) like this:
```yaml
matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true
matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: YOUR_SHARED_SECRET_GOES_HERE
```
You can generate a strong shared secret with a command like this: `pwgen -s 64 1`
## Authenticating only using a password provider
If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it:
```yaml
matrix_synapse_password_config_localdb_enabled: false
```

97
docs/configuring-playbook-ssl-certificates.md Normal file
View file

@ -0,0 +1,97 @@
# Adjusting SSL certificate retrieval (optional, advanced)
By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (`matrix.<your-domain>` and possibly `element.<your-domain>`)
Those certificates are used when configuring the nginx reverse proxy installed by this playbook.
They can also be used for configuring [your own webserver](configuring-playbook-own-webserver.md), in case you're not using the integrated nginx server provided by the playbook.
If you need to retrieve certificates for other domains (e.g. your base domain) or more control over certificate retrieval, read below.
Things discussed in this document:
- [Using self-signed SSL certificates](#using-self-signed-ssl-certificates), if you can't use Let's Encrypt or just need a test setup
- [Using your own SSL certificates](#using-your-own-ssl-certificates), if you don't want to or can't use Let's Encrypt certificates, but are still interested in using the integrated nginx reverse proxy server
- [Not bothering with SSL certificates](#not-bothering-with-ssl-certificates), if you're using [your own webserver](configuring-playbook-own-webserver.md) and would rather this playbook leaves SSL certificate management to you
- [Obtaining SSL certificates for additional domains](#obtaining-ssl-certificates-for-additional-domains), if you'd like to host additional domains on the Matrix server and would like the playbook to help you obtain and renew certificates for those domains automatically
## Using self-signed SSL certificates
For private deployments (not publicly accessible from the internet), you may not be able to use Let's Encrypt certificates.
If self-signed certificates are alright with you, you can ask the playbook to generate such for you with the following configuration:
```yaml
matrix_ssl_retrieval_method: self-signed
```
If you get a `Cannot reach homeserver` error in Element, you will have to visit `https://matrix.<your-domain>` in your browser and agree to the certificate exception before you can login.
## Using your own SSL certificates
If you'd like to manage SSL certificates by yourself and have the playbook use your certificate files, you can use the following configuration:
```yaml
matrix_ssl_retrieval_method: manually-managed
```
With such a configuration, the playbook would expect you to drop the SSL certificate files in the directory specified by `matrix_ssl_config_dir_path` (`/matrix/ssl/config` by default) obeying the following hierarchy:
- `<matrix_ssl_config_dir_path>/live/<domain>/fullchain.pem`
- `<matrix_ssl_config_dir_path>/live/<domain>/privkey.pem`
- `<matrix_ssl_config_dir_path>/live/<domain>/chain.pem`
where `<domain>` refers to the domains that you need (usually `matrix.<your-domain>` and `element.<your-domain>`).
## Not bothering with SSL certificates
If you're [using an external web server](configuring-playbook-own-webserver.md) which is not nginx, or you would otherwise want to manage its certificates without this playbook getting in the way, you can completely disable SSL certificate management with the following configuration:
```yaml
matrix_ssl_retrieval_method: none
```
With such a configuration, no certificates will be retrieved at all. You're free to manage them however you want.
## Obtaining SSL certificates for additional domains
The playbook tries to be smart about the certificates it will obtain for you.
By default, it obtains certificates for:
- `matrix.<your-domain>` (`matrix_server_fqn_matrix`)
- possibly for `element.<your-domain>`, unless you have disabled the [Element client component](configuring-playbook-client-element.md) using `matrix_client_element_enabled: false`
- possibly for `riot.<your-domain>`, if you have explicitly enabled Riot to Element redirection (for background compatibility) using `matrix_nginx_proxy_proxy_riot_compat_redirect_enabled: true`
- possibly for `dimension.<your-domain>`, if you have explicitly [set up Dimension](configuring-playbook-dimension.md).
- possibly for `jitsi.<your-domain>`, if you have explicitly [set up Jitsi](configuring-playbook-jitsi.md).
- possibly for your base domain (`<your-domain>`), if you have explicitly configured [Serving the base domain](configuring-playbook-base-domain-serving.md)
If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too.
To do that, simply define your own custom configuration like this:
```yaml
# In this example, we retrieve 2 extra certificates,
# one for the base domain (in the `matrix_domain` variable) and one for a hardcoded domain.
# Adding any other additional domains (hosted on the same machine) is possible.
matrix_ssl_additional_domains_to_obtain_certificates_for:
- '{{ matrix_domain }}'
- 'another.domain.example.com'
```
After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually obtain certificates you should:
- make sure the web server occupying port 80 is stopped. If you are using matrix-nginx-proxy server (which is the default for this playbook), you need to stop it temporarily by running `systemctl stop matrix-nginx-proxy` on the server.
- re-run the SSL part of the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-ssl,start`
The certificate files would be made available in `/matrix/ssl/config/live/<your-other-domain>/...`.
For automated certificate renewal to work, each port `80` vhost for each domain you are obtaining certificates for needs to forward requests for `/.well-known/acme-challenge` to the certbot container we use for renewal.
See how this is configured for the `matrix.` subdomain in `/matrix/nginx-proxy/conf.d/matrix-synapse.conf`
Don't be alarmed if the above configuration file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.

71
docs/configuring-playbook-sygnal.md Normal file
View file

@ -0,0 +1,71 @@
# Setting up Sygnal (optional)
The playbook can install and configure the [Sygnal](https://github.com/matrix-org/sygnal) push gateway for you.
See the project's [documentation](https://github.com/matrix-org/sygnal) to learn what it does and why it might be useful to you.
**Note**: most people don't need to install their own gateway. As Sygnal's [Notes for application developers](https://github.com/matrix-org/sygnal/blob/master/docs/applications.md) documentation says:
> It is not feasible to allow end-users to configure their own Sygnal instance, because the Sygnal instance needs the appropriate FCM or APNs secrets that belong to the application.
This optional playbook component is only useful to people who develop/build their own Matrix client applications themselves.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
```yaml
matrix_sygnal_enabled: true
# You need at least 1 app defined.
# The configuration below is incomplete. Read more below.
matrix_sygnal_apps:
com.example.myapp.ios:
type: apns
keyfile: /data/my_key.p8
# .. more configuration ..
com.example.myapp.android:
type: gcm
api_key: your_api_key_for_gcm
# .. more configuration ..
matrix_aux_file_definitions:
- dest: "{{ matrix_sygnal_data_path }}/my_key.p8"
content: |
some
content
here
mode: '0600'
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
```
For a more complete example of available fields and values they can take, see `roles/matrix-sygnal/templates/sygnal.yaml.j2` (or the [upstream `sygnal.yaml.sample` configuration file](https://github.com/matrix-org/sygnal/blob/master/sygnal.yaml.sample)).
Configuring [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/) is easier, as it only requires that you provide some config values.
To configure [APNS](https://developer.apple.com/notifications/) (Apple Push Notification Service), you'd need to provide one or more certificate files.
To do that, the above example configuration:
- makes use of the `matrix-aux` role (and its `matrix_aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See `roles/matrix-aux/defaults/main.yml` for usage examples. It also makes sure the files are owned by `matrix:matrix`, so that Sygnal can read them. Of course, you can also install these files manually yourself, if you'd rather not use `matrix-aux`.
- references these files in the Sygnal configuration (`matrix_sygnal_apps`) using a path like `/data/..` (the `/matrix/sygnal/data` directory on the host system is mounted into the `/data` directory inside the container)
## Installing
Don't forget to add `sygnal.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
To make use of your Sygnal installation, you'd need to build your own Matrix client application, which uses the same API keys (for [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/)) and certificates (for [APNS](https://developer.apple.com/notifications/)) and is also pointed to `https://sygnal.DOMAIN` as the configured push server.
Refer to Sygnal's [Notes for application developers](https://github.com/matrix-org/sygnal/blob/master/docs/applications.md) document.

64
docs/configuring-playbook-synapse-admin.md Normal file
View file

@ -0,0 +1,64 @@
# Setting up Synapse Admin (optional)
The playbook can install and configure [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) for you.
It's a web UI tool you can use to **administrate users and rooms on your Matrix server**.
See the project's [documentation](https://github.com/Awesome-Technologies/synapse-admin) to learn what it does and why it might be useful to you.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_synapse_admin_enabled: true
```
**Note**: Synapse Admin requires Synapse's [Admin APIs](https://github.com/matrix-org/synapse/tree/master/docs/admin_api) to function. Access to them is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, for additional security, we normally leave them unexposed, following [official Synapse reverse-proxying recommendations](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints). Because Synapse Admin needs these APIs to function, when installing Synapse Admin, we **automatically** exposes them publicly for you (equivalent to `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true`).
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
After installation, Synapse Admin will be accessible at: `https://matrix.DOMAIN/synapse-admin/`
To use Synapse Admin, you need to have [registered at least one administrator account](registering-users.md) on your server.
The Homeserver URL to use on Synapse Admin's login page is: `https://matrix.DOMAIN`
### Sample configuration for running behind Traefik 2.0
Below is a sample configuration for using this playbook with a [Traefik](https://traefik.io/) 2.0 reverse proxy.
This an extension to Traefik config sample in [own-webserver-documentation](./configuring-playbook-own-webserver.md).
```yaml
# Don't bind any HTTP or federation port to the host
# (Traefik will proxy directly into the containers)
matrix_synapse_admin_container_http_host_bind_port: ""
matrix_synapse_admin_container_extra_arguments:
# May be unnecessary depending on Traefik config, but can't hurt
- '--label "traefik.enable=true"'
# The Synapse Admin container will only receive traffic from this subdomain and path
- '--label "traefik.http.routers.matrix-synapse-admin.rule=(Host(`{{ matrix_server_fqn_matrix }}`) && Path(`{{matrix_synapse_admin_public_endpoint}}`))"'
# (Define your entrypoint)
- '--label "traefik.http.routers.matrix-synapse-admin.entrypoints=web-secure"'
# (The 'default' certificate resolver must be defined in Traefik config)
- '--label "traefik.http.routers.matrix-synapse-admin.tls.certResolver=default"'
# The Synapse Admin container uses port 80 by default
- '--label "traefik.http.services.matrix-synapse-admin.loadbalancer.server.port=80"'
```

16
docs/configuring-playbook-synapse-simple-antispam.md Normal file
View file

@ -0,0 +1,16 @@
# Setting up Synapse Simple Antispam (optional, advanced)
The playbook can install and configure [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) for you.
See that project's documentation to learn what it does and why it might be useful to you.
In short, it lets you fight invite-spam by automatically blocking invitiations from a list of servers specified by you (blacklisting).
If you decide that you'd like to let this playbook install it for you, you need some configuration like this:
```yaml
matrix_synapse_ext_spam_checker_synapse_simple_antispam_enabled: true
matrix_synapse_ext_spam_checker_synapse_simple_antispam_config_blocked_homeservers:
- example.com
- another.com
```

76
docs/configuring-playbook-synapse.md Normal file
View file

@ -0,0 +1,76 @@
# Configuring Synapse (optional)
By default, this playbook configures the [Synapse](https://github.com/matrix-org/synapse) Matrix server, so that it works for the general case.
If that's enough for you, you can skip this document.
The playbook provides lots of customization variables you could use to change Synapse's settings.
Their defaults are defined in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml) and they ultimately end up in the generated `/matrix/synapse/config/homeserver.yaml` file (on the server). This file is generated from the [`roles/matrix-synapse/templates/synapse/homeserver.yaml.j2`](../roles/matrix-synapse/templates/synapse/homeserver.yaml.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
Alternatively, **if there is no pre-defined variable** for a Synapse setting you wish to change:
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Synapse's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`homeserver.yaml.j2`](../roles/matrix-synapse/templates/synapse/homeserver.yaml.j2)) by making use of the `matrix_synapse_configuration_extension_yaml` variable. You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml).
## Load balancing with workers
To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/matrix-org/synapse/blob/master/docs/workers.md).
To enable Synapse worker support, update your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_synapse_workers_enabled: true
```
We support a few configuration presets (`matrix_synapse_workers_preset: one-of-each` being the default configuration):
- `little-federation-helper` - a very minimal worker configuration to improve federation performance
- `one-of-each` - one worker of each supported type
If you'd like more customization power, you can start with one of the presets and tweak various `matrix_synapse_workers_*_count` variables manually.
If you increase worker counts too much, you may need to increase the maximum number of Postgres connections too (example):
```yaml
matrix_postgres_process_extra_arguments: [
"-c 'max_connections=200'"
]
```
If you're using the default setup (the `matrix-nginx-proxy` webserver being enabled) or you're using your own `nginx` server (which imports the configuration files generated by the playbook), you're good to go. If you use some other webserver, you may need to tweak your reverse-proxy setup manually to forward traffic to the various workers.
In case any problems occur, make sure to have a look at the [list of synapse issues about workers](https://github.com/matrix-org/synapse/issues?q=workers+in%3Atitle) and your `journalctl --unit 'matrix-*'`.
## Synapse Admin
Certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace, if you install [Synapse Admin](configuring-playbook-synapse-admin.md).
## Synapse + OpenID Connect for Single-Sign-On
If you'd like to use OpenID Connect authentication with Synapse, you'll need some additional reverse-proxy configuration (see [our nginx reverse-proxy doc page](configuring-playbook-nginx.md#synapse-openid-connect-for-single-sign-on)).
In case you encounter errors regarding the parsing of the variables, you can try to add `{% raw %}` and `{% endraw %}` blocks around them. For example ;
```
- idp_id: keycloak
idp_name: "Keycloak"
issuer: "https://url.ix/auth/realms/x"
client_id: "matrix"
client_secret: "{{ vault_synapse_keycloak }}"
scopes: ["openid", "profile"]
authorization_endpoint: "https://url.ix/auth/realms/x/protocol/openid-connect/auth"
token_endpoint: "https://url.ix/auth/realms/x/protocol/openid-connect/token"
userinfo_endpoint: "https://url.ix/auth/realms/x/protocol/openid-connect/userinfo"
user_mapping_provider:
config:
display_name_template: "{% raw %}{{ user.given_name }}{% endraw %} {% raw %}{{ user.family_name }}{% endraw %}"
email_template: "{% raw %}{{ user.email }}{% endraw %}"
```

46
docs/configuring-playbook-telemetry.md Normal file
View file

@ -0,0 +1,46 @@
# Enabling Telemetry for your Matrix server (optional)
By default, this playbook configures your Matrix homeserver to not send any telemetry data anywhere.
The [matrix.org](https://matrix.org) team would really appreciate it if you could help the project out by reporting
anonymized usage statistics from your homeserver. Only very [basic aggregate
data](#usage-statistics-being-submitted) (e.g. number of users) will be reported, but it helps track the
growth of the Matrix community, and helps to make Matrix a success.
## Enabling Telemetry
If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_synapse_report_stats: true
```
## Usage statistics being submitted
If statistics reporting is enabled, the information that gets submitted to the matrix.org team [according to the source code](https://github.com/matrix-org/synapse/blob/master/synapse/app/homeserver.py) is:
- your homeserver's domain name
- uptime of the homeserver program
- [Python](https://www.python.org/) version powering your homeserver
- total number of users on your home server (including bridged users)
- total number of native Matrix users on your home server
- total number of rooms on your homeserver
- total number of daily active users on your homeserver
- total number of daily active rooms on your homeserver
- total number of messages sent per day
- cache setting information
- CPU and memory statistics for the homeserver program
- database engine type and version

42
docs/configuring-playbook-turn.md Normal file
View file

@ -0,0 +1,42 @@
# TURN server
The playbook installs a [Coturn](https://github.com/coturn/coturn) TURN server by default, so that clients can make audio/video calls even from [NAT](https://en.wikipedia.org/wiki/Network_address_translation)-ed networks.
By default, the Synapse chat server is configured, so that it points to the Coturn TURN server installed by the playbook.
## Disabling Coturn
If, for some reason, you'd like to prevent the playbook from installing Coturn, you can use the following configuration:
```yaml
matrix_coturn_enabled: false
```
In that case, Synapse would not point to any Coturn servers and audio/video call functionality may fail.
## Using your own external Coturn server
If you'd like to use another TURN server (be it Coturn or some other one), you can configure the playbook like this:
```yaml
# Disable integrated Coturn server
matrix_coturn_enabled: false
# Point Synapse to your other Coturn server
matrix_synapse_turn_uris:
- turns:HOSTNAME_OR_IP?transport=udp
- turns:HOSTNAME_OR_IP?transport=tcp
- turn:HOSTNAME_OR_IP?transport=udp
- turn:HOSTNAME_OR_IP?transport=tcp
```
If you have or want to enable [Jitsi](configuring-playbook-jitsi.md), you might want to enable the TURN server there too.
If you do not do it, Jitsi will fall back to an upstream service.
```yaml
matrix_jitsi_web_stun_servers:
- stun:HOSTNAME_OR_IP:PORT
```
You can put multiple host/port combinations if you like.

145
docs/configuring-playbook.md Normal file
View file

@ -0,0 +1,145 @@
# Configuring the Ansible playbook
To configure the playbook, you need to have done the following things:
- have a server where Matrix services will run
- [configured your DNS records](configuring-dns.md)
- [retrieved the playbook's source code](getting-the-playbook.md) to your computer
You can then follow these steps inside the playbook directory:
1. create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)
1. copy the sample configuration file (`cp examples/vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)
1. edit the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to your liking. You may also take a look at the various `roles/ROLE_NAME_HERE/defaults/main.yml` files and see if there's something you'd like to copy over and override in your `vars.yml` configuration file.
1. copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)
1. edit the inventory hosts file (`inventory/hosts`) to your liking
For a basic Matrix installation, that's all you need.
For a more custom setup, see the [Other configuration options](#other-configuration-options) below.
When you're done with all the configuration you'd like to do, continue with [Installing](installing.md).
## Other configuration options
### Additional useful services
- [Setting up the Dimension Integration Manager](configuring-playbook-dimension.md) (optional, but recommended; after [installing](installing.md))
- [Setting up the Jitsi video-conferencing platform](configuring-playbook-jitsi.md) (optional)
- [Setting up Dynamic DNS](configuring-playbook-dynamic-dns.md) (optional)
- [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](configuring-playbook-prometheus-grafana.md) (optional)
### Core service adjustments
- [Configuring Synapse](configuring-playbook-synapse.md) (optional)
- [Configuring Element](configuring-playbook-client-element.md) (optional)
- [Storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional)
- [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) (optional)
- [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md) (optional)
- [Adjusting SSL certificate retrieval](configuring-playbook-ssl-certificates.md) (optional, advanced)
- [Serving your base domain using this playbook's nginx server](configuring-playbook-base-domain-serving.md) (optional)
- [Configure Nginx (optional, advanced)](configuring-playbook-nginx.md) (optional, advanced)
- [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional, advanced)
- [Adjusting TURN server configuration](configuring-playbook-turn.md) (optional, advanced)
### Server connectivity
- [Enabling Telemetry for your Matrix server](configuring-playbook-telemetry.md) (optional)
- [Controlling Matrix federation](configuring-playbook-federation.md) (optional)
- [Adjusting email-sending settings](configuring-playbook-email.md) (optional)
- [Setting up Hydrogen](configuring-playbook-client-hydrogen.md) - a new lightweight matrix client with legacy and mobile browser support (optional)
### Authentication and user-related
- [Setting up Synapse Admin](configuring-playbook-synapse-admin.md) (optional)
- [Setting up matrix-registration](configuring-playbook-matrix-registration.md) (optional)
- [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional, advanced)
- [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional, advanced)
- [Setting up the LDAP password provider module](configuring-playbook-ldap-auth.md) (optional, advanced)
- [Setting up Synapse Simple Antispam](configuring-playbook-synapse-simple-antispam.md) (optional, advanced)
- [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional, advanced)
### Bridging other networks
- [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md) (optional)
- [Setting up Mautrix Whatsapp bridging](configuring-playbook-bridge-mautrix-whatsapp.md) (optional)
- [Setting up Mautrix Facebook bridging](configuring-playbook-bridge-mautrix-facebook.md) (optional)
- [Setting up Mautrix Hangouts bridging](configuring-playbook-bridge-mautrix-hangouts.md) (optional)
- [Setting up Mautrix Instagram bridging](configuring-playbook-bridge-mautrix-instagram.md) (optional)
- [Setting up Mautrix Signal bridging](configuring-playbook-bridge-mautrix-signal.md) (optional)
- [Setting up Appservice IRC bridging](configuring-playbook-bridge-appservice-irc.md) (optional)
- [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md) (optional)
- [Setting up Appservice Slack bridging](configuring-playbook-bridge-appservice-slack.md) (optional)
- [Setting up Appservice Webhooks bridging](configuring-playbook-bridge-appservice-webhooks.md) (optional)
- [Setting up MX Puppet Skype bridging](configuring-playbook-bridge-mx-puppet-skype.md) (optional)
- [Setting up MX Puppet Slack bridging](configuring-playbook-bridge-mx-puppet-slack.md) (optional)
- [Setting up MX Puppet Instagram bridging](configuring-playbook-bridge-mx-puppet-instagram.md) (optional)
- [Setting up MX Puppet Twitter bridging](configuring-playbook-bridge-mx-puppet-twitter.md) (optional)
- [Setting up MX Puppet Discord bridging](configuring-playbook-bridge-mx-puppet-discord.md) (optional)
- [Setting up MX Puppet GroupMe bridging](configuring-playbook-bridge-mx-puppet-groupme.md) (optional)
- [Setting up MX Puppet Steam bridging](configuring-playbook-bridge-mx-puppet-steam.md) (optional)
- [Setting up Email2Matrix](configuring-playbook-email2matrix.md) (optional)
- [Setting up Matrix SMS bridging](configuring-playbook-bridge-matrix-bridge-sms.md) (optional)
- [Setting up Heisenbridge bouncer-style IRC bridging](configuring-playbook-bridge-heisenbridge.md) (optional)
### Bots
- [Setting up matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) - a bot to remind you about stuff (optional)
- [Setting up Go-NEB](configuring-playbook-bot-go-neb.md) - an extensible multifunctional bot (optional)
- [Setting up Mjolnir](configuring-playbook-bot-mjolnir.md) - a moderation tool/bot (optional)
### Other specialized services
- [Setting up the Sygnal push gateway](configuring-playbook-sygnal.md) (optional)

171
docs/configuring-well-known.md Normal file
View file

@ -0,0 +1,171 @@
# Configuring Service Discovery via .well-known
Service discovery is a way for the Matrix network to discover where a Matrix server is.
There are 2 types of well-known service discovery that Matrix makes use of:
- (important) **Federation Server discovery** (`/.well-known/matrix/server`) -- assists other servers in the Matrix network with finding your server. Without a proper configuration, your server will effectively not be part of the Matrix network. Learn more in [Introduction to Federation Server Discovery](#introduction-to-federation-server-discovery)
- (not that important) **Client Server discovery** (`/.well-known/matrix/client`) -- assists programs that you use to connect to your server (e.g. Element), so that they can make it more convenient for you by automatically configuring the "Homeserver URL" and "Identity Server URL" addresses. Learn more in [Introduction to Client Server Discovery](#introduction-to-client-server-discovery)
## Introduction to Federation Server Discovery
All services created by this playbook are meant to be installed on their own server (such as `matrix.<your-domain>`).
As [per the Server-Server specification](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), to use a Matrix user identifier like `@<username>:<your-domain>` while hosting services on a subdomain like `matrix.<your-domain>`, the Matrix network needs to be instructed of such delegation/redirection.
Server delegation can be configured using DNS SRV records or by setting up a `/.well-known/matrix/server` file on the base domain (`<your-domain.com>`).
Both methods have their place and will continue to do so. You only need to use just one of these delegation methods.
For simplicity reasons, our setup advocates for the `/.well-known/matrix/server` method and guides you into using that.
To learn how to set up `/.well-known/matrix/server`, read the Installing section below.
## Introduction to Client Server Discovery
Client Server Service discovery lets various client programs which support it, to receive a full user id (e.g. `@username:example.com`) and determine where the Matrix server is automatically (e.g. `https://matrix.example.com`).
This lets you (and your users) easily connect to your Matrix server without having to customize connection URLs. When using client programs that support it, you won't need to point them to `https://matrix.example.com` in Custom Server options manually anymore. The connection URL would be discovered automatically from your full username.
As [per the Client-Server specification](https://matrix.org/docs/spec/client_server/r0.4.0.html#server-discovery) Matrix does Client Server service discovery using a `/.well-known/matrix/client` file hosted on the base domain (e.g. `example.com`).
However, this playbook installs your Matrix server on another domain (e.g. `matrix.example.com`) and not on the base domain (e.g. `example.com`), so it takes a little extra manual effort to set up the file.
To learn how to set it up, read the Installing section below.
## Installing well-known files on the base domain's server
To implement the two service discovery mechanisms, your base domain's server (e.g. `example.com`) needs to run an HTTPS-capable webserver.
If you don't have a server for your base domain at all, you can use the Matrix server for this.
See [Serving the base domain](configuring-playbook-base-domain-serving.md) to learn how the playbook can help you set it up.
If you decide to go this route, you don't need to read ahead in this document. When **Serving the base domain**, the playbook takes care to serve the appropriate well-known files automatically.
If you're managing the base domain by yourself somehow, you'll need to set up serving of some `/.well-known/matrix/*` files from it via HTTPS.
To make things easy for you to set up, this playbook generates and hosts 2 well-known files on the Matrix domain's server (e.g. `https://matrix.example.com/.well-known/matrix/server` and `https://matrix.example.com/.well-known/matrix/client`), even though this is the wrong place to host them.
You have 3 options when it comes to installing the files on the base domain's server:
### (Option 1): **Copying the files manually** to your base domain's server
**Hint**: Option 2 and 3 (below) are generally a better way to do this. Make sure to go with them, if possible.
All you need to do is:
- copy `/.well-known/matrix/server` and `/.well-known/matrix/client` from the Matrix server (e.g. `matrix.example.com`) to your base domain's server (`example.com`). You can find these files in the `/matrix/static-files/.well-known/matrix` directory on the Matrix server. They are also accessible on URLs like this: `https://matrix.example.com/.well-known/matrix/server` (same for `client`).
- set up the server at your base domain (e.g. `example.com`) so that it adds an extra HTTP header when serving the `/.well-known/matrix/client` file. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the `Access-Control-Allow-Origin` header should be set with a value of `*`. If you don't do this step, web-based Matrix clients (like Element) may fail to work. Setting up headers for the `/.well-known/matrix/server` file is not necessary, as this file is only consumed by non-browsers, which don't care about CORS.
This is relatively easy to do and possibly your only choice if you can only host static files from the base domain's server.
It is, however, **a little fragile**, as future updates performed by this playbook may regenerate the well-known files and you may need to notice that and copy them over again.
### (Option 2): **Serving the base domain** from the Matrix server via the playbook
If you don't need the base domain (e.g. `example.com`) for anything else (hosting a website, etc.), you can point it to the Matrix server's IP address and tell the playbook to configure it.
This is the easiest way to set up well-known serving -- letting the playbook handle the whole base domain for you (including SSL certificates, etc.). However, if you need to use the base domain for other things (such as hosting some website, etc.), going with Option 1 or Option 3 might be more suitable.
See [Serving the base domain](configuring-playbook-base-domain-serving.md) to learn how the playbook can help you set it up.
### (Option 3): **Setting up reverse-proxying** of the well-known files from the base domain's server to the Matrix server
This option is less fragile and generally better.
On the base domain's server (e.g. `example.com`), you can set up reverse-proxying, so that any access for the `/.well-known/matrix` location prefix is forwarded to the Matrix domain's server (e.g. `matrix.example.com`).
With this method, you **don't need** to add special HTTP headers for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) reasons (like `Access-Control-Allow-Origin`), because your Matrix server (where requests ultimately go) will be configured by this playbook correctly.
**For nginx**, it would be something like this:
```nginx
# This is your HTTPS-enabled server for DOMAIN.
server {
server_name DOMAIN;
location /.well-known/matrix {
proxy_pass https://matrix.DOMAIN/.well-known/matrix;
proxy_set_header X-Forwarded-For $remote_addr;
}
# other configuration
}
```
**For Apache**, it would be something like this:
```apache
<VirtualHost *:443>
ServerName DOMAIN
SSLProxyEngine on
<Location /.well-known/matrix>
ProxyPass "https://matrix.DOMAIN/.well-known/matrix"
</Location>
# other configuration
</VirtualHost>
```
**For Caddy 2**, it would be something like this:
```caddy
reverse_proxy /.well-known/matrix/* https://matrix.DOMAIN {
header_up Host {http.reverse_proxy.upstream.hostport}
}
```
**For Caddy 1**, it would be something like this:
```caddy
proxy /.well-known/matrix/ https://matrix.DOMAIN {
header_upstream Host {http.reverse_proxy.upstream.hostport}
}
```
**For HAProxy**, it would be something like this:
```haproxy
frontend www-https
# Select a Challenge for Matrix federation redirect
acl matrix-acl path_beg /.well-known/matrix/
# Use the challenge backend if the challenge is set
use_backend matrix-backend if matrix-acl
backend matrix-backend
# Redirects the .well-known matrix to the matrix server for federation.
http-request set-header Host matrix.example.com
server matrix matrix.example.com:80
# Map url path as ProxyPass does
reqirep ^(GET|POST|HEAD)\ /.well-known/matrix/(.*) \1\ /\2
# Rewrite redirects as ProxyPassReverse does
acl response-is-redirect res.hdr(Location) -m found
rsprep ^Location:\ (http|https)://matrix.example.com\/(.*) Location:\ \1://matrix.example.com/.well-known/matrix/\2 if response-is-redirect
```
**For Netlify**, it would be something like this:
```
# In the _redirects file in the website's root
/.well-known/matrix/* https://matrix.DOMAIN/.well-known/matrix/:splat 200!
```
Make sure to:
- **replace `DOMAIN`** in the server configuration with your actual domain name
- and: to **do this for the HTTPS-enabled server block**, as that's where Matrix expects the file to be
## Confirming it works
No matter which method you've used to set up the well-known files, if you've done it correctly you should be able to see a JSON file at both of these URLs:
- `https://<domain>/.well-known/matrix/server`
- `https://<domain>/.well-known/matrix/client`
You can also check if everything is configured correctly, by [checking if services work](maintenance-checking-services.md).

103
docs/container-images.md Normal file
View file

@ -0,0 +1,103 @@
# Container Images used by the playbook
This page summarizes the container ([Docker](https://www.docker.com/)) images used by the playbook when setting up your server.
We try to stick to official images (provided by their respective projects) as much as possible.
## Container images used by default
These services are enabled and used by default, but you can turn them off, if you wish.
- [matrixdotorg/synapse](https://hub.docker.com/r/matrixdotorg/synapse/) - the official [Synapse](https://github.com/matrix-org/synapse) Matrix homeserver (optional)
- [coturn/coturn](https://hub.docker.com/r/coturn/coturn/) - the [Coturn](https://github.com/coturn/coturn) STUN/TURN server (optional)
- [vectorim/element-web](https://hub.docker.com/r/vectorim/element-web/) - the [Element](https://element.io/) web client (optional)
- [ma1uta/ma1sd](https://hub.docker.com/r/ma1uta/ma1sd/) - the [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server (optional)
- [postgres](https://hub.docker.com/_/postgres/) - the [Postgres](https://www.postgresql.org/) database server (optional)
- [devture/exim-relay](https://hub.docker.com/r/devture/exim-relay/) - the [Exim](https://www.exim.org/) email server (optional)
- [nginx](https://hub.docker.com/_/nginx/) - the [nginx](http://nginx.org/) web server (optional)
- [certbot/certbot](https://hub.docker.com/r/certbot/certbot/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) (optional)
## Optional other container images we may use
These services are not part of our default installation, but can be enabled by [configuring the playbook](configuring-playbook.md) (either before the initial installation or any time later):
- [ewoutp/goofys](https://hub.docker.com/r/ewoutp/goofys/) - the [Goofys](https://github.com/kahing/goofys) Amazon [S3](https://aws.amazon.com/s3/) file-system-mounting program (optional)
- [etherpad/etherpad](https://hub.docker.com/r/etherpad/etherpad/) - the [Etherpad](https://etherpad.org) realtime collaborative text editor that can be used in a Jitsi audio/video call or integrated as a widget into Matrix chat rooms via the Dimension integration manager (optional)
- [devture/email2matrix](https://hub.docker.com/r/devture/email2matrix/) - the [Email2Matrix](https://github.com/devture/email2matrix) email server, which can relay email messages to Matrix rooms (optional)
- [devture/matrix-corporal](https://hub.docker.com/r/devture/matrix-corporal/) - [Matrix Corporal](https://github.com/devture/matrix-corporal): reconciliator and gateway for a managed Matrix server (optional)
- [zeratax/matrix-registration](https://hub.docker.com/r/devture/zeratax-matrix-registration/) - [matrix-registration](https://github.com/ZerataX/matrix-registration): a simple python application to have a token based matrix registration (optional)
- [tulir/mautrix-telegram](https://mau.dev/tulir/mautrix-telegram/container_registry) - the [mautrix-telegram](https://github.com/tulir/mautrix-telegram) bridge to [Telegram](https://telegram.org/) (optional)
- [tulir/mautrix-whatsapp](https://mau.dev/tulir/mautrix-whatsapp/container_registry) - the [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) bridge to [Whatsapp](https://www.whatsapp.com/) (optional)
- [tulir/mautrix-facebook](https://mau.dev/tulir/mautrix-facebook/container_registry) - the [mautrix-facebook](https://github.com/tulir/mautrix-facebook) bridge to [Facebook](https://facebook.com/) (optional)
- [tulir/mautrix-hangouts](https://mau.dev/tulir/mautrix-hangouts/container_registry) - the [mautrix-hangouts](https://github.com/tulir/mautrix-hangouts) bridge to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts) (optional)
- [tulir/mautrix-instagram](https://mau.dev/tulir/mautrix-instagram/container_registry) - the [mautrix-instagram](https://github.com/tulir/mautrix-instagram) bridge to [Instagram](https://instagram.com/) (optional)
- [tulir/mautrix-signal](https://mau.dev/tulir/mautrix-signal/container_registry) - the [mautrix-signal](https://github.com/tulir/mautrix-signal) bridge to [Signal](https://www.signal.org/) (optional)
- [matrixdotorg/matrix-appservice-irc](https://hub.docker.com/r/matrixdotorg/matrix-appservice-irc) - the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) (optional)
- [halfshot/matrix-appservice-discord](https://hub.docker.com/r/halfshot/matrix-appservice-discord) - the [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) bridge to [Discord](https://discordapp.com/) (optional)
- [cadair/matrix-appservice-slack](https://hub.docker.com/r/cadair/matrix-appservice-slack) - the [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) bridge to [Slack](https://slack.com/) (optional)
- [turt2live/matrix-appservice-webhooks](https://hub.docker.com/r/turt2live/matrix-appservice-webhooks) - the [Appservice Webhooks](https://github.com/turt2live/matrix-appservice-webhooks) bridge (optional)
- [folivonet/matrix-sms-bridge](https://hub.docker.com/repository/docker/folivonet/matrix-sms-bridge) - the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) (optional)
- [sorunome/mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) - the [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) bridge to [Skype](https://www.skype.com) (optional)
- [sorunome/mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) - the [mx-puppet-slack](https://github.com/Sorunome/mx-puppet-slack) bridge to [Slack](https://slack.com) (optional)
- [sorunome/mx-puppet-instagram](https://hub.docker.com/r/sorunome/mx-puppet-instagram) - the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge to [Instagram](https://www.instagram.com) (optional)
- [sorunome/mx-puppet-twitter](https://hub.docker.com/r/sorunome/mx-puppet-twitter) - the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge to [Twitter](https://twitter.com) (optional)
- [sorunome/mx-puppet-discord](https://hub.docker.com/r/sorunome/mx-puppet-discord) - the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge to [Discord](https://discordapp.com) (optional)
- [xangelix/mx-puppet-groupme](https://hub.docker.com/r/xangelix/mx-puppet-groupme) - the [mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) bridge to [GroupMe](https://groupme.com/) (optional)
- [icewind1991/mx-puppet-steam](https://hub.docker.com/r/icewind1991/mx-puppet-steam) - the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge to [Steam](https://steampowered.com) (optional)
- [turt2live/matrix-dimension](https://hub.docker.com/r/turt2live/matrix-dimension) - the [Dimension](https://dimension.t2bot.io/) integrations manager (optional)
- [jitsi/web](https://hub.docker.com/r/jitsi/web) - the [Jitsi](https://jitsi.org/) web UI (optional)
- [jitsi/jicofo](https://hub.docker.com/r/jitsi/jicofo) - the [Jitsi](https://jitsi.org/) Focus component (optional)
- [jitsi/prosody](https://hub.docker.com/r/jitsi/prosody) - the [Jitsi](https://jitsi.org/) Prosody XMPP server component (optional)
- [jitsi/jvb](https://hub.docker.com/r/jitsi/jvb) - the [Jitsi](https://jitsi.org/) Video Bridge component (optional)
- [anoa/matrix-reminder-bot](https://hub.docker.com/r/anoa/matrix-reminder-bot) - the [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) bot for one-off & recurring reminders and alarms (optional)
- [matrixdotorg/go-neb](https://hub.docker.com/r/matrixdotorg/go-neb) - the [Go-NEB](https://github.com/matrix-org/go-neb) bot (optional)
- [matrixdotorg/mjolnir](https://hub.docker.com/r/matrixdotorg/mjolnir) - the [mjolnir](https://github.com/matrix-org/mjolnir) moderation bot (optional)
- [awesometechnologies/synapse-admin](https://hub.docker.com/r/awesometechnologies/synapse-admin) - the [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) web UI tool for administrating users and rooms on your Matrix server (optional)
- [prom/prometheus](https://hub.docker.com/r/prom/prometheus/) - [Prometheus](https://github.com/prometheus/prometheus/) is a systems and service monitoring system
- [prom/node-exporter](https://hub.docker.com/r/prom/node-exporter/) - [Prometheus Node Exporter](https://github.com/prometheus/node_exporter/) is an addon for Prometheus that gathers standard system metrics
- [grafana/grafana](https://hub.docker.com/r/grafana/grafana/) - [Grafana](https://github.com/grafana/grafana/) is a graphing tool that works well with the above two images. Our playbook also adds two dashboards for [Synapse](https://github.com/matrix-org/synapse/tree/master/contrib/grafana) and [Node Exporter](https://github.com/rfrail3/grafana-dashboards)
- [matrixdotorg/sygnal](https://hub.docker.com/r/matrixdotorg/sygnal/) - [Sygnal](https://github.com/matrix-org/sygnal) is a reference Push Gateway for Matrix

475
docs/faq.md Normal file
View file

@ -0,0 +1,475 @@
# Frequently Asked Questions
This documentation page tries to answer various Frequently Asked Questions about all things [Matrix](https://matrix.org/), with a focus on this [Ansible](https://www.ansible.com/) playbook ([What is Ansible? How does it work?](#what-is-ansible-how-does-it-work)).
This FAQ page does not intend to replace the [matrix.org FAQ](https://matrix.org/faq/) (please see that one too).
We've only started this FAQ recently, so it's still somewhat empty.
Also, we encourage you to not dig yourself into a hole by reading way too much. When you've heard enough, proceed to [Prerequisites](prerequisites.md) to get guided into installing Matrix.
## Introductory
## Where do I find more questions and answers about Matrix?
This is a Frequently Asked Questions page focused on this [Ansible](https://www.ansible.com/) playbook ([What is Ansible? How does it work?](#what-is-ansible-how-does-it-work)) for deploying a [Matrix](https://matrix.org/) server.
For a lot more generic questions and answers, see the [matrix.org FAQ](https://matrix.org/faq/).
## What is Matrix? What is Element? What is Synapse? Why are you confusing me with so many terms?
[Matrix](https://matrix.org/) is a new type of realtime communication (chat) network, the closest analogy to which is probably "email".
You don't just use the "email" protocols (SMTP, POP3, IMAP) directly though. There's a *server* somewhere which stores your data (`@gmail.com`, `@yahoo.com`, `@hotmail.com`, `@your-company.com`) and you access it by using these "email" protocols via some *client* program (Outlook, Thunderbird, some website, etc).
In the world of the Matrix chat protocol, there are various client programs. The first and currently most full-featured one is called [Element](https://element.io/) (used to be called Riot.im and Vector.im in the past). There are [many other clients](https://matrix.org/clients/). You can switch clients as much as you want until you find the one that is right for you on a given platform (you may use Element on your desktop, but Fluffychat on your phone, etc).
Matrix is also like email due to the fact that there are many servers around the world which can all talk to each other (you can send email from `@gmail.com` addresses to `@yahoo.com` and `@hotmail.com` addresses). It's the same with Matrix (`@bob:his-domain.com` can talk to `@alice:her-domain.org`).
If someone else is hosting your Matrix server (you being `@user:matrix.org` or some other public server like this), all you need is a Matrix client program, like Element.
If you'd like to host your own server (you being `@user:your-own-domain.com`), you'd need to set up a Matrix server program, like Synapse.
In short:
- Matrix is the protocol - a set of rules about how the chat network operates
- Element is a client program you can use to participate on the Matrix chat network via some server (yours or someone else's). There are also [many other client programs](https://matrix.org/clients/).
- Synapse is a server program you can use to host your very own Matrix server.
This FAQ here mostly focuses on installing various Matrix services using the Ansible automation tool. You can learn much more about Matrix in the [matrix.org FAQ](https://matrix.org/faq/).
## People I wish to talk to are not on Matrix. Can I talk to them?
You most likely can. Besides Matrix-native chats, Matrix also supports the concept of "bridging", which allows you to plug other networks into it.
This Ansible playbook can help you install [tens of bridges for various networks](configuring-playbook.md#bridging-other-networks).
Besides setting up your own bridges (preferable), you can also use some [public bridges hosted by others](https://publiclist.anchel.nl/#bridges).
## How do I get started with Matrix?
One of [Matrix](https://matrix.org/)'s distinguishing strengths (compared to other chat networks) is its decentralized nature. There's not just one entity (company, organization) controlling the servers. Rather there's thousands of servers operated by different people - one server being insecure, slow or disrespective toward its users does not affect the rest of the network. To participate in that decentralization in its fullest, consider hosting your own server or using some public server other than the largest/default one (`matrix.org`).
There are 3 ways to get into Martix, depending on your technical ability and needs:
- **using the existing default server** - the easiest way is to use an existing server. The largest public Matrix server is `matrix.org` and it's configured as a default server in clients such as [Element](https://element.io) and many others. Just use Element on the browser via that link (or download the Element app on a smartphone), create an account and start chatting.
- **using some other server** - instead of using the largest public server (`matrix.org`), you can use another public one. Here's a [list of public Matrix servers](https://publiclist.anchel.nl/) to choose from. Again, you download [Element](https://element.io) or [some other client](https://matrix.org/clients/) of your choosing and adjust the homeserver URL during login.
- **using your own server** - running your own server puts you in ultimate control of your data. It also lets you have your own user identifiers (e.g. `@bob:your-domain.com`). See [How do I set up my own Matrix server](#how-do-i-set-up-my-own-matrix-server).
### How do I set up my own Matrix server?
Normally, you'd first choose the [Matrix](https://matrix.org/) server software you'd like to run. At the time of this writing (January/2021), there's only one fully-featured server program, so there's only one reasonable choice. That's [Synapse](https://github.com/matrix-org/synapse).
There are [many guides about installing Synapse](https://matrix.org/docs/guides/#installing-synapse). Using this Ansible playbook is just one way of doing it.
Naturally, we're biased, so our usual recommendation is to go with this [Ansible](https://www.ansible.com/) playbook, instead of installing Synapse (and many many other things around it) manually.
To get started with the playbook, start at the [Prerequisites](prerequisites.md) page.
### What is Ansible? How does it work?
[Ansible](https://www.ansible.com/) is an automation program. This "playbook" is a collection of tasks/scripts that will set up a [Matrix](https://matrix.org/) server for you, so you don't have to perform these tasks manually.
We have written these automated tasks for you and all you need to do is execute them using the Ansible program.
You can install Ansible and this playbook code repository on your own computer and tell it to install Matrix services at the server living at `matrix.DOMAIN`. We recommend installing Ansible on your own computer.
Alternatively, you can download Ansible and the playbook itself directly on the `matrix.DOMAIN` server.
To learn more, see our [dedicated Ansible documentation page](ansible.md).
### Why use this playbook and not install Synapse and other things manually?
There are various guides telling you how easy it is to install [Synapse](https://github.com/matrix-org/synapse).
Reading the documentation of this Ansible playbook, you may also be thinking:
> I don't know what [Ansible](https://www.ansible.com/) is. I don't know what [Docker](https://www.docker.com/) is. This looks more complicated.
.. so you may be leaning toward [installing Synapse manually](https://github.com/matrix-org/synapse/blob/master/INSTALL.md).
The problem with a manual installation is:
- Synapse is written in Python. If not packaged for your distribution, you'd need to install various Python modules, etc., and keep them updated.
- Synapse requires a [Postgres](https://www.postgresql.org/) database (it can run on SQLite, but that's very much discouraged). So you'd need to install Postgres as well.
- you may also need a reverse-proxy server in front of it (nginx, Apache), so you'd need to be familiar with that
- SSL is required, so you'd need to obtain Let's Encrypt (or other free or non-free) certificates for one or more domain names. You'd need to be familiar with [certbot](https://certbot.eff.org/) (when using Let's Encrypt) or similar software.
- for each additional component you'd like to add (client like [Element](https://element.io), bridge to some other chat network, Integration Manager (sitckers, other services), Identity Manager, etc.), you'll need to spend extra time installing and wiring it with the rest of the system in a way that works.
- you'll likely get slower updates for all of these components, depending on your distro packaging or your own time and ability
The playbook, on the other hand, installs a bunch of components for you by default, obtains SSL certificates for you, etc. If you'd like, you can enable various bridges and other services with very little effort. All the components are wired to work together.
All services run in Docker containers (most being officially provided by each component's developers), so we're not at the mercy of distro packaging.
### Why use this playbook and not just use the Docker image directly?
Reasons are similar to the reasons for not installing manually.
Besides Synapse, you'd need other things - a Postgres database, likely the [Element](https://element.io) client, etc., etc.
Using the playbook, you get all these components in a way that works well together out of the box.
### What's different about this Ansible playbook compared to [EMnify/matrix-synapse-auto-deploy](https://github.com/EMnify/matrix-synapse-auto-deploy)?
This is similar to the [EMnify/matrix-synapse-auto-deploy](https://github.com/EMnify/matrix-synapse-auto-deploy) Ansible deployment, but:
- this one is a complete Ansible playbook (instead of just a role), so it's **easier to run** - especially for folks not familiar with Ansible
- this one installs and hooks together **a lot more Matrix-related services** for you (see above)
- this one **can be executed more than once** without causing trouble
- works on various distros: **CentOS** (7.0+), Debian-based distributions (**Debian** 9/Stretch+, **Ubuntu** 16.04+), **Archlinux**
- this one installs everything in a single directory (`/matrix` by default) and **doesn't "contaminate" your server** with files all over the place
- this one **doesn't necessarily take over** ports 80 and 443. By default, it sets up nginx for you there, but you can also [use your own webserver](configuring-playbook-own-webserver.md)
- this one **runs everything in Docker containers**, so it's likely more predictable and less fragile (see [Docker images used by this playbook](container-images.md))
- this one retrieves and automatically renews free [Let's Encrypt](https://letsencrypt.org/) **SSL certificates** for you
- this one optionally can store the `media_store` content repository files on [Amazon S3](https://aws.amazon.com/s3/) (but defaults to storing files on the server's filesystem)
- this one optionally **allows you to use an external PostgreSQL server** for Synapse's database (but defaults to running one in a container)
- helps you **import data from a previous installation** (so you can migrate your manual virtualenv/Docker setup to a more managed one)
- this one is actually **maintained**
## Server-related
### What kind of server do I need to install Matrix using this Ansible playbook?
We list our server requirements in [Prerequisites](prerequisites.md).
### Why not run Matrix on Kubernetes?
There's no reason not to run Matrix on [Kubernetes](https://kubernetes.io/).
However, that's overly complicated for thousands of us who just want to run a single small (and sometimes not so small) Matrix server, either using "cloud" servers or even a [Raspberry Pi](https://www.raspberrypi.org/) at home.
For us, a Kubernetes-based setup which requires a cluster of multiple computers and is more technically-involved is a no-go.
There are others working on automating a Matrix-on-Kubernetes setup, such as this [Helm](https://helm.sh/) chart: https://github.com/dacruz21/matrix-chart.
### Why don't you use Podman instead of Docker?
We like the philosophy of a daemonless container runtime, but [Podman](https://podman.io) is just not ready for our use case yet.
Learn more about our past experiences/attempts to give Podman a chance, by reading [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/520).
In short, `alias podman=docker` is a lie (for us).
### Why use Docker?
[Docker](https://www.docker.com/) is one of our 2 hard dependencies (the other one being [systemd](https://systemd.io/)).
It lets us run services in an isolated manner and independently of the (usually old) packages available for distributions.
It also lets us have a unified setup which runs the same across various supported distros (see them on [Prerequisites](prerequisites.md)).
### Is Docker a hard requirement?
Yes. See [Why don't you use Podman instead of Docker?](#why-dont-you-use-podman-instead-of-docker) for why we're not using another container runtime.
All of our services run in containers. It's how we achieve predictability and also how we support tens of different services across lots of distros.
The only thing we need on the distro is systemd and Python (we install Docker ourselves, unless you ask us not to).
### Why don't you use docker-compose?
Instead of using [docker-compose](https://docs.docker.com/compose/), we prefer installing systemd services and scheduling those independently.
There are people who have worked on turning this setup into a docker-compose-based one. See these experiments [here](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/64#issuecomment-603164625).
### Can I run this on a distro without systemd?
No. [systemd](https://systemd.io/) is one of our 2 hard dependencies (the other one being [Docker](https://www.docker.com/)).
### Can I install this on a Raspberry Pi?
Yes, you can. See our [Alternative Architectures](alternative-architectures.md) documentation page.
Whether a Raspberry Pi has enough power to give you a good experience is another question. It depends on your use case.
Also see: [What kind of server specs do I need?](#what-kind-of-server-specs-do-i-need).
### What kind of server specs do I need?
This largely depends on your use case. It's not so much the number of users that you plan to host, but rather the number of large rooms they will join.
Federated rooms with lots of history and containing hundreds of other servers are very heavy CPU-wise and memory-wise.
You can probably use a 1 CPU + 1GB memory server to host hundreds of local users just fine, but as soon as one of them joins a federated room like `#matrix:matrix.org` (Matrix HQ) or some IRC-bridged room (say `##linux`), your server will get the need for a lot more power (at least 2GB RAM, etc).
Running Matrix on a server with 1GB of memory is possible (especially if you disable some not-so-important services). See [How do I optimize this setup for a low-power server?](#how-do-i-optimize-this-setup-for-a-low-power-server).
**We recommend starting with a server having at least 2GB of memory** and even then using it sparingly. If you know for sure you'll be joining various large rooms, etc., then going for 4GB of memory or more is a good idea.
Besides the regular Matrix stuff, we also support things like video-conferencing using [Jitsi](configuring-playbook-jitsi.md) and other additional services which (when installed) may use up a lot of memory. Things do add up. Besides the Synapse Matrix server, Jitsi is especially notorious for consuming a lot of resources. If you plan on running Jitsi, we recommend a server with at least 2GB of memory (preferrably more). See our [Jitsi documentation page](configuring-playbook-jitsi.md) to learn how to optimize its memory/CPU usage.
### Can I run this in an LXC container?
If your distro runs within an [LXC container](https://linuxcontainers.org/), you may hit [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/703). It can be worked around, if absolutely necessary, but we suggest that you avoid running from within an LXC container.
## Configuration
### Why install my server at matrix.DOMAIN and not at the base DOMAIN?
It's the same with email servers. Your email address is likely `name@company.com`, not `name@mail.company.com`, even though it's `mail.company.com` that is really handling your data for `@company.com` email to work.
Using a separate domain name is easier to manage (although it's a little hard to get right at first) and keeps your Matrix server isolated from your website (if you have one), from your email server (if you have one), etc.
We allow `matrix.DOMAIN` to be the Matrix server handling Matrix stuff for `DOMAIN` by [Server Delegation](howto-server-delegation.md). During the installation procedure, we recommend that you set up server delegation using the [.well-known](configuring-well-known.md) method.
If you'd really like to install Matrix services directly on the base domain, see [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain).
### I don't control anything on the base domain and can't set up delegation to matrix.DOMAIN. What do I do?
If you're not in control of your base domain (or the server handling it) at all, you can take a look at [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain)
### I can't set up HTTPS on the base domain. How will I get Matrix federating?
If you really can't obtain an HTTPS certificate for your base domain, you can take a look at [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain)
### How do I install on matrix.DOMAIN without involving the base DOMAIN?
This Ansible playbook guides you into installing a server for `DOMAIN` (user identifiers are like this: `@user:DOMAIN`), while the server is at `matrix.DOMAIN`.
We allow `matrix.DOMAIN` to be the Matrix server handling Matrix stuff for `DOMAIN` by [Server Delegation](howto-server-delegation.md). During the installation procedure, we recommend that you set up server delegation using the [.well-known](configuring-well-known.md) method.
If you're fine with uglier identifiers (`@user:matrix.DOMAIN`, which is the equivalent of having an email address like `bob@mail.company.com`, instead of just `bob@company.com`), you can do that as well using the following configuration in your `vars.yml` file:
```yaml
# This is what your identifiers are like (e.g. `@bob:matrix.YOUR_BASE_DOMAIN`).
matrix_domain: "matrix.YOUR_BASE_DOMAIN"
# This is where Matrix services
matrix_server_fqn_matrix: "matrix.YOUR_BASE_DOMAIN"
# This is where you access the Element web UI from (if enabled via `matrix_client_element_enabled: true`; enabled by default).
# This and the Matrix FQN (see above) are expected to be on the same server.
#
# Feel free to use `element.matrix.YOUR_BASE_DOMAIN`, if you'd prefer that.
matrix_server_fqn_element: "element.YOUR_BASE_DOMAIN"
# This is where you access Dimension (if enabled via `matrix_dimension_enabled: true`; NOT enabled by default).
#
# Feel free to use `dimension.matrix.YOUR_BASE_DOMAIN`, if you'd prefer that.
matrix_server_fqn_dimension: "dimension.YOUR_BASE_DOMAIN"
# This is where you access Jitsi (if enabled via `matrix_jitsi_enabled: true`; NOT enabled by default).
#
# Feel free to use `jitsi.matrix.YOUR_BASE_DOMAIN`, if you'd prefer that.
matrix_server_fqn_jitsi: "jitsi.YOUR_BASE_DOMAIN"
```
### I don't use the base domain for anything. How am I supposed to set up Server Delegation for Matrix services?
If you don't use your base domain for anything, then it's hard for you to "serve files over HTTPS" on it -- something we ask you to do for the [.well-known](configuring-well-known.md) setup (needed for [Server Delegation](howto-server-delegation.md)).
Luckily, the playbook can set up your Matrix server (at `matrix.DOMAIN`) to also handle traffic for the base domain (`DOMAIN`).
See [Serving the base domain](configuring-playbook-base-domain-serving.md).
### How do I optimize this setup for a low-power server?
You can disable some not-so-important services to save on memory.
```yaml
# An identity server is not a must.
matrix_ma1sd_enabled: false
# Disabling this will prevent email-notifications and other such things from working.
matrix_mailer_enabled: false
# You can also disable this to save more RAM,
# at the expense of audio/video calls being unreliable.
matrix_coturn_enabled: false
# This makes Synapse not keep track of who is online/offline.
#
# Keeping track of this and announcing such online-status in federated rooms with
# hundreds of servers inside is insanely heavy (https://github.com/matrix-org/synapse/issues/3971).
#
# If your server does not federate with hundreds of others, enabling this doesn't hurt much.
matrix_synapse_presence_enabled: false
```
You can also consider implementing a restriction on room complexity, in order to prevent users from joining very heavy rooms:
```yaml
matrix_synapse_configuration_extension_yaml: |
limit_remote_rooms:
enabled: true
complexity: 1.0 # this limits joining complex (~large) rooms, can be
# increased, but larger values can require more RAM
```
If you've installed [Jitsi](configuring-playbook-jitsi.md) (not installed by default), there are additional optimizations listed on its documentation page that you can perform.
### I already have Docker on my server. Can you stop installing Docker via the playbook?
Yes, we can stop installing Docker ourselves. Just use this in your `vars.yml` file:
```yaml
matrix_docker_installation_enabled: true
```
### I run another webserver on the same server where I wish to install Matrix. What now?
By default, we install a webserver for you (nginx), but you can also use [your own webserver](configuring-playbook-own-webserver.md).
### How is the effective configuration determined?
Configuration variables are defined in multiple places in this playbook and are considered in this order:
- there are defaults coming from each role's defaults file (`role/matrix*/defaults/main.yml`). These variable values aim to be good defaults for when the role is used standalone (outside of this collection of roles, also called playbook).
- then, there are overrides in `group_vars/matrix_servers`, which aim to adjust these "standalone role defaults" to something which better fits the playbook in its entirety.
- finally, there's your `inventory/host_vars/matrix.DOMAIN/vars.yml` file, which is the ultimate override
### What configuration variables are available?
You can discover the variables you can override in each role (`role/matrix*/defaults/main.yml`).
As described in [How is the effective configuration determined?](#how-is-the-effective-configuration-determined), these role-defaults may be overriden by values defined in `group_vars/matrix_servers`.
Refer to both of these for inspiration. Still, as mentioned in [Configuring the playbook](configuring-playbook.md), you're only ever supposed to edit your own `inventory/host_vars/matrix.DOMAIN/vars.yml` file and nothing else inside the playbook (unless you're meaning to contribute new features).
### I'd like to adjust some configuration which doesn't have a corresponding variable. How do I do it?
The playbook doesn't aim to expose all configuration settings for all services using variables.
Doing so would amount to hundreds of variables that we have to create and maintain.
Instead, we only try to make some important basics configurable using dedicated variables you can see in each role.
See [What configuration variables are available?](#what-configuration-variables-are-available).
Besides that, each role (component) aims to provide a `matrix_SOME_COMPONENT_configuration_extension_yaml` (or `matrix_SOME_COMPONENT_configuration_extension_json`) variable, which can be used to override the configuration.
Check each role's `role/matrix*/defaults/main.yml` for the corresponding variable and an example for how use it.
## Installation
### How do I run the installation?
See [Installing](installing.md) to learn how to use Ansible to install Matrix services.
Of course, don't just jump straight to Installing. Rather, start at [Prerequisites](prerequisites.md) and get guided from there (into [setting up DNS](configuring-dns.md), [configuring the playbook](configuring-playbook.md), etc).
### I installed Synapse some other way. Can I migrate such a setup to the playbook?
Yes, you can.
You generally need to do a playbook installation (start at the [Prerequisites](prerequisites.md) page), followed by importing your existing data into it.
This Ansible playbook guides you into installing a server for `DOMAIN` (user identifiers are like this: `@user:DOMAIN`), while the server is at `matrix.DOMAIN`. If your existing setup has a server name (`server_name` configuration setting in Synapse's `homeserver.yaml` file) other than the base `DOMAIN`, you may need to tweak some additional variables. This FAQ entry may be of use if you're dealing with a more complicated setup - [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain)
After configuring the playbook and installing and **before starting** services (done with `ansible-playbook ... --tags=start`) you'd import [your SQLite](importing-synapse-sqlite.md) (or [Postgres](importing-postgres.md)) database and also [import your media store](importing-synapse-media-store.md).
### I've downloaded Ansible and the playbook on the server. It can't connect using SSH.
If you're using the playbook directly on the server, then Ansible doesn't need to connect using SSH.
It can perform a local connection instead. Just set `ansible_connection=local` at the end of the server line in `inventory/hosts` and re-run the playbook.
If you're running Ansible from within a container (one of the possibilities we list on our [dedicated Ansible documentation page](ansible.md)), then using `ansible_connection=local` is not possible.
## Troubleshooting
### I get "Error response from daemon: configured logging driver does not support reading" when I do `docker logs matrix-synapse`.
See [How can I see the logs?](#how-can-i-see-the-logs).
### How can I see the logs?
We utilize [systemd/journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html#Description) for logging.
To see logs for Synapse, run `journalctl -fu matrix-synapse.service`. You may wish to see the [manual page for journalctl](https://www.commandlinux.com/man-page/man1/journalctl.1.html).
Available service names can be seen by doing `ls /etc/systemd/system/matrix*.service` on the server.
Some services also log to files in `/matrix/*/data/..`, but we're slowly moving away from that.
We also disable Docker logging, so you can't use `docker logs matrix-*` either. We do this to prevent useless double (or even triple) logging and to avoid having to rotate log files.
We just simply delegate logging to journald and it takes care of persistence and expiring old data.
Also see: [How long do systemd/journald logs persist for?](#how-long-do-systemdjournald-logs-persist-for)
### How long do systemd/journald logs persist for?
On some distros, the journald logs are just in-memory and not persisted to disk.
Consult (and feel free to adjust) your distro's journald logging configuration in `/etc/systemd/journald.conf`.
To enable persistence and put some limits on how large the journal log files can become, adjust your configuration like this:
```ini
[Journal]
RuntimeMaxUse=200M
SystemMaxUse=1G
RateLimitInterval=0
RateLimitBurst=0
Storage=persistent
```
## Maintenance
### Do I need to do anything to keep my Matrix server updated?
Yes. We don't update anything for you automatically.
See our [documentation page about upgrading services](maintenance-upgrading-services.md).
### How do I move my existing installation to another (VM) server?
If you have an existing installation done using this Ansible playbook, you can easily migrate that to another server using [our dedicated server migration guide](maintenance-migrating.md).
If your previous installation is done in some other way (not using this Ansible playbook), see [I installed Synapse some other way. Can I migrate such a setup to the playbook?](#i-installed-synapse-some-other-way-can-i-migrate-such-a-setup-to-the-playbook).
### How do I back up the data on my server?
We haven't documented this properly yet, but the general advice is to:
- back up Postgres by making a database dump. See [Backing up PostgreSQL](maintenance-postgres.md#backing-up-postgresql)
- back up all `/matrix` files, except for `/matrix/postgres/data` (you already have a dump) and `/matrix/postgres/data-auto-upgrade-backup` (this directory may exist and contain your old data if you've [performed a major Postgres upgrade](maintenance-postgres.md#upgrading-postgresql)).
You can later restore these roughly like this:
- restore the `/matrix` directory and files on the new server manually
- run the playbook again (see [Installing](installing.md)), but **don't** start services yet (**don't run** `... --tags=start`). This step will fix any file permission mismatches and will also set up additional software (Docker, etc.) and files on the server (systemd service, etc.).
- perform a Postgres database import (see [Importing Postgres](importing-postgres.md)) to restore your database backup
- start services (see [Starting the services](installing.md#starting-the-services))
If your server's IP address has changed, you may need to [set up DNS](configuring-dns.md) again.
### What is this `/matrix/postgres/data-auto-upgrade-backup` directory that is taking up so much space?
When you [perform a major Postgres upgrade](maintenance-postgres.md#upgrading-postgresql), we save the the old data files in `/matrix/postgres/data-auto-upgrade-backup`, just so you could easily restore them should something have gone wrong.
After verifying that everything still works after the Postgres upgrade, you can safely delete `/matrix/postgres/data-auto-upgrade-backup`
### How do I debug or force SSL certificate renewal?
SSL certificate renewal normally happens automatically via [systemd timers](https://wiki.archlinux.org/index.php/Systemd/Timers).
If you're having trouble with SSL certificate renewal, you can inspect the renewal logs using:
- `journalctl -fu matrix-ssl-lets-encrypt-certificates-renew.service`
- *or* by looking at the log files in `/matrix/ssl/log/`
To trigger renewal, run: `systemctl start matrix-ssl-lets-encrypt-certificates-renew.service`. You can then take a look at the logs again.
If you're using the integrated webserver (`matrix-nginx-proxy`), you can reload it manually like this: `systemctl reload matrix-nginx-proxy`. Reloading also happens periodically via a systemd timer.
If you're [using your own webserver](configuring-playbook-own-webserver.md) instead of the integrated one (`matrix-nginx-proxy`) you may also need to reload/restart it, to make it pick up the renewed SSL certificate files.

41
docs/getting-the-playbook.md Normal file
View file

@ -0,0 +1,41 @@
# Getting the playbook
This Ansible playbook is meant to be executed on your own computer (not the Matrix server).
In special cases (if your computer cannot run Ansible, etc.) you may put the playbook on the server as well.
You can retrieve the playbook's source code by:
- [Using git to get the playbook](#using-git-to-get-the-playbook) (recommended)
- [Downloading the playbook as a ZIP archive](#downloading-the-playbook-as-a-zip-archive) (not recommended)
## Using git to get the playbook
We recommend using the [git](https://git-scm.com/) tool to get the playbook's source code, because it lets you easily keep up to date in the future when [Maintaining services](maintenance-upgrading-services.md).
Once you've installed git on your computer, you can go to any directory of your choosing and run the following command to retrieve the playbook's source code:
```bash
git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
```
This will create a new `matrix-docker-ansible-deploy` directory.
You're supposed to execute all other installation commands inside that directory.
## Downloading the playbook as a ZIP archive
Alternatively, you can download the playbook as a ZIP archive.
This is not recommended, as it's not easy to keep up to date with future updates. We suggest you [use git](#using-git-to-get-the-playbook) instead.
The latest version is always at the following URL: https://github.com/spantaleev/matrix-docker-ansible-deploy/archive/master.zip
You can extract this archive anywhere. You'll get a directory called `matrix-docker-ansible-deploy-master`.
You're supposed to execute all other installation commands inside that directory.
---------------------------------------------
No matter which method you've used to download the playbook, you can proceed by [Configuring the playbook](configuring-playbook.md).

132
docs/howto-server-delegation.md Normal file
View file

@ -0,0 +1,132 @@
# Server Delegation
To have a server on a subdomain (e.g. `matrix.<your-domain>`) handle Matrix federation traffic for the base domain (`<your-domain>`), we need to instruct the Matrix network of such a delegation.
By default, this playbook guides you into setting up [Server Delegation via a well-known file](#server-delegation-via-a-well-known-file).
However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation.
It is a complicated matter, so unless you are affected by the [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation), we suggest you stay on the simple/default path.
## Server Delegation via a well-known file
Serving a `/.well-known/matrix/server` file from the base domain is the most straightforward way to set up server delegation, but it suffers from some problems that we list in [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation).
As we already mention in [Configuring DNS](configuring-dns.md) and [Configuring Service Discovery via .well-known](configuring-well-known.md),
this playbook already properly guides you into setting up such delegation by means of a `/.well-known/matrix/server` file served from the base domain (`<your-domain>`).
If this is okay with you, feel free to not read ahead.
### Downsides of well-known-based Server Delegation
Server Delegation by means of a `/.well-known/matrix/server` file is the most straightforward, but suffers from the following downsides:
- you need to have a working HTTPS server for the base domain (`<your-domain>`). If you don't have any server for the base domain at all, you can easily solve it by making the playbook [serve the base domain from the Matrix server](configuring-playbook-base-domain-serving.md).
- any downtime on the base domain (`<your-domain>`) or network trouble between the matrix subdomain (`matrix.<your-domain>`) and the base `<domain>` may cause Matrix Federation outages. As the [Server-Server spec says](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery):
> Errors are recommended to be cached for up to an hour, and servers are encouraged to exponentially back off for repeated failures.
**For most people, this is a reasonable tradeoff** given that it's easy and straightforward to set up. We recommend you stay on this path.
Otherwise, you can decide to go against the default for this playbook, and instead set up [Server Delegation via a DNS SRV record (advanced)](#server-delegation-via-a-dns-srv-record-advanced) (much more complicated).
## Server Delegation via a DNS SRV record (advanced)
**NOTE**: doing Server Delegation via a DNS SRV record is a more **advanced** way to do it and is not the default for this playbook. This is usually **much more complicated** to set up, so **we don't recommend it**. If you're not an experience sysadmin, you'd better stay away from this.
As per the [Server-Server spec](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), it's possible to do Server Delegation using only a SRV record (without a `/.well-known/matrix/server` file).
This prevents you from suffering the [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation).
To use DNS SRV record validation, you need to:
- ensure that `/.well-known/matrix/server` is **not served** from the base domain, as that would interfere with DNS SRV record Server Delegation. To make the playbook **not** generate and serve the file, use the following configuration: `matrix_well_known_matrix_server_enabled: false`.
- ensure that you have a `_matrix._tcp` DNS SRV record for your base domain (`<your-domain>`) with a value of `10 0 8448 matrix.<your-domain>`
- ensure that you are serving the Matrix Federation API (tcp/8448) with a certificate for `<your-domain>` (not `matrix.<your-domain>`!). Getting this certificate to the `matrix.<your-domain>` server may be complicated. The playbook's automatic SSL obtaining/renewal flow will likely not work and you'll need to copy certificates around manually. See below.
### Obtaining certificates
How you can obtain a valid certificate for `<your-domain>` on the `matrix.<your-domain>` server is up to you.
If `<your-domain>` and `matrix.<your-domain>` are hosted on the same machine, you can let the playbook obtain the certificate for you, by following our [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) guide.
If `<your-domain>` and `matrix.<your-domain>` are not hosted on the same machine, you can copy over the certificate files manually.
Don't forget that they may get renewed once in a while, so you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire.
### Serving the Federation API with your certificates
Regardless of which method for obtaining certificates you've used, once you've managed to get certificates for your base domain onto the `matrix.<your-domain>` machine you can put them to use.
Based on your setup, you have different ways to go about it:
- [Serving the Federation API with your certificates and matrix-nginx-proxy](#serving-the-federation-api-with-your-certificates-and-matrix-nginx-proxy)
- [Serving the Federation API with your certificates and another webserver](#serving-the-federation-api-with-your-certificates-and-another-webserver)
- [Serving the Federation API with your certificates and Synapse handling Federation](#serving-the-federation-api-with-your-certificates-and-synapse-handling-federation)
### Serving the Federation API with your certificates and matrix-nginx-proxy
**If you are using matrix-nginx-proxy**, a reverse-proxy webserver used by default in this playbook, you only need to override the certificates used for the Matrix Federation API. You can do that using:
```yaml
# Adjust paths below to point to your certificate.
#
# NOTE: these are in-container paths. `/matrix/ssl` on the host is mounted into the container
# at the same path (`/matrix/ssl`) by default, so if that's the path you need, it would be seamless.
matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate: /matrix/ssl/config/live/<your-domain>/fullchain.pem
matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key: /matrix/ssl/config/live/<your-domain>/privkey.pem
```
If your files are not in `/matrix/ssl` but in some other location, you would need to mount them into the container:
```yaml
matrix_nginx_proxy_container_extra_arguments:
- "--mount type=bind,src=/some/path/on/the/host,dst=/some/path/inside/the/container,ro"
```
You then refer to them (for `matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate` and `matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key`) by using `/some/path/inside/the/container`.
Make sure to reload matrix-nginx-proxy once in a while (`systemctl reload matrix-nginx-proxy`), so that newer certificates can kick in.
Reloading doesn't cause any downtime.
### Serving the Federation API with your certificates and another webserver
**If you are NOT using matrix-nginx-proxy**, but rather some other webserver, you can set up reverse-proxying for the `tcp/8448` port by yourself.
Make sure to use the proper certificates for `<your-domain>` (not for `matrix.<your-domain>`) when serving the `tcp/8448` port.
Proxying needs to happen to `127.0.0.1:8048` (unencrypted Synapse federation listener).
Make sure to reload/restart your webserver once in a while, so that newer certificates can kick in.
### Serving the Federation API with your certificates and Synapse handling Federation
**Alternatively**, if you are **NOT using matrix-nginx-proxy** and **would rather not use your own webserver for Federation traffic**, you can let Synapse handle Federation by itself.
To do that, make sure the certificate files are mounted into the Synapse container:
```yaml
matrix_synapse_container_extra_arguments:
- "--mount type=bind,src=/some/path/on/the/host,dst=/some/path/inside/the/container,ro"
```
You can then tell Synapse to serve Federation traffic over TLS on `tcp/8448`:
```yaml
matrix_synapse_tls_federation_listener_enabled: true
matrix_synapse_tls_certificate_path: /some/path/inside/the/container/certificate.crt
matrix_synapse_tls_private_key_path: /some/path/inside/the/container/private.key
```
Make sure to reload Synapse once in a while (`systemctl reload matrix-synapse`), so that newer certificates can kick in.
Reloading doesn't cause any downtime.

84
docs/importing-postgres.md Normal file
View file

@ -0,0 +1,84 @@
# Importing an existing Postgres database from another installation (optional)
Run this if you'd like to import your database from a previous installation.
(don't forget to import your Synapse `media_store` files as well - see [the importing-synape-media-store guide](importing-synapse-media-store.md)).
## Prerequisites
For this to work, **the database name in Postgres must match** what this playbook uses.
This playbook uses a Postgres database name of `synapse` by default (controlled by the `matrix_synapse_database_database` variable).
If your database name differs, be sure to change `matrix_synapse_database_database` to your desired name and to re-run the playbook before proceeding.
The playbook supports importing Postgres dump files in **text** (e.g. `pg_dump > dump.sql`) or **gzipped** formats (e.g. `pg_dump | gzip -c > dump.sql.gz`).
Importing multiple databases (as dumped by `pg_dumpall`) is also supported.
Before doing the actual import, **you need to upload your Postgres dump file to the server** (any path is okay).
## Importing
To import, run this command (make sure to replace `<server-path-to-postgres-dump.sql>` with a file path on your server):
```sh
ansible-playbook -i inventory/hosts setup.yml \
--extra-vars='server_path_postgres_dump=<server-path-to-postgres-dump.sql>' \
--tags=import-postgres
```
We specify the `synapse` database as the default import database. If your dump is a single-database dump (`pg_dump`), then we need to tell it where to go to. If you're redefining `matrix_synapse_database_database` to something other than `synapse`, please adjust it here too. For database dumps spanning multiple databases (`pg_dumpall`), you can remove the `postgres_default_import_database` definition (but it doesn't hurt to keep it too).
**Note**: `<server-path-to-postgres-dump.sql>` must be a file path to a Postgres dump file on the server (not on your local machine!).
## Troubleshooting
A table ownership issue can occur if you are importing from a Synapse installation which was both:
- migrated from SQLite to Postgres, and
- used a username other than 'synapse'
In this case you may run into the following error during the import task:
```
"ERROR: role \"synapse_user\" does not exist"
```
where `synapse_user` is the database username from the previous Synapse installation.
This can be verified by examining the dump for ALTER TABLE statements which set OWNER TO that username:
```Shell
$ grep "ALTER TABLE" homeserver.sql"
ALTER TABLE public.access_tokens OWNER TO synapse_user;
ALTER TABLE public.account_data OWNER TO synapse_user;
ALTER TABLE public.account_data_max_stream_id OWNER TO synapse_user;
ALTER TABLE public.account_validity OWNER TO synapse_user;
ALTER TABLE public.application_services_state OWNER TO synapse_user;
...
```
It can be worked around by changing the username to `synapse`, for example by using `sed`:
```Shell
$ sed -i "s/synapse_user/synapse/g" homeserver.sql"
```
This uses sed to perform an 'in-place' (`-i`) replacement globally (`/g`), searching for `synapse user` and replacing with `synapse` (`s/synapse_user/synapse`). If your database username was different, change `synapse_user` to that username instead.
Note that if the previous import failed with an error it may have made changes which are incompatible with re-running the import task right away; if you do so it may fail with an error such as:
```
ERROR: relation \"access_tokens\" already exists
```
In this case you can use the command suggested in the import task to clear the database before retrying the import:
```Shell
# systemctl stop matrix-postgres
# rm -rf /matrix/postgres/data/*
# systemctl start matrix-postgres
```
Once the database is clear and the ownership of the tables has been fixed in the SQL file, the import task should succeed.

22
docs/importing-synapse-media-store.md Normal file
View file

@ -0,0 +1,22 @@
# Importing `media_store` data files from an existing Synapse installation (optional)
Run this if you'd like to import your `media_store` files from a previous installation of Synapse.
## Prerequisites
Before doing the actual data restore, **you need to upload your media store directory to the server** (any path is okay).
If you are [Storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional), restoring with this tool is not possible right now.
As an alternative, you can perform a manual restore using the [AWS CLI tool](https://aws.amazon.com/cli/) (e.g. `aws s3 sync /path/to/server/media_store/. s3://name-of-bucket/`)
**Note for Mac users**: Due to case-sensitivity issues on certain Mac filesystems (HFS or HFS+), filename corruption may occur if you copy a `media_store` directory to your Mac. If you're transferring a `media_store` directory between 2 servers, make sure you do it directly (from server to server with a tool such as [rsync](https://rsync.samba.org/)), and not by downloading the files to your Mac.
## Importing
Run this command (make sure to replace `<server-path-to-media_store>` with a path on your server):
ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_media_store=<server-path-to-media_store>' --tags=import-synapse-media-store
**Note**: `<server-path-to-media_store>` must be a file path to a `media_store` directory on the server (not on your local machine!).

26
docs/importing-synapse-sqlite.md Normal file
View file

@ -0,0 +1,26 @@
# Importing an existing SQLite database from another Synapse installation (optional)
Run this if you'd like to import your database from a previous default installation of Synapse.
(don't forget to import your `media_store` files as well - see [the importing-synapse-media-store guide](importing-synapse-media-store.md)).
While this playbook always sets up PostgreSQL, by default a Synapse installation would run
using an SQLite database.
If you have such a Synapse setup and wish to migrate it here (and over to PostgreSQL), this command is for you.
## Prerequisites
Before doing the actual import, **you need to upload your SQLite database file to the server** (any path is okay).
## Importing
Run this command (make sure to replace `<server-path-to-homeserver.db>` with a file path on your server):
ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_homeserver_db=<server-path-to-homeserver.db>' --tags=import-synapse-sqlite-db
**Notes**:
- `<server-path-to-homeserver.db>` must be a file path to a `homeserver.db` **file on the server** (not on your local machine!).
- if the SQLite database is from an older version of Synapse, the **importing procedure may run migrations on it to bring it up to date**. That is, your SQLite database file may get modified and become unusable with your older Synapse version. Keeping a copy of the original is probably wise.

54
docs/installing.md Normal file
View file

@ -0,0 +1,54 @@
# Installing
If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playbook.md), you can start the installation procedure.
Run this as-is to set up a server:
```bash
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all
```
**Note**: if you don't use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the above (and all other) Ansible commands.
**Note**: if you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to the above (and all other) Ansible commands.
The above command **doesn't start any services just yet** (another step does this later - below).
Feel free to **re-run this setup command any time** you think something is off with the server configuration.
## Things you might want to do after installing
After installing, but before starting the services, you may want to do additional things like:
- [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)
- [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)
- [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
## Starting the services
When you're ready to start the Matrix services (and set them up to auto-start in the future):
```bash
ansible-playbook -i inventory/hosts setup.yml --tags=start
```
Now that services are running, you need to **finalize the installation process** (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md)
## Things to do next
If you have started services and **finalized the installation process** (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md), you can:
- [check if services work](maintenance-checking-services.md)
- or [create your first Matrix user account](registering-users.md)
- or [set up additional services](configuring-playbook.md#other-configuration-options) (bridges to other chat networks, bots, etc.)
- or learn how to [upgrade services when new versions are released](maintenance-upgrading-services.md)
- or learn how to [maintain your server](faq.md#maintenance)
- or join some Matrix rooms:
* via the *Explore rooms* feature in Element or some other client, or by discovering them using this [matrix-static list](https://view.matrix.org). Note: joining large rooms may overload small servers.
* or come say Hi in our support room - [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting.
- or help make this playbook better by contributing (code, documentation, or [coffee/beer](https://liberapay.com/s.pantaleev/donate))

49
docs/maintenance-and-troubleshooting.md Normal file
View file

@ -0,0 +1,49 @@
# Maintenance and Troubleshooting
## How to see the current status of your services
You can check the status of your services by using `systemctl status`. Example:
```
sudo systemctl status matrix-nginx-proxy
● matrix-nginx-proxy.service - Matrix nginx proxy server
Loaded: loaded (/etc/systemd/system/matrix-nginx-proxy.service; enabled; vendor preset: enabled)
Active: active (running) since Wed 2018-11-14 19:38:35 UTC; 49min ago
```
You can see the logs by using journalctl. Example:
```
sudo journalctl -fu matrix-synapse
```
## Increasing Synapse logging
Because the [Synapse](https://github.com/matrix-org/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`.
If you'd like to debug an issue or [report a Synapse bug](https://github.com/matrix-org/synapse/issues/new/choose) to the developers, it'd be better if you temporarily increasing the logging level to `INFO`.
Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`):
```yaml
matrix_synapse_log_level: "INFO"
matrix_synapse_storage_sql_log_level: "INFO"
matrix_synapse_root_log_level: "INFO"
```
Re-run the playbook after making these configuration changes.
## Remove unused Docker data
You can free some disk space from Docker, see [docker system prune](https://docs.docker.com/engine/reference/commandline/system_prune/) for more information.
```bash
ansible-playbook -i inventory/hosts setup.yml --tags=run-docker-prune
```
## Postgres
See the dedicated [PostgreSQL Maintenance](maintenance-postgres.md) documentation page.
## Ma1sd
See the dedicated [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md) documentation page.

13
docs/maintenance-checking-services.md Normal file
View file

@ -0,0 +1,13 @@
# Checking if services work
This playbook can perform a check to ensure that you've configured things correctly and that services are running.
To perform the check, run:
```bash
ansible-playbook -i inventory/hosts setup.yml --tags=self-check
```
If it's all green, everything is probably running correctly.
Besides this self-check, you can also check your server using the [Federation Tester](https://federationtester.matrix.org/).

14
docs/maintenance-migrating.md Normal file
View file

@ -0,0 +1,14 @@
> **Note**: This migration guide is applicable if you migrate from one server to another server having the same CPU architecture (e.g. both servers being `amd64`).
>
> If you're trying to migrate between different architectures (e.g. `amd64` --> `arm64`), simply copying the complete `/matrix` directory is not possible as it would move the raw PostgreSQL data between different architectures. In this specific case, you can use the guide below as a reference, but you would also need to dump the database on your current server and import it properly on the new server. See our [Backing up PostgreSQL](maintenance-postgres.md#backing-up-postgresql) docs for help with PostgreSQL backup/restore.
# Migrating to new server
1. Prepare by lowering DNS TTL for your domains (`matrix.DOMAIN`, etc.), so that DNS record changes (step 4 below) would happen faster, leading to less downtime
2. Stop all services on the old server and make sure they won't be starting again. Execute this on the old server: `systemctl disable --now matrix*`
3. Copy directory `/matrix` from the old server to the new server. Make sure to preserve ownership and permissions (use `cp -p` or `rsync -ar`)!
4. Make sure your DNS records are adjusted to point to the new server's IP address
5. Remove old server from the `inventory/hosts` file and add new server.
6. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-system-user`. This will create the `matrix` user and group on the new server
7. Because the `matrix` user and group are created dynamically on each server, the user/group id may differ between the old and new server. We suggest that you adjust ownership of `/matrix` files manually by running this on the new server: `chown -R matrix:matrix /matrix`.
8. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` to finish the installation and start all services

159
docs/maintenance-postgres.md Normal file
View file

@ -0,0 +1,159 @@
# PostgreSQL maintenance
This document shows you how to perform various maintenance tasks related to the Postgres database server used by Matrix.
Table of contents:
- [Getting a database terminal](#getting-a-database-terminal), for when you wish to execute SQL queries
- [Vacuuming PostgreSQL](#vacuuming-postgresql), for when you wish to run a Postgres [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html) (optimizing disk space)
- [Backing up PostgreSQL](#backing-up-postgresql), for when you wish to make a backup
- [Upgrading PostgreSQL](#upgrading-postgresql), for upgrading to new major versions of PostgreSQL. Such **manual upgrades are sometimes required**.
- [Tuning PostgreSQL](#tuning-postgresql) to make it run faster
## Getting a database terminal
You can use the `/usr/local/bin/matrix-postgres-cli` tool to get interactive terminal access ([psql](https://www.postgresql.org/docs/11/app-psql.html)) to the PostgreSQL server.
If you are using an [external Postgres server](configuring-playbook-external-postgres.md), the above tool will not be available.
By default, this tool puts you in the `matrix` database, which contains nothing.
To see the available databases, run `\list` (or just `\l`).
To change to another database (for example `synapse`), run `\connect synapse` (or just `\c synapse`).
You can then proceed to write queries. Example: `SELECT COUNT(*) FROM users;`
**Be careful**. Modifying the database directly (especially as services are running) is dangerous and may lead to irreversible database corruption.
When in doubt, consider [making a backup](#backing-up-postgresql).
## Vacuuming PostgreSQL
Deleting lots data from Postgres does not make it release disk space, until you perform a `VACUUM` operation.
To perform a `FULL` Postgres [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html), run the playbook with `--tags=run-postgres-vacuum`.
Example:
```bash
ansible-playbook -i inventory/hosts setup.yml --tags=run-postgres-vacuum,start
```
**Note**: this will automatically stop Synapse temporarily and restart it later. You'll also need plenty of available disk space in your Postgres data directory (usually `/matrix/postgres/data`).
## Backing up PostgreSQL
To automatically make Postgres database backups on a fixed schedule, see [Setting up postgres backup](configuring-playbook-postgres-backup.md).
To make a one off back up of the current PostgreSQL database, make sure it's running and then execute a command like this on the server:
```bash
/usr/bin/docker exec \
--env-file=/matrix/postgres/env-postgres-psql \
matrix-postgres \
/usr/local/bin/pg_dumpall -h matrix-postgres \
| gzip -c \
> /matrix/postgres.sql.gz
```
If you are using an [external Postgres server](configuring-playbook-external-postgres.md), the above command will not work, because neither the credentials file (`/matrix/postgres/env-postgres-psql`), nor the `matrix-postgres` container is available.
Restoring a backup made this way can be done by [importing it](importing-postgres.md).
## Upgrading PostgreSQL
Unless you are using an [external Postgres server](configuring-playbook-external-postgres.md), this playbook initially installs Postgres for you.
Once installed, the playbook attempts to preserve the Postgres version it starts with.
This is because newer Postgres versions cannot start with data generated by older Postgres versions.
Upgrades must be performed manually.
This playbook can upgrade your existing Postgres setup with the following command:
ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres
**The old Postgres data directory is backed up** automatically, by renaming it to `/matrix/postgres/data-auto-upgrade-backup`.
To rename to a different path, pass some extra flags to the command above, like this: `--extra-vars="postgres_auto_upgrade_backup_data_path=/another/disk/matrix-postgres-before-upgrade"`
The auto-upgrade-backup directory stays around forever, until you **manually decide to delete it**.
As part of the upgrade, the database is dumped to `/tmp`, an upgraded and empty Postgres server is started, and then the dump is restored into the new server.
To use a different directory for the dump, pass some extra flags to the command above, like this: `--extra-vars="postgres_dump_dir=/directory/to/dump/here"`
To save disk space in `/tmp`, the dump file is gzipped on the fly at the expense of CPU usage.
If you have plenty of space in `/tmp` and would rather avoid gzipping, you can explicitly pass a dump filename which doesn't end in `.gz`.
Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`
**All databases, roles, etc. on the Postgres server are migrated**.
## Tuning PostgreSQL
PostgreSQL can be tuned to make it run faster. This is done by passing extra arguments to Postgres with the `matrix_postgres_process_extra_arguments` variable. You should use a website like https://pgtune.leopard.in.ua/ or information from https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server to determine what Postgres settings you should change.
**Note**: the configuration generator at https://pgtune.leopard.in.ua/ adds spaces around the `=` sign, which is invalid. You'll need to remove it manually (`max_connections = 300` -> `max_connections=300`)
### Here are some examples:
These are not recommended values and they may not work well for you. This is just to give you an idea of some of the options that can be set. If you are an experienced PostgreSQL admin feel free to update this documentation with better examples.
Here is an example config for a small 2 core server with 4GB of RAM and SSD storage:
```
matrix_postgres_process_extra_arguments: [
"-c shared_buffers=128MB",
"-c effective_cache_size=2304MB",
"-c effective_io_concurrency=100",
"-c random_page_cost=2.0",
"-c min_wal_size=500MB",
]
```
Here is an example config for a 4 core server with 8GB of RAM on a Virtual Private Server (VPS); the paramters have been configured using https://pgtune.leopard.in.ua with the following setup: PostgreSQL version 12, OS Type: Linux, DB Type: Mixed type of application, Data Storage: SSD storage:
```
matrix_postgres_process_extra_arguments: [
"-c max_connections=100",
"-c shared_buffers=2GB",
"-c effective_cache_size=6GB",
"-c maintenance_work_mem=512MB",
"-c checkpoint_completion_target=0.9",
"-c wal_buffers=16MB",
"-c default_statistics_target=100",
"-c random_page_cost=1.1",
"-c effective_io_concurrency=200",
"-c work_mem=5242kB",
"-c min_wal_size=1GB",
"-c max_wal_size=4GB",
"-c max_worker_processes=4",
"-c max_parallel_workers_per_gather=2",
"-c max_parallel_workers=4",
"-c max_parallel_maintenance_workers=2",
]
```
Here is an example config for a large 6 core server with 24GB of RAM:
```
matrix_postgres_process_extra_arguments: [
"-c max_connections=40",
"-c shared_buffers=1536MB",
"-c checkpoint_completion_target=0.7",
"-c wal_buffers=16MB",
"-c default_statistics_target=100",
"-c random_page_cost=1.1",
"-c effective_io_concurrency=100",
"-c work_mem=2621kB",
"-c min_wal_size=1GB",
"-c max_wal_size=4GB",
"-c max_worker_processes=6",
"-c max_parallel_workers_per_gather=3",
"-c max_parallel_workers=6",
"-c max_parallel_maintenance_workers=3",
]
```

84
docs/maintenance-synapse.md Normal file
View file

@ -0,0 +1,84 @@
# Synapse maintenance
This document shows you how to perform various maintenance tasks related to the Synapse chat server.
Table of contents:
- [Purging old data with the Purge History API](#purging-old-data-with-the-purge-history-api), for when you wish to delete in-use (but old) data from the Synapse database
- [Compressing state with rust-synapse-compress-state](#compressing-state-with-rust-synapse-compress-state)
- [Browse and manipulate the database](#browse-and-manipulate-the-database), for when you really need to take matters into your own hands
- [Make Synapse faster](#make-synapse-faster)
## Purging old data with the Purge History API
You can use the **[Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.md)** to delete old messages on a per-room basis. **This is destructive** (especially for non-federated rooms), because it means **people will no longer have access to history past a certain point**.
To make use of this API, **you'll need an admin access token** first. You can find your access token in the setting of some clients (like Element).
Alternatively, you can log in and obtain a new access token like this:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Synapse-Purge-History-API"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
Synapse's Admin API is not exposed to the internet by default. To expose it you will need to add `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true` to your `vars.yml` file.
Follow the [Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.md) documentation page for the actual purging instructions.
After deleting data, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).
## Compressing state with rust-synapse-compress-state
[rust-synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state) can be used to optimize some `_state` tables used by Synapse. If your server participates in large rooms this is the most effective way to reduce the size of your database.
This tool should be safe to use (even when Synapse is running), but it's always a good idea to [make Postgres backups](./maintenance-postgres.md#backing-up-postgresql) first.
To ask the playbook to run rust-synapse-compress-state, execute:
```
ansible-playbook -i inventory/hosts setup.yml --tags=rust-synapse-compress-state
```
By default, all rooms with more than `100000` state group rows will be compressed.
If you need to adjust this, pass: `--extra-vars='matrix_synapse_rust_synapse_compress_state_min_state_groups_required=SOME_NUMBER_HERE'` to the command above.
After state compression, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).
## Browse and manipulate the database
When the [Synapse Admin API](https://github.com/matrix-org/synapse/tree/master/docs/admin_api) and the other tools do not provide a more convenient way, having a look at synapse's postgresql database can satisfy a lot of admins' needs.
Editing the database manually is not recommended or supported by the Synapse developers. If you are going to do so you should [make a database backup](./maintenance-postgres.md#backing-up-postgresql).
First, set up an SSH tunnel to your matrix server (skip if it is your local machine):
```
# you may replace 1799 with an arbitrary port unbound on both machines
ssh -L 1799:localhost:1799 matrix.DOMAIN
```
Then start up an ephemeral [adminer](https://www.adminer.org/) container on the Matrix server, connecting it to the `matrix` network and linking the postgresql container:
```
docker run --rm --publish 1799:8080 --link matrix-postgres --net matrix adminer
```
You should then be able to browse the adminer database administration GUI at http://localhost:1799/ after entering your DB credentials (found in the `host_vars` or on the server in `{{matrix_synapse_config_dir_path}}/homeserver.yaml` under `database.args`)
⚠️ Be **very careful** with this, there is **no undo** for impromptu DB operations.
## Make Synapse faster
Synapse's presence feature which tracks which users are online and which are offline can use a lot of processing power. You can disable presence by adding `matrix_synapse_presence_enabled: false` to your `vars.yml` file.
Tuning Synapse's cache factor can help reduce RAM usage. [See the upstream documentation](https://github.com/matrix-org/synapse#help-synapse-is-slow-and-eats-all-my-ram-cpu) for more information on what value to set the cache factor to. Use the variable `matrix_synapse_caches_global_factor` to set the cache factor.
Tuning your PostgreSQL database will also make Synapse run significantly faster. See [maintenance-postgres.md##tuning-postgresql](maintenance-postgres.md##tuning-postgresql).
See also [How do I optimize this setup for a low-power server?](faq.md#how-do-i-optimize-this-setup-for-a-low-power-server).

17
docs/maintenance-upgrading-services.md Normal file
View file

@ -0,0 +1,17 @@
# Upgrading the Matrix services
This playbook not only installs the various Matrix services for you, but can also upgrade them as new versions are made available.
If you want to be notified when new versions of Synapse are released, you should join the Synapse Homeowners room: [#homeowners:matrix.org](https://matrix.to/#/#homeowners:matrix.org).
To upgrade services:
- update your playbook directory (`git pull`), so you'd obtain everything new we've done
- take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of
- re-run the [playbook setup](installing.md): `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all`
- restart the services: `ansible-playbook -i inventory/hosts setup.yml --tags=start`
**Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).

39
docs/prerequisites.md Normal file
View file

@ -0,0 +1,39 @@
# Prerequisites
To install Matrix services using this Ansible playbook, you need:
- (Recommended) An **x86** server ([What kind of server specs do I need?](faq.md#what-kind-of-server-specs-do-i-need)) running one of these operating systems:
- **CentOS** (7 only for now; [8 is not yet supported](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/300))
- **Debian** (9/Stretch or newer)
- **Ubuntu** (16.04 or newer, although [20.04 may be problematic](ansible.md#supported-ansible-versions))
- **Archlinux**
Generally, newer is better. We only strive to support released stable versions of distributions, not betas or pre-releases. This playbook can take over your whole server or co-exist with other services that you have there.
This playbook somewhat supports running on non-`amd64` architectures like ARM. See [Alternative Architectures](alternative-architectures.md).
If your distro runs within an [LXC container](https://linuxcontainers.org/), you may hit [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/703). It can be worked around, if absolutely necessary, but we suggest that you avoid running from within an LXC container.
- `root` access to your server (or a user capable of elevating to `root` via `sudo`).
- [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python3`). On some distros, Ansible may incorrectly [detect the Python version](https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html) (2 vs 3) and you may need to explicitly specify the interpreter path in `inventory/hosts` during installation (e.g. `ansible_python_interpreter=/usr/bin/python3`)
- The [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible.
- An HTTPS-capable web server at the base domain name (`<your-domain>`) which is capable of serving static files. Unless you decide to [Serve the base domain from the Matrix server](configuring-playbook-base-domain-serving.md) or alternatively, to use DNS SRV records for [Server Delegation](howto-server-delegation.md).
- Properly configured DNS records for `<your-domain>` (details in [Configuring DNS](configuring-dns.md)).
- Some TCP/UDP ports open. This playbook configures the server's internal firewall for you. In most cases, you don't need to do anything special. But **if your server is running behind another firewall**, you'd need to open these ports:
- `80/tcp`: HTTP webserver
- `443/tcp`: HTTPS webserver
- `3478/tcp`: TURN over TCP (used by Coturn)
- `3478/udp`: TURN over UDP (used by Coturn)
- `5349/tcp`: TURN over TCP (used by Coturn)
- `5349/udp`: TURN over UDP (used by Coturn)
- `8448/tcp`: Matrix Federation API HTTPS webserver. In some cases, this **may necessary even with federation disabled**. Integration Servers (like Dimension) and Identity Servers (like ma1sd) may need to access `openid` APIs on the federation port.
- the range `49152-49172/udp`: TURN over UDP
- potentially some other ports, depending on the additional (non-default) services that you enable in the **configuring the playbook** step (later on). Consult each service's documentation page in `docs/` for that.
When ready to proceed, continue with [Configuring DNS](configuring-dns.md).

70
docs/registering-users.md Normal file
View file

@ -0,0 +1,70 @@
# Registering users
This documentation page tells you how to create user account on your Matrix server.
Table of contents:
- [Registering users](#registering-users)
- [Registering users manually](#registering-users-manually)
- [Managing users via a Web UI](#managing-users-via-a-web-ui)
- [Letting certain users register on your private server](#letting-certain-users-register-on-your-private-server)
- [Enabling public user registration](#enabling-public-user-registration)
- [Adding/Removing Administrator privileges to an existing user](#addingremoving-administrator-privileges-to-an-existing-user)
## Registering users manually
You can do it via this Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user
```
**or** using the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
```
/usr/local/bin/matrix-synapse-register-user <your-username> <your-password> <admin access: 0 or 1>
```
**Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:<your-domain>` identifier.
**You can then log in with that user** via the Element service that this playbook has created for you at a URL like this: `https://element.<domain>/`.
-----
If you've just installed Matrix, **to finalize the installation process**, it's best if you proceed to [Configuring service discovery via .well-known](configuring-well-known.md)
## Managing users via a Web UI
To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md).
## Letting certain users register on your private server
If you'd rather **keep your server private** (public registration closed, as is the default), and **let certain people create accounts by themselves** (instead of creating user accounts manually like this), consider installing and making use of [matrix-registration](configuring-playbook-matrix-registration.md).
## Enabling public user registration
To **open up user registration publicly** (usually **not recommended**), consider using the following configuration:
```yaml
matrix_synapse_enable_registration: true
```
and running the [installation](installing.md) procedure once again.
If you're opening up registrations publicly like this, you might also wish to [configure CAPTCHA protection](configuring-captcha.md).
## Adding/Removing Administrator privileges to an existing user
The script `/usr/local/bin/matrix-change-user-admin-status` may be used to change a user's admin privileges.
* log on to your server with ssh
* execute with the username and 0/1 (0 = non-admin | 1 = admin)
```
/usr/local/bin/matrix-change-user-admin-status <username> <0/1>
```

36
docs/self-building.md Normal file
View file

@ -0,0 +1,36 @@
# Self-building
**Caution: self-building does not have to be used on its own. See the [Alternative Architectures](alternative-architectures.md) page.**
The playbook supports self-building of various components, which don't have a container image for your architecture (see the [container images we use](container-images.md)). For `amd64`, self-building is not required.
For other architectures (e.g. `arm32`, `arm64`), ready-made container images are used when available. If there's no ready-made image for a specific component and said component supports self-building, an image will be built on the host. Building images like this takes more time and resources (some build tools need to get installed by the playbook to assist building).
To make use of self-building, you don't need to do anything besides change your architecture variable (e.g. `matrix_architecture: arm64`). If a component has an image for the specified architecture, the playbook will use it directly. If not, it will build the image on the server itself.
Note that **not all components support self-building yet**.
List of roles where self-building the Docker image is currently possible:
- `matrix-synapse`
- `matrix-synapse-admin`
- `matrix-client-element`
- `matrix-client-hydrogen`
- `matrix-registration`
- `matrix-coturn`
- `matrix-corporal`
- `matrix-ma1sd`
- `matrix-mailer`
- `matrix-bridge-appservice-irc`
- `matrix-bridge-appservice-slack`
- `matrix-bridge-mautrix-facebook`
- `matrix-bridge-mautrix-hangouts`
- `matrix-bridge-mautrix-telegram`
- `matrix-bridge-mautrix-signal`
- `matrix-bridge-mx-puppet-skype`
- `matrix-bot-mjolnir`
- `matrix-bot-matrix-reminder-bot`
- `matrix-email2matrix`
Adding self-building support to other roles is welcome. Feel free to contribute!
If you'd like **to force self-building** even if an image is available for your architecture, look into the `matrix_*_self_build` variables provided by individual roles.

38
docs/uninstalling.md Normal file
View file

@ -0,0 +1,38 @@
# Uninstalling
**Warnings**:
- If your server federates with others, make sure to **leave any federated rooms before nuking your Matrix server's data**. Otherwise, the next time you set up a Matrix server for this domain (regardless of the installation method you use), you'll encounter trouble federating.
- If you have some trouble with your installation, you can just [re-run the playbook](installing.md) and it will try to set things up again. **Uninstalling and then installing anew rarely solves anything**.
-----------------
## Uninstalling using a script
Installing places a `/usr/local/bin/matrix-remove-all` script on the server.
You can run it to to have it uninstall things for you automatically (see below). **Use with caution!**
## Uninstalling manually
If you prefer to uninstall manually, run these commands (most are meant to be executed on the Matrix server itself):
- ensure all Matrix services are stopped: `ansible-playbook -i inventory/hosts setup.yml --tags=stop` (if you can't get Ansible working to run this command, you can run `systemctl stop 'matrix*'` manually on the server)
- delete the Matrix-related systemd `.service` and `.timer` files (`rm -f /etc/systemd/system/matrix*.{service,timer}`) and reload systemd (`systemctl daemon-reload`)
- delete some helper scripts (`rm -f /usr/local/bin/matrix*`)
- delete some cached Docker images (`docker system prune -a`) or just delete them all (`docker rmi $(docker images -aq)`)
- delete the Docker networks: `docker network rm matrix matrix-coturn` (might have been deleted already if you ran the `docker system prune` command)
- uninstall Docker itself, if necessary
- delete the `/matrix` directory (`rm -rf /matrix`)

45
docs/updating-users-passwords.md Normal file
View file

@ -0,0 +1,45 @@
# Updating users passwords
## Option 1 (if you are using the default matrix-postgres container):
You can reset a user's password via the Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password>' --tags=update-user-password
```
**Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:<your-domain>` identifier.
**You can then log in with that user** via the Element service that this playbook has created for you at a URL like this: `https://element.<domain>/`.
## Option 2 (if you are using an external Postgres server):
You can manually generate the password hash by using the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#starting-the-services)):
```
docker exec -it matrix-synapse /usr/local/bin/hash_password -c /data/homeserver.yaml
```
and then connecting to the postgres server and executing:
```
UPDATE users SET password_hash = '<password-hash>' WHERE name = '@someone:server.com'
```
where `<password-hash>` is the hash returned by the docker command above.
## Option 3:
Use the Synapse User Admin API as described here: https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#reset-password
This requires an access token from a server admin account. *This method will also log the user out of all of their clients while the other options do not.*
If you didn't make your account a server admin when you created it, you can use the `/usr/local/bin/matrix-change-user-admin-status` script as described in [registering-users.md](registering-users.md).
### Example:
To set @user:domain.com's password to `correct_horse_battery_staple` you could use this curl command:
```
curl -XPOST -d '{ "new_password": "correct_horse_battery_staple" }' "https://matrix.<domain>/_matrix/client/r0/admin/reset_password/@user:domain.com?access_token=MDA...this_is_my_access_token
```

17
examples/apache/README.md Normal file
View file

@ -0,0 +1,17 @@
# Apache reverse-proxy
This directory contains sample files that show you how to do reverse-proxying using Apache.
This is for when you wish to have your own Apache webserver sitting in front of Matrix services installed by this playbook.
See the [Using your own webserver, instead of this playbook's nginx proxy](../../docs/configuring-playbook-own-webserver.md) documentation page.
To use your own Apache reverse-proxy, you first need to disable the integrated nginx server.
You do that with the following custom configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_nginx_proxy_enabled: false
```
You can then use the configuration files from this directory as an example for how to configure your Apache server.
**NOTE**: this is just an example and may not be entirely accurate. It may also not cover other use cases (enabling various services or bridges requires additional reverse-proxying configuration).

41
examples/apache/matrix-client-element.conf Normal file
View file

@ -0,0 +1,41 @@
# This is a sample file demonstrating how to set up reverse-proxy for element.DOMAIN.
# If you're not using Element (`matrix_client_element_enabled: false`), you won't need this.
<VirtualHost *:80>
ServerName element.DOMAIN
ProxyVia On
# Map /.well-known/acme-challenge to the certbot server
# If you manage SSL certificates by yourself, this will differ.
<Location /.well-known/acme-challenge>
ProxyPreserveHost On
ProxyPass http://127.0.0.1:2402/.well-known/acme-challenge
</Location>
Redirect permanent / https://element.DOMAIN/
</VirtualHost>
<VirtualHost *:443>
ServerName element.DOMAIN
SSLEngine On
# If you manage SSL certificates by yourself, these paths will differ.
SSLCertificateFile /matrix/ssl/config/live/element.DOMAIN/fullchain.pem
SSLCertificateKeyFile /matrix/ssl/config/live/element.DOMAIN/privkey.pem
SSLProxyEngine on
SSLProxyProtocol +TLSv1.2 +TLSv1.3
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
ProxyPreserveHost On
ProxyRequests Off
ProxyVia On
ProxyPass / http://127.0.0.1:8765/
ProxyPassReverse / http://127.0.0.1:8765/
ErrorLog ${APACHE_LOG_DIR}/element.DOMAIN-error.log
CustomLog ${APACHE_LOG_DIR}/element.DOMAIN-access.log combined
</VirtualHost>

41
examples/apache/matrix-dimension.conf Normal file
View file

@ -0,0 +1,41 @@
# This is a sample file demonstrating how to set up reverse-proxy for dimension.DOMAIN.
# If you're not using Dimension (`matrix_dimension_enabled: false`, which is also the default), you won't need this.
<VirtualHost *:80>
ServerName dimension.DOMAIN
ProxyVia On
# Map /.well-known/acme-challenge to the certbot server
# If you manage SSL certificates by yourself, this will differ.
<Location /.well-known/acme-challenge>
ProxyPreserveHost On
ProxyPass http://127.0.0.1:2402/.well-known/acme-challenge
</Location>
Redirect permanent / https://dimension.DOMAIN/
</VirtualHost>
<VirtualHost *:443>
ServerName dimension.DOMAIN
SSLEngine On
# If you manage SSL certificates by yourself, these paths will differ.
SSLCertificateFile /matrix/ssl/config/live/dimension.DOMAIN/fullchain.pem
SSLCertificateKeyFile /matrix/ssl/config/live/dimension.DOMAIN/privkey.pem
SSLProxyEngine on
SSLProxyProtocol +TLSv1.2 +TLSv1.3
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
ProxyPreserveHost On
ProxyRequests Off
ProxyVia On
ProxyPass / http://127.0.0.1:8184/
ProxyPassReverse / http://127.0.0.1:8184/
ErrorLog ${APACHE_LOG_DIR}/dimension.DOMAIN-error.log
CustomLog ${APACHE_LOG_DIR}/dimension.DOMAIN-access.log combined
</VirtualHost>

134
examples/apache/matrix-synapse.conf Normal file
View file

@ -0,0 +1,134 @@
# This is a sample file demonstrating how to set up reverse-proxy for matrix.DOMAIN
<VirtualHost *:80>
ServerName matrix.DOMAIN
ProxyVia On
# Map /.well-known/acme-challenge to the certbot server
# If you manage SSL certificates by yourself, this will differ.
<Location /.well-known/acme-challenge>
ProxyPreserveHost On
ProxyPass http://127.0.0.1:2402/.well-known/acme-challenge
</Location>
Redirect permanent / https://matrix.DOMAIN/
</VirtualHost>
# Client-Server API
<VirtualHost *:443>
ServerName matrix.DOMAIN
SSLEngine On
# If you manage SSL certificates by yourself, these paths will differ.
SSLCertificateFile /matrix/ssl/config/live/matrix.DOMAIN/fullchain.pem
SSLCertificateKeyFile /matrix/ssl/config/live/matrix.DOMAIN/privkey.pem
SSLProxyEngine on
SSLProxyProtocol +TLSv1.2 +TLSv1.3
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
ProxyPreserveHost On
ProxyRequests Off
ProxyVia On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
# Keep some URIs free for different proxy/location
ProxyPassMatch ^/.well-known/matrix/client !
ProxyPassMatch ^/.well-known/matrix/server !
ProxyPassMatch ^/_matrix/identity !
ProxyPassMatch ^/_matrix/client/r0/user_directory/search !
# Proxy all remaining traffic to Synapse
AllowEncodedSlashes NoDecode
ProxyPass /_matrix http://127.0.0.1:8008/_matrix retry=0 nocanon
ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
ProxyPass /_synapse/client http://127.0.0.1:8008/_synapse/client retry=0 nocanon
ProxyPassReverse /_synapse/client http://127.0.0.1:8008/_synapse/client
# Proxy Admin API (necessary for Synapse-Admin)
# ProxyPass /_synapse/admin http://127.0.0.1:8008/_synapse/admin retry=0 nocanon
# ProxyPassReverse /_synapse/admin http://127.0.0.1:8008/_synapse/admin
# Proxy Synapse-Admin
# ProxyPass /synapse-admin http://127.0.0.1:8766 retry=0 nocanon
# ProxyPassReverse /synapse-admin http://127.0.0.1:8766
# Map /.well-known/matrix/client for client discovery
Alias /.well-known/matrix/client /matrix/static-files/.well-known/matrix/client
<Files "/matrix/static-files/.well-known/matrix/client">
Require all granted
</Files>
<Location "/.well-known/matrix/client">
Header always set Content-Type "application/json"
Header always set Access-Control-Allow-Origin "*"
</Location>
# Map /.well-known/matrix/server for server discovery
Alias /.well-known/matrix/server /matrix/static-files/.well-known/matrix/server
<Files "/matrix/static-files/.well-known/matrix/server">
Require all granted
</Files>
<Location "/.well-known/matrix/server">
Header always set Content-Type "application/json"
</Location>
<Directory /matrix/static-files/.well-known/matrix/>
AllowOverride All
# Apache 2.4:
Require all granted
# Or for Apache 2.2:
#order allow,deny
</Directory>
# Map /_matrix/identity to the identity server
<Location /_matrix/identity>
ProxyPass http://127.0.0.1:8090/_matrix/identity nocanon
</Location>
# Map /_matrix/client/r0/user_directory/search to the identity server
<Location /_matrix/client/r0/user_directory/search>
ProxyPass http://127.0.0.1:8090/_matrix/client/r0/user_directory/search nocanon
</Location>
ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log
CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined
</VirtualHost>
# Server-Server (federation) API
# Use this apache reverse proxy template to enable matrix server-to-server federation traffic
# Be sure that network traffic on port 8448 is possible
#
# You can check your federation config at https://federationtester.matrix.org/
# Enter there your base DOMAIN address, NOT your matrix.DOMAIN address, ex. https://DOMAIN
#
# In this example we use all services on the same machine (127.0.0.1) but you can do this with different machines.
# If you do so be sure to reach the destinated IPADRESS and the correspondending port. Check this with netstat, nmap or your favourite tool.
Listen 8448
<VirtualHost *:8448>
ServerName matrix.DOMAIN
SSLEngine On
# If you manage SSL certificates by yourself, these paths will differ.
SSLCertificateFile /matrix/ssl/config/live/matrix.DOMAIN/fullchain.pem
SSLCertificateKeyFile /matrix/ssl/config/live/matrix.DOMAIN/privkey.pem
SSLProxyEngine on
SSLProxyProtocol +TLSv1.2 +TLSv1.3
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
ProxyPreserveHost On
ProxyRequests Off
ProxyVia On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
# Proxy all remaining traffic to the Synapse port
# Beware: In this example the local traffic goes to the local synapse server at 127.0.0.1
# Of course you can use another IPADRESS in case of using other synapse servers in your network
AllowEncodedSlashes NoDecode
ProxyPass /_matrix http://127.0.0.1:8048/_matrix retry=0 nocanon
ProxyPassReverse /_matrix http://127.0.0.1:8048/_matrix
ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log
CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined
</VirtualHost>

8
examples/caddy/matrix-client-element Normal file
View file

@ -0,0 +1,8 @@
https://element.DOMAIN {
# These might differ if you are supplying your own certificates
tls /matrix/ssl/config/live/element.DOMAIN/fullchain.pem /matrix/ssl/config/live/element.DOMAIN/privkey.pem
proxy / http://127.0.0.1:8765 {
transparent
}
}

9
examples/caddy/matrix-dimension Normal file
View file

@ -0,0 +1,9 @@
https://dimension.DOMAIN {
# These might differ if you are supplying your own certificates
# If you wish to use Caddy's built-in Let's Encrypt support, you can also supply an email address here
tls /matrix/ssl/config/live/dimension.DOMAIN/fullchain.pem /matrix/ssl/config/live/dimension.DOMAIN/privkey.pem
proxy / http://127.0.0.1:8184/ {
transparent
}
}

31
examples/caddy/matrix-synapse Normal file
View file

@ -0,0 +1,31 @@
https://matrix.DOMAIN {
# If you use your own certificates, your path may differ
# If you wish to use Caddy's built-in Let's Encrypt support, you can also supply an email address here
tls /matrix/ssl/config/live/matrix.DOMAIN/fullchain.pem /matrix/ssl/config/live/matrix.DOMAIN/privkey.pem
root /matrix/static-files
header {
Access-Control-Allow-Origin *
Strict-Transport-Security "mag=age=31536000;"
X-Frame-Options "DENY"
X-XSS-Protection "1; mode=block"
}
# Identity server traffic
proxy /_matrix/identity matrix-msisd:8090 {
transparent
}
proxy /_matrix/client/r0/user_directory/search matrix-msisd:8090 {
transparent
}
# Synapse Client<>Server API
proxy /_matrix matrix-synapse:8008 {
transparent
except /_matrix/identity/ /_matrix/client/r0/user_directory/search
}
proxy /_synapse/client matrix-synapse:8008 {
transparent
}
}

7
examples/caddy/matrix-util Normal file
View file

@ -0,0 +1,7 @@
:80 {
# Redirect ACME-Challenge traffic to port 2402
proxy /.well-known/acme-challenge http://127.0.0.1:2402
# Redirect all other traffic to HTTPS
redir / https://{host}{uri} 301
}

203
examples/caddy2/Caddyfile Normal file
View file

@ -0,0 +1,203 @@
matrix.DOMAIN.tld {
# creates letsencrypt certificate
# tls your@email.com
@identity {
path /_matrix/identity/*
}
@noidentity {
not path /_matrix/identity/*
}
@search {
path /_matrix/client/r0/user_directory/search/*
}
@nosearch {
not path /_matrix/client/r0/user_directory/search/*
}
@static {
path /matrix/static-files/*
}
@nostatic {
not path /matrix/static-files/*
}
header {
# Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
# Enable cross-site filter (XSS) and tell browser to block detected attacks
X-XSS-Protection "1; mode=block"
# Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
X-Content-Type-Options "nosniff"
# Disallow the site to be rendered within a frame (clickjacking protection)
X-Frame-Options "DENY"
# X-Robots-Tag
X-Robots-Tag "noindex, noarchive, nofollow"
}
# Cache
header @static {
# Cache
Cache-Control "public, max-age=31536000"
defer
}
# identity
handle @identity {
reverse_proxy localhost:8090 {
header_up X-Forwarded-Port {http.request.port}
header_up X-Forwarded-Proto {http.request.scheme}
header_up X-Forwarded-TlsProto {tls_protocol}
header_up X-Forwarded-TlsCipher {tls_cipher}
header_up X-Forwarded-HttpsProto {proto}
}
}
# search
handle @search {
reverse_proxy localhost:8090 {
header_up X-Forwarded-Port {http.request.port}
header_up X-Forwarded-Proto {http.request.scheme}
header_up X-Forwarded-TlsProto {tls_protocol}
header_up X-Forwarded-TlsCipher {tls_cipher}
header_up X-Forwarded-HttpsProto {proto}
}
}
handle {
encode zstd gzip
reverse_proxy localhost:8008 {
header_up X-Forwarded-Port {http.request.port}
header_up X-Forwarded-Proto {http.request.scheme}
header_up X-Forwarded-TlsProto {tls_protocol}
header_up X-Forwarded-TlsCipher {tls_cipher}
header_up X-Forwarded-HttpsProto {proto}
}
}
}
matrix.DOMAIN.tld:8448 {
handle {
encode zstd gzip
reverse_proxy 127.0.0.1:8048 {
header_up X-Forwarded-Port {http.request.port}
header_up X-Forwarded-Proto {http.request.scheme}
header_up X-Forwarded-TlsProto {tls_protocol}
header_up X-Forwarded-TlsCipher {tls_cipher}
header_up X-Forwarded-HttpsProto {proto}
}
}
}
element.DOMAIN.tld {
# creates letsencrypt certificate
# tls your@email.com
header {
# Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
# Enable cross-site filter (XSS) and tell browser to block detected attacks
X-XSS-Protection "1; mode=block"
# Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
X-Content-Type-Options "nosniff"
# Disallow the site to be rendered within a frame (clickjacking protection)
X-Frame-Options "DENY"
# X-Robots-Tag
X-Robots-Tag "noindex, noarchive, nofollow"
}
handle {
encode zstd gzip
reverse_proxy localhost:8765 {
header_up X-Forwarded-Port {http.request.port}
header_up X-Forwarded-Proto {http.request.scheme}
header_up X-Forwarded-TlsProto {tls_protocol}
header_up X-Forwarded-TlsCipher {tls_cipher}
header_up X-Forwarded-HttpsProto {proto}
}
}
#dimension.DOMAIN.tld {
#
# # creates letsencrypt certificate
# # tls your@email.com
#
# header {
# # Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
# Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
# # Enable cross-site filter (XSS) and tell browser to block detected attacks
# X-XSS-Protection "1; mode=block"
# # Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
# X-Content-Type-Options "nosniff"
# # Disallow the site to be rendered within a frame (clickjacking protection)
# X-Frame-Options "DENY"
# # X-Robots-Tag
# X-Robots-Tag "noindex, noarchive, nofollow"
# }
#
# handle {
# encode zstd gzip
#
# reverse_proxy localhost:8184 {
# header_up X-Forwarded-Port {http.request.port}
# header_up X-Forwarded-Proto {http.request.scheme}
# header_up X-Forwarded-TlsProto {tls_protocol}
# header_up X-Forwarded-TlsCipher {tls_cipher}
# header_up X-Forwarded-HttpsProto {proto}
# }
# }
#}
#jitsi.DOMAIN.tld {
#
# creates letsencrypt certificate
# tls your@email.com
#
# header {
# # Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
# Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
#
# # Enable cross-site filter (XSS) and tell browser to block detected attacks
# X-XSS-Protection "1; mode=block"
#
# # Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
# X-Content-Type-Options "nosniff"
#
# # Disallow the site to be rendered within a frame (clickjacking protection)
# X-Frame-Options "SAMEORIGIN"
#
# # Disable some features
# Feature-Policy "accelerometer 'none';ambient-light-sensor 'none'; autoplay 'none';camera 'none';encrypted-media 'none';focus-without-user-activation 'none'; geolocation 'none';gyroscope #'none';magnetometer 'none';microphone 'none';midi 'none';payment 'none';picture-in-picture 'none'; speaker 'none';sync-xhr 'none';usb 'none';vr 'none'"
#
# # Referer
# Referrer-Policy "no-referrer"
#
# # X-Robots-Tag
# X-Robots-Tag "none"
#
# # Remove Server header
# -Server
# }
#
# handle {
# encode zstd gzip
#
# reverse_proxy 127.0.0.1:13080 {
# header_up X-Forwarded-Port {http.request.port}
# header_up X-Forwarded-Proto {http.request.scheme}
# header_up X-Forwarded-TlsProto {tls_protocol}
# header_up X-Forwarded-TlsCipher {tls_cipher}
# header_up X-Forwarded-HttpsProto {proto}
# }
# }
#}

12
examples/caddy2/README.md Normal file
View file

@ -0,0 +1,12 @@
# Caddyfile
This directory contains sample files that show you how to do reverse-proxying using Caddy2.
## Config
| Variable | Function |
| ------------------ | -------- |
| tls your@email.com | Specify an email address for your [ACME account](https://caddyserver.com/docs/caddyfile/directives/tls) (but if only one email is used for all sites, we recommend the email [global option](https://caddyserver.com/docs/caddyfile/options) instead) |
| tls | To enable [tls](https://caddyserver.com/docs/caddyfile/directives/tls) support uncomment the lines for tls |
| Dimension | To enable Dimension support uncomment the lines for Dimension and set your data |
| Jitsi | To enable Jitsi support uncomment the lines for Jitsi and set your data |

12
examples/haproxy/Dockerfile Normal file
View file

@ -0,0 +1,12 @@
# Pull nginx base image
FROM nginx:latest
# Expost port 80
EXPOSE 80
# Copy custom configuration file from the current directory
COPY nginx.conf /etc/nginx/nginx.conf
# Start up nginx server
CMD ["nginx"]

26
examples/haproxy/README.md Normal file
View file

@ -0,0 +1,26 @@
# HAproxy reverse-proxy
This directory contains sample files that show you how to do reverse-proxying using HAproxy.
This is for when you wish to have your own HAproxy instance sitting in front of Matrix services installed by this playbook.
See the [Using your own webserver, instead of this playbook's nginx proxy](../../docs/configuring-playbook-own-webserver.md) documentation page.
To use your own HAproxy reverse-proxy, you first need to disable the integrated Nginx server.
You do that with the following custom configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_nginx_proxy_enabled: false
```
You can then use the configuration files from this directory as an example for how to configure your HAproxy reverse proxy.
**NOTE**: this is just an example and may not be entirely accurate. It may also not cover other use cases or performance needs.
### Configuration
HAproxy, unlike Apache, Nginx and others, does not provide you with a webserver to serve static files (i.e., `/.well-known/` directory). For this reason, in this folder you can find an example on how to use HAproxy together with a simple Nginx container whose only task is to serve those files.
* Build the Docker image. `docker build -t local/nginx .`
* Start the container. `docker-compose up -d`. Note that if you want to run Nginx on a different port, you will have to change the port both in the `docker-compose.yml` and in `haproxy.cfg`.
* If you don't want to use a wildcard certificate, you will need to modify the corresponding line in the HTTPS frontent and add the paths of all the specific certificates (as for the commented example in `haproxy.cfg`).
* Start HAproxy with the proposed configuration.

8
examples/haproxy/docker-compose.yml Normal file
View file

@ -0,0 +1,8 @@
version: '3'
services:
nginx:
image: local/nginx
ports:
- 40888:80
volumes:
- /matrix/static-files:/var/www/:ro

97
examples/haproxy/haproxy.cfg Normal file
View file

@ -0,0 +1,97 @@
global
log /dev/log local0
log /dev/log local1 notice
chroot /var/lib/haproxy
stats socket /run/haproxy/admin.sock mode 660 level admin
stats timeout 30s
user haproxy
group haproxy
daemon
# Default SSL material locations
ca-base /etc/ssl/certs
crt-base /etc/ssl/private
# Default ciphers to use on SSL-enabled listening sockets.
# For more information, see ciphers(1SSL). This list is from:
# https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/
ssl-default-bind-ciphers ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS
ssl-default-bind-options no-sslv3
defaults
log global
mode http
option httplog
option dontlognull
option forwardfor
option redispatch
timeout connect 5000
timeout client 50000
timeout server 50000
errorfile 400 /etc/haproxy/errors/400.http
errorfile 403 /etc/haproxy/errors/403.http
errorfile 408 /etc/haproxy/errors/408.http
errorfile 500 /etc/haproxy/errors/500.http
errorfile 502 /etc/haproxy/errors/502.http
errorfile 503 /etc/haproxy/errors/503.http
errorfile 504 /etc/haproxy/errors/504.http
frontend https-frontend
bind *:80
# HAproxy wants the full chain and the private key in one file. For Letsencrypt manually generated certs (e.g., wildcard certs) you can use
# cat /etc/letsencrypt/live/example.com/fullchain.pem /etc/letsencrypt/live/example.com/privkey.pem > /etc/haproxy/certs/star-example.com.pem
bind *:443 ssl crt /etc/haproxy/certs/star-example.com.pem
#bind *:443 ssl crt /etc/haproxy/certs/element.example.com.pem /etc/haproxy/certs/matrix.example.com.pem
reqadd X-Forwarded-Proto:\ https
option httplog
option http-server-close
#
# Matrix
#
# matrix.example.com
acl matrix_domain hdr_dom(host) -i matrix.example.com
acl static_files path -i -m beg /.well-known/matrix
use_backend nginx-static if static_files
# /_matrix/identity and /_matrix/client/r0/user_directory/search
acl matrix_identity path -i -m beg /_matrix/identity
acl matrix_search path -i -m beg /_matrix/client/r0/user_directory/search
# Send to :8090
use_backend matrix-supporting if matrix_identity or matrix_search
# /_matrix and /_synapse/admin
acl matrix_path path -i -m beg /_matrix
acl synapse_admin path -i -m beg /_synapse/admin
# Send to :8008
use_backend matrix-main if matrix_path or synapse_admin
# element.example.com
acl element_domain hdr_dom(host) -i element.example.com
# Send to 8765
use_backend element if element_domain
# If nothing else match, just send to default matrix backend
use_backend matrix-main if matrix_domain
#default_backend matrix-main
frontend matrix-federation
bind *:8448 ssl crt /etc/haproxy/certs/star-example.com.pem
reqadd X-Forwarded-Proto:\ https
option httplog
option http-server-close
default_backend synapse
backend matrix-supporting
server matrix-supporting 127.0.0.1:8090 check
backend matrix-main
server matrix-main 127.0.0.1:8008 check
backend synapse
server synapse 127.0.0.1:8048 check
backend nginx-static
capture request header origin len 128
http-response add-header Access-Control-Allow-Origin *
rspadd Access-Control-Allow-Methods:\ GET,\ HEAD,\ OPTIONS,\ POST,\ PUT if { capture.req.hdr(0) -m found }
rspadd Access-Control-Allow-Credentials:\ true if { capture.req.hdr(0) -m found }
rspadd Access-Control-Allow-Headers:\ Origin,\ Accept,\ X-Requested-With,\ Content-Type,\ Access-Control-Request-Method,\ Access-Control-Request-Headers,\ Authorization if { capture.req.hdr(0) -m found }
server nginx 127.0.0.1:40888 check
backend element
server element 127.0.0.1:8765 check

15
examples/haproxy/nginx.conf Normal file
View file

@ -0,0 +1,15 @@
worker_processes auto;
daemon off;
events {
worker_connections 1024;
}
http {
server_tokens off;
server {
listen 80;
index index.html;
root /var/www;
}
}

19
examples/hosts Normal file
View file

@ -0,0 +1,19 @@
# We explicitly ask for your server's external IP address, because the same value is used for configuring Coturn.
# If you'd rather use a local IP here, make sure to set up `matrix_coturn_turn_external_ip_address`.
#
# To connect using a non-root user (and elevate to root with sudo later),
# replace `ansible_ssh_user=root` with something like this: `ansible_ssh_user=username become=true become_user=root`
#
# For improved Ansible performance, SSH pipelining is enabled by default in `ansible.cfg`.
# If this causes SSH connection troubles, disable it by adding `ansible_ssh_pipelining=False`
# to the host line below or by adding `ansible_ssh_pipelining: False` to your variables file.
#
# If you're running this Ansible playbook on the same server as the one you're installing to,
# consider adding an additional `ansible_connection=local` argument to the host line below.
#
# Ansible may fail to discover which Python interpreter to use on the host for some distros (like Ubuntu 20.04).
# You may sometimes need to explicitly add the argument `ansible_python_interpreter=/usr/bin/python3`
# to the host line below.
[matrix_servers]
matrix.<your-domain> ansible_host=<your-server's external IP address> ansible_ssh_user=root

Some files were not shown because too many files have changed in this diff Show more