.. _helm_prod:
Installing wire-server (production) components using Helm
=========================================================
.. note::
Code in this repository should be considered *beta*. As of 2020, we do not (yet)
run our production infrastructure on Kubernetes (but plan to do so soon).
Introduction
------------
The following will install a version of all the wire-server components. These instructions are for reference, and may not set up what you would consider a production environment, due to the fact that there are varying definitions of 'production ready'. These instructions will cover what we consider to be a useful overlap of our users' production needs. They do not cover load balancing/distributing, using multiple datacenters, federating wire, or other forms of intercontinental/interplanetary distribution of the wire service infrastructure. If you deviate from these directions and need to contact us for support, please provide the deviations you made to fit your production environment along with your support request.
Some of the instructions here will present you with two options: No AWS, and with AWS. The 'No AWS' instructions will not require any AWS infrastructure, but may have a reduced feature set. The 'with AWS' instructions will assume you have completed the setup procedures in :ref:`aws_prod`.
What will be installed?
^^^^^^^^^^^^^^^^^^^^^^^
- wire-server (API)
- user accounts, authentication, conversations
- assets handling (images, files, ...)
- notifications over websocket
- wire-webapp, a fully functioning web client (like ``https://app.wire.com/``)
- wire-account-pages, user account management (a few pages relating to e.g. password reset procedures)
What will not be installed?
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- team-settings page
- SSO Capabilities
Additionally, if you opt to do the 'No AWS' route, you will not get:
- notifications over native push notifications via `FCM `__/`APNS `__
Prerequisites
-------------
You need to have access to a Kubernetes cluster running a Kubernetes version , and the ``helm`` local binary on your PATH.
Your Kubernetes cluster needs to have internal DNS services, so that wire-server can find it's databases.
You need to have docker on the machine you are using to perform this installation with, or a secure data path to a machine that runs docker. You will be using docker to generate security credentials for your wire installation.
* If you want calling services, you need to have
* FIXME
* If you don't have a Kubernetes cluster, you have two options:
* You can get access to a managed Kubernetes cluster with the cloud provider of your choice.
* You can install one if you have ssh access to a set of sufficiently large virtual machines, see :ref:`ansible-kubernetes`
* If you don't have ``helm`` yet, see `Installing helm `__. If you followed the instructions in :ref:`dependencies` should have helm installed already.
Type ``helm version``, you should, if everything is configured correctly, see a result similar this:
::
version.BuildInfo{Version:"v3.1.1", GitCommit:"afe70585407b420d0097d07b21c47dc511525ac8", GitTreeState:"clean", GoVersion:"go1.13.8"}
In case ``kubectl version`` shows both Client and Server versions, but ``helm version`` does not show a Server version, you may need to run ``helm init``. The exact version matters less as long as both Client and Server versions match (or are very close).
Preparing to install charts from the internet with Helm
-------------------------------------------------------
If your environment is online, you need to add the remote wire Helm repository, to download wire charts.
To enable the wire charts helm repository:
.. code:: shell
helm repo add wire https://s3-eu-west-1.amazonaws.com/public.wire.com/charts
(You can see available helm charts by running ``helm search repo wire/``. To see
new versions as time passes, you may need to run ``helm repo update``)
Great! Now you can start installing.
There is a shell script for doing a version of the following procedure with Helm 22. For reference, examine `prod-setup.sh `__.
Watching changes as they happen
-------------------------------
Open a terminal and run:
.. code:: shell
kubectl get pods -w
This will block your terminal and show some things happening as you proceed through this guide. Keep this terminal open and open a second terminal.
General installation notes
--------------------------
.. note::
All helm and kubectl commands below can also take an extra ``--namespace `` if you don't want to install into the default Kubernetes namespace.
How to install charts that provide access to external databases
---------------------------------------------------------------
Before you can deploy the helm charts that tell wire where external services
are, you need the 'values' and 'secrets' files for those charts to be
configured. Values and secrets YAML files provide helm charts with the settings
that are installed in Kubernetes.
Assuming you have followed the procedures in the previous document, the values
and secrets files for cassandra, elasticsearch, and minio (if you are using it)
will have been filled in automatically. If not, examine the
``prod-values.example.yaml`` files for each of these services in
values//, copy them to ``values.yaml``, and then edit them.
Once the values and secrets files for your databases have been configured, you
have to write a ``values/databases-ephemeral/values.yaml`` file to tell
databases-ephemeral what external database services you are using, and what
services you want databases-ephemeral to configure. We recommend you use the
'redis' component from this only, as the contents of redis are in fact
ephemeral. Look at the ``values/databases-ephemeral/prod-values.example.yaml``
file
Once you have values and secrets for your environment, open a terminal and run:
.. code:: shell
helm upgrade --install cassandra-external wire/cassandra-external -f values/cassandra-external/values.yaml --wait
helm upgrade --install elasticsearch-external wire/elasticsearch-external -f values/elasticsearch-external/values.yaml --wait
helm upgrade --install databases-ephemeral wire/databases-ephemeral -f values/databases-ephemeral/values.yaml --wait
If you are using minio instead of AWS S3, you should also run:
.. code:: shell
helm upgrade --install minio-external wire/minio-external -f values/minio-external/values.yaml --wait
How to install fake AWS services for SNS / SQS
----------------------------------------------
AWS SNS is required to send notifications to clients. SQS is used to get notified of any devices that have discontinued using Wire (e.g. if you uninstall the app, the push notification token is removed, and the wire-server will get feedback for that using SQS).
Note: *for using real SQS for real native push notifications instead, see also :ref:`pushsns`.*
If you use the fake-aws version, clients will use the websocket method to receive notifications, which keeps connections to the servers open, draining battery.
Open a terminal and run:
.. code:: shell
cp values/fake-aws/prod-values.example.yaml values/fake-aws/values.yaml
helm upgrade --install fake-aws wire/fake-aws -f values/fake-aws/values.yaml --wait
You should see some pods being created in your first terminal as the above command completes.
Preparing to install wire-server
--------------------------------
As part of configuring wire-server, we need to change some values, and provide some secrets. We're going to copy the files for this to a new folder, so that you always have the originals for reference.
.. note::
This part of the process makes use of overrides for helm charts. You may wish to read :ref:`understand-helm-overrides` first.
.. code:: shell
mkdir -p my-wire-server
cp values/wire-server/prod-secrets.example.yaml my-wire-server/secrets.yaml
cp values/wire-server/prod-values.example.yaml my-wire-server/values.yaml
How to configure real SMTP (email) services
-------------------------------------------
In order for users to interact with their wire account, they need to receive mail from your wire server.
If you are using a mail server, you will need to provide your authentication credentials before setting up wire.
- Add your SMTP username in my-wire-server/values.yaml under ``brig.config.smtp.username``. You may need to add an entry for username.
- Add your SMTP password is my-wire-server/secrets.yaml under ``brig.secrets.smtpPassword``.
How to install fake SMTP (email) services
-----------------------------------------
If you are not making use of mail services, and are adding your users via some other means, you can use demo-smtp, as a placeholder.
.. code:: shell
cp values/demo-smtp/prod-values.example.yaml values/demo-smtp/values.yaml
helm upgrade --install smtp wire/demo-smtp -f values/demo-smtp/values.yaml
You should see some pods being created in your first terminal as the above command completes.
How to install wire-server itself
---------------------------------
Open ``my-wire-server/values.yaml`` and replace ``example.com`` and other domains and subdomains with domains of your choosing. Look for the ``# change this`` comments. You can try using ``sed -i 's/example.com//g' values.yaml``.
1. If you are not using team settings, comment out ``teamSettings`` under ``brig.config.externalURLs``.
Generate some secrets:
.. code:: shell
openssl rand -base64 64 | env LC_CTYPE=C tr -dc a-zA-Z0-9 | head -c 42 > my-wire-server/restund.txt
apt install docker-ce
sudo docker run --rm quay.io/wire/alpine-intermediate /dist/zauth -m gen-keypair -i 1 > my-wire-server/zauth.txt
1. Add the generated secret from my-wire-server/restund.txt to my-wire-serwer/secrets.yaml under ``brig.secrets.turn.secret``
2. add **both** the public and private parts from zauth.txt to secrets.yaml under ``brig.secrets.zAuth``
3. Add the public key from zauth.txt to secrets.yaml under ``nginz.secrets.zAuth.publicKeys``
Great, now try the installation:
.. code:: shell
helm upgrade --install wire-server wire/wire-server -f my-wire-server/values.yaml -f my-wire-server/secrets.yaml --wait
.. _helmdns:
DNS records
-----------
.. include:: includes/helm_dns-ingress-troubleshooting.inc.rst