Package: teamplify
Teamplify runnerTeamplifyis a personal assistant for your development
team. It helps you track work progress and notify your team about situations
that may require their attention. It is availablein the cloudor as an on-premise installation.This package is the installer and runner for the on-premise version.System requirementsOn Ubuntu, be sure to install pip3HardwareInstallingInstalling on LinuxInstalling on Mac OS XConfigurationWhere are configuration files located?A reference of all configuration optionsStarting and stopping the serviceWhat to do after the first run?Creating an admin accountUpdating TeamplifyBackup and restoreA Sample maintenance scriptUninstallTroubleshootingTeamplify won't startEmail delivery issuesThe connection is refused or not trusted in SSL-enabled modeOtherLicenseSystem requirementsTeamplify is designed to run on Linux. For demonstration purposes, it should
also deploy on Mac OS X. Windows is not supported.Before you install, make sure that your system has the following components:Docker version 1.13 and above;Docker Compose V2;Python 3.6 and above;pip for Python 3To check that the required versions are installed, run these commands (shown
with example output):$docker-v
Dockerversion18.06.1-ce,builde68fc7a215d7133c34aa18e3b72b4a21fd0c6136
$python3--version
Python3.7.2
$pip3--version
pip9.0.3from/usr/lib/python3.7/site-packages(python3.7)On Ubuntu, be sure to installpip3On most systems,Python 3comes withpip3pre-installed. However,
in UbuntuPython 3andpip3are installed separately. To installpip3run:$sudoaptinstallpython3-pipImportant: after installing, exit the terminal and re-open it.
This forces the terminal to update its path configuration, so that you
can find the command line tools installed withpip3in your$PATH.HardwareAs a default server configuration, we recommend 4GB of RAM, 2 CPU cores, and
30 GB of disk space (SSD is strongly recommended). For most small-to-medium
organizations (up to a few dozen people), this should be enough. Larger
workloads, however, may need more resources. The recommended strategy is to
start with the default server configuration and scale up or down depending on
the workload.InstallingInstalling on LinuxAfter installing Docker, check Docker'spost-installation steps for Linux.
You probably want to make sure that you can run Docker commands withoutsudo, and that Docker is configured to start on boot.Install the latest version of Teamplify runner with pip:$pip3install-UteamplifyInstalling on Mac OS XOn Mac OS X, we recommend installing Teamplify in a Python virtual
environment located in your home directory. This is because Teamplify needs to
mount its configuration files into Docker containers. By default on Mac OS X,
only the/Usersfolder is shared with Docker.Create a new Python virtual environment for Teamplify in your home directory:$python3-mvenv~/.venv/teamplifyActivate it:$source~/.venv/teamplify/bin/activateAt this point, apipcommand is linked to the virtual environment that
you just created. Install Teamplify runner withpip:$pipinstallteamplifyConfigurationTeamplify requires a configuration file to run.Run the following command to create the initial file:$teamplifyconfigureThis creates a configuration file with default settings in your home
directory:~/.teamplify.ini. You can specify the location of
your file with the--configoption.Use your text editor to  adjust the contents of this file.
You need to specify the following parameters:product_keyin the[main]sectionhostandportin the[web]sectionOther parameters are optional and can keep their default values.
You can review them atthe reference of all configuration optionsWhere are configuration files located?When you runteamplify configure, it creates a configuration file.
Typically, this file is at~/.teamplify.ini.However, that is not the only
possible location. Teamplify searches the following locations (listed from
highest priority to lowest priority):First, it checks the location specified in the--configparameter in the
command line. Example:$teamplify--config/path/to/configuration/filestartAn environment variable namedTEAMPLIFY_CONF. Example:$TEAMPLIFY_CONF=/path/to/configuration/fileteamplifystartIn the home directory of the current user:~/.teamplify.ini;At/etc/teamplify/teamplify.ini.A reference of all configuration options[main]product_key- the product key of your installation. This is required.
To get the product key, please email us atsupport@teamplify.com;send_crash_reports- possible values areyesandno, defaults toyes.
When set toyes, the system automatically sends application crash
reports to our team. We recommend keeping this option enabled as it helps us
to detect bugs faster and ship fixes for them more quickly;[web]⚠️ Please note that the built-in SSL option with certificates from
Let's Encrypt requires standard ports for HTTP and HTTPS:port = 80andssl_port = 443. This requirement comes from theLet's Encrypt HTTP-01 challenge,
which does not support custom ports. However, you can still use custom HTTP and
HTTPS ports if you provide your own SSL certificates or use an external proxy
withuse_ssl = external.host- domain name on which the Teamplify web interface will be running. It
must be created in advance, and pointed to the server where you have
installed Teamplify;port- the port on which Teamplify web interface will be running, the default
is80. Ifuse_sslis set tobuiltinand no SSL certificates path is specified
then80is the only allowed option;use_ssl- SSL mode. Possible values areno,builtin, andexternal, defaults tono. When set tobuiltin, Teamplify will serve HTTPS requests on the port specified
in thessl_portoption below. All HTTP traffic will be redirected to this port.
If you're hosting Teamplify behind a proxy or load balancer that is already
configured for SSL support, please set this parameter toexternal,
and also make sure that your proxy correctly setsX-Forwarded-ProtoHTTP header.
In this case, Teamplify will handle HTTP requests on the port number specified
in theportoption and redirect insecure requests tohttps://<host>:<ssl_port>.ssl_port- the port on which Teamplify web interface will be running when SSL
is enabled, the default is443. Ifuse_sslis set tobuiltinand
no SSL certificates path is specified, then443is the only allowed option;ssl_certs(optional) - a path to a directory which contains SSL
certificates. The directory must contain certificate (.crt) and key (.key) files
for the domain specified in thehostoption above. The filenames must be equal
the domain name. For example, if the domain isexample.com, the filenames
must beexample.com.crtandexample.com.key. If no path is specified,
Teamplify runner will useLet's Encryptto generate and renew SSL certificates for the domain that you specified
in thehostparameter above.[runner][db]host- defaults tobuiltin_db, that is, using the DB instance that is
shipped with Teamplify. You can also switch to an external MySQL 5.7
compatible database by providing its hostname instead ofbuiltin_dband
specifying other DB connection parameters below;name- the database name to use. Must beteamplifyifbuiltin_dbis
used;port- the database port. Must be3306forbuiltin_db;user- DB user. Must berootforbuiltin_db;password- DB password. Must beteamplifyforbuiltin_db;backup_mount- a path to a directory on the server which will be mounted
into the built-in DB instance container. It is used as a temporary directory
in the process of making and restoring backups;[email]address_from- email address used by Teamplify in the FROM field of its
email messages. It could be either a plain email address or an email address
with a display name, like this:Teamplify <teamplify@your-company-domain.com>;smtp_host- hostname of an SMTP server used to send emails. Defaults tobuiltin_smtpwhich means using the SMTP server that is shipped with
Teamplify. Built-in SMTP for Teamplify is based on Postfix, and it is
production-ready. However, if you plan to use it, we strongly recommend that
you add the address of Teamplify's server to theSPF recordof the domain used
in theaddress_fromsetting to prevent Teamplify emails from being marked
as spam. Or, you can configure Teamplify to use an external SMTP server by
providing its hostname instead ofbuiltin_smtpand configuring other
SMTP connection settings below;smtp_protocol- SMTP protocol to use. Can beplain,ssl, ortls.
Must beplainif you usebuiltin_smtp;smtp_port- SMTP port to use. Must be25forbuiltin_smtp;smtp_user- username for the SMTP server. Must be blank forbuiltin_smtp;smtp_password- password for the SMTP server. Must be blank forbuiltin_smtp;[crypto]signing_key- the random secret string used by Teamplify for signing
cookies and generating CSRF protection tokens. It is automatically generated
when you runteamplify configure, and typically you don't need to change
it unless you think that it may be compromised. In such cases, replace it with
another 50-character random string made of Latin characters and numbers
(please note that this will force all existing users to log in to the system
again).[worker]slim_count- number of workers doing background tasks, such as sending
notifications and emails. The default setting is1, which is sufficient
for most organizations.fat_count- the number of workers synchronizing resources, such as
repositories, chats, issues, etc. If you have a lot of resources or it takes
a long time to sync them, you can increase this parameter. Essentially, it
controls how many resources are synchronized in parallel. The default setting
is2.Starting and stopping the serviceAfter you have created the configuration file, start Teamplify with:$teamplifystartOn the first run, the application has to download and configure many Docker
images. For this reason, the first run might take a while to start.After the command completes, open Teamplify in your browser using thehostand
theportthat you provided in the[web]section of the configuration. After
starting the service, it might take a minute or two before it finally comes
online.If you have problems starting Teamplify, please see theTroubleshootingsection below.If you need to stop Teamplify, run:$teamplifystopAfter running Teamplify for the first time,follow the instructions to create an admin accountThere's also a convenient command to stop the service and start it again. This
is useful when applying changes made to the configuration:$teamplifyrestartWhat to do after the first run?After the first run, you need to create an admin account.Creating an admin accountAfter the application first starts, run the following command:$teamplifycreateadmin--email<admin@email>--full-name<FullName>Please check the output to make sure that no errors occurred.With thecreateadmincommand, you can create as many
admin account as you want. However, after creating the first one,
it might be more convenient to create the others through the Teamplify UI.Updating TeamplifyTeamplify installation consists of the Teamplify runner and the Teamplify
product itself, which ships in the form of Docker images. We recommend
that you use the most recent version to keep up with the latest features and
bugfixes. The update process consists of two steps:Update Teamplify runner:$pip3install-UteamplifyUpdate Teamplify itself:$teamplifyupdateTheupdatecommand automatically detects if a new version has been
downloaded and, if necessary, restarts the service. Because a service restart
causes  a short downtime, you should ideally update in periods of low user
activity. Theupdatecommand restarts the service only when necessary. If no
update has been downloaded, there is no restart and therefore no service
interruption.Backup and restoreTeamplify stores your data in a MySQL database. As with any other database, it
might be a good idea to make backups from time to time.To back up the built-in Teamplify database, run:$teamplifybackup[optional-backup-file-or-directory]If launched without parameters, it makes a gzipped backup of the DB and
stores it in the current working directory, under a name in the format:teamplify_<current-date>.sql.gz,for example,teamplify_2019-01-31_06-58-57.sql.gz.You may specify the directory or file path where you'd like to save your backup.To restore the built-in Teamplify database from a gzipped backup, run:$teamplifyrestore<path-to-a-backup-file>Please note that the commands above work with only a built-in database.
If you're running Teamplify with an external database, you need to use tools
for backups or restores that connect to that database directly.A Sample maintenance scriptBacking up the data and keeping the software up-to-date are routine operations.
We recommend automating these processes. Below is a sample script you can use to
do so.Create a file namedteamplify-maintenance.shwith the following contents:#!/usr/bin/env bash# Backups directory:BACKUP_LOCATION=/backups/teamplify/# How many days should we store the backups for:BACKUP_STORE_DAYS=14# Back up Teamplify DB and update Teamplify:mkdir-p$BACKUP_LOCATION&&\pip3install-Uteamplify&&\teamplifybackup$BACKUP_LOCATION&&\teamplifyupdate# If the update was successful, clean up old backups:if[$?-eq0];thenfind$BACKUP_LOCATION-typef-mmin+$((60*24*$BACKUP_STORE_DAYS))\-name'teamplify_*.sql.gz'-execdirrm--'{}'\;fi# The final step is optional but recommended. Add your code so that would# sync contents of $BACKUP_LOCATION to a physically remote location.##   ... add your backups sync code below:In the code above, adjust the path for$BACKUP_LOCATIONand the value
for$BACKUP_STORE_DAYSas necessary. At the end of the script, you can add
your own code that would sync your backups to a remote location. This is an
optional but highly recommended precaution that would help you recover your
backup in the case of a disaster. For example, you can useaws s3 syncto
upload the backups to AWS S3.When the maintenance script is ready, make it executable withchmod +x teamplify-maintenance.sh.Set the script to run as a daily cron job. Open the crontab schedule:$crontab-eAppend the following entry (remember to replace the path to the script):03***/path/to/the/script/teamplify-maintenance.shIn the example above, the script is scheduled to run daily at 3 AM. Seecron syntaxfor a detailed explanation.
When ready, save and close the file.UninstallIf you'd like to uninstall Teamplify, use the following steps.IMPORTANT: The uninstall procedure erases all data stored in Teamplify.
Before doing this,consider making a backup.Remove all Teamplify data, Docker images, volumes, and networks:$teamplifyeraseUninstall Teamplify runner:$pip3uninstallteamplifyTroubleshootingSo what could possibly go wrong?Teamplify won't startPlease check the following:The service won't start if the configuration file is missing or contains
errors. In such cases, theteamplify startcommand will report a problem.
Please inspect its output;There could be a problem with the domain name configuration. If theteamplify startcommand has completed successfully, you should see
Teamplify's interface in the browser when you open an address specified in thehostandportparameters in the[web]section of theConfiguration. If that doesn't happen, i.e. if browser says
that it can't find the server or the server is not responding, then most
likely this is a problem with either the domain name or firewall
configuration. Please make sure that the domain exists and points to the
Teamplify server, and that the port is open in the firewall;If you see the "Teamplify is starting" message, you should give it a minute
or two to come online. If nothing happens after a few minutes, there could be
a problem during application start. Application logs may contain additional
information:$dockerlogsteamplify_appPlease let us know about the problem and attach the output from the command
above. You can eitheropen an issue on Github,
or contact us atsupport@teamplify.com, or
use the live chat onteamplify.com.Email delivery issuesEmails can go to spam or sometimes aren't delivered at all. If you're
running a demo version of Teamplify on your desktop at home, this is
very likely to happen, since IPs of home internet providers have a large
chance of being blacklisted in spam databases. We recommend that you
try the following:If you're going to use the built-in SMTP server, consider running Teamplify
on a server hosted in a data center or at your office, but not at home. Next,
please make sure that you've added the IP of your Teamplify server to theSPF recordof the domain used
inaddress_fromsetting in the configuration file;Some email providers, for example, Google Mail, explicitly reject emails
sent from blacklisted IPs. It might be helpful to examine SMTP server
logs to see if that's what's happening:$dockerlogsteamplify_smtpAlternatively, if you have another SMTP server that is already configured
and can reliably send emails, you can configure Teamplify to use this server
instead of the built-in SMTP. See[email]section inConfigurationfor details;The connection is refused or not trusted in SSL-enabled modeDuring the first start, Teamplify runner generates a temporary self-issued SSL
certificate (not trusted) and then tries to create a valid certificate for your
domain viaLet's Encryptthat would replace the
temporary one. Besides that, it also creates a new set of 2048-bit DH parameters
to give your SSL configuration an A+ rating. This process is rather slow and may
take a few minutes to complete. If you open Teamplify in your browser and see
that the SSL connection can't be established or is not trusted, the problem may
be caused by DH params or the SSL certificate generations that are still in
progress. After DH params and the SSL certificate have been successfully
generated, they are saved for future use and subsequent restarts of the server
should be much faster.If you have just started the server for the very first time, please give it a
few minutes to complete the initialization and then refresh the page in your
browser. If after a few minutes the browser reports that the connection is not
trusted, it probably means that the certificate generation has failed. Please
check the following:That the domain that you specified in thehostparameter can be resolved
from the public Internet and is pointing to the server on which you have
installed Teamplify;That ports80and443are not blocked in the firewall.It also might be helpful to check the logs:$dockerlogsteamplify_letsencryptOtherFor any issue with Teamplify, we recommend that you try tocheck for updatesfirst. We release updates frequently. It's quite
possible that the problem that you encountered is already addressed in a newer
version.If these suggested solutions don't work, don't hesitate toopen an issue on Githubor contact us atsupport@teamplify.com. You can
also use the live chat onteamplify.com. We're ready
to help!LicenseTeamplify runner is available under the MIT license. Please note that the MIT
license applies to Teamplify runner only, but not to the main Teamplify product.
Some Docker images downloaded by Teamplify runner will contain a proprietary
code that is not open source and is distributed under its ownterms and conditions.