Threema for Desktop

A standalone Threema client for the desktop (Windows/macOS/Linux).

Table of Contents

• Policies
  • Bug Reports / Feature Requests / Security Issues
  • Contributions
  • Source Code Release Policy
• Building
  • Requirements
  • Install Dependencies
  • Set Up Fonts
  • Build and Package
• Development
  • Dev Container
  • Development Outside Dev Container
  • Starting a Dev Build
• License

Policies

Bug Reports / Feature Requests / Security Issues

To report bugs and request new features, please contact the Threema support team through threema.ch/support.

If you discover a security issue in Threema, please adhere to the coordinated vulnerability disclosure model. To be eligible for a bug bounty, please file a report on GObugfree (where all the details, including the bounty levels, are listed). If you’re not interested in the bug bounty program, you can contact us via Threema or by email; for contact details, see threema.ch/contact (section “Security”).

Contributions

Contributing to Threema for desktop can be done over GitHub pull requests. See CONTRIBUTING.md for details.

Source Code Release Policy

This source code repository will be updated for every public release. The full commit history since the last release will be published.

Building

Requirements

• NodeJS / npm (we recommend using something like nvm for version management)
• Python3 with distutils (for node-gyp, e.g. python and python-setuptools on Arch)
• C/C++ compiler toolchain (e.g. build-essential on Debian or base-devel on Arch)
• Rust compiler and Cargo

It is highly recommended to use a Linux- or macOS-based system for building and developing Threema Desktop! Building on Windows 10+ should mostly work, but not everything may work as smoothly and we cannot provide any support.

macOS

On macOS you might need to manually install and configure the C compiler toolchain in order to use node-gyp. Usually that can be done by installing the required "Command Line Tools" with the command xcode-select --install. Alternatively, you can install Xcode (note that it might take more than 1h between download and installation!) and then select a "Command Line Tools" version in Preferences > Locations. For a detailed guide and diagnostics, please refer to the "Installation notes for macOS" from the node-gyp project itself.

Windows

When building on Windows, it is important to clone the repository with symlink support. For this, you first need to enable Developer Mode. Then, run the following command to enable git support for symlinks globally:

git config --global core.symlinks true

Afterwards clone the repository as usual. (Alternatively, clone with git clone -c core.symlinks=true ... if you don't want to enable this option globally.)

Install Dependencies

First, make sure that you're using the correct NodeJS version (check out the .nvmrc file). If you have nvm installed, you can simply type nvm use.

Next, install dependencies:

npm install

Note that this requires a C/C++ compiler toolchain due to native dependencies, as mentioned above.

Set Up Fonts

When building from source, due to its license, the Threema font (Lab Grotesque) is not included in the build. To ensure that all fonts are rendered correctly, obtain a desktop license from Letters from Sweden and install the font family on your system.

If you don't install the font, you can still build and run Threema, but some layouts might not be rendered as intended. (Known issue: Numbers are not displayed correctly.)

Note: In official builds provided by Threema, the Lab Grotesque font is bundled and does not need to be installed manually.

Build and Package

To create a package target, run:

npm run package <target> [params]

Possible targets:

• source: A source archive (.tar.gz and .7z)
• binary: An archive containing a raw binary build for the current architecture
• dmg: An unsigned macOS DMG
• dmgSigned: A signed macOS DMG
• msix: An unsigned Windows MSIX package
• msixSigned: A signed Windows MSIX package
• flatpak: A Linux Flatpak in a local repository

For example, to build Threema for your current platform, run:

npm run package binary consumer-live

Now you can find the application bundle at build/out/.

Development

Below we'll provide a couple of hints and rules for working on this project.

More developer docs can be found under docs/.

Dev Container

We recommend to use the provided VS Code Dev Container considering that any npm dependency can run arbitrary code and we have a ton of development dependencies. Note that this currently requires Visual Studio Code (not Code OSS) and the proprietary ms-vscode-remote.remote-containers extension.

> Dev Containers: Reopen in Container

You will have to rebuild the Dev Container every time the Node version of .nvmrc changes.

> Dev Containers: Rebuild Container

It is also possible to use the native shell to run npm and node commands inside of the container. You'll need jq and a compatible shell, then run:

source ./.devcontainer/env.sh
node --version

Limitations:

• Needs X11 compatibility to run npm run dev:*. It may run slower and may not support all UI features (e.g. drag & drop). To use the native UI, it is recommended to make a npm run dist:* build and run that locally but only when needed.
• Cannot run npm run test:karma. Let this be run by the CI after pushing a branch.

Development Outside Dev Container

The project provides an .nvmrc file in case the default NodeJS installation on your device is being rejected by npm install.

nvm use
nvm install

Starting a Dev Build

To start a dev build of Threema with hot code reloading, run npm run dev:<flavor> in the terminal, e.g. npm run dev:consumer-live.

License

Threema for Desktop is licensed under the GNU Affero General Public License v3.

Copyright (c) Threema GmbH

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License, version 3,
as published by the Free Software Foundation.

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/>.

The full license text can be found in LICENSE.txt.

If you have questions about the use of self-compiled apps or the license in general, feel free to contact us. We are publishing the source code in good faith, with transparency being the main goal. By having users pay for the development of the app, we can ensure that our goals sustainably align with the goals of our users: Great privacy and security, no ads, no collection of user data!