Teamplify is 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 available in the cloud or as an on-premise installation.
This package is the installer and runner for the on-premise version.
- System requirements
- Installing
- Configuration
- Starting and stopping the service
- What to do after the first run?
- Updating Teamplify
- Backup and restore
- A Sample maintenance script
- Uninstall
- Troubleshooting
- License
Teamplify 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 2.29.4 and above;
- Python 3.9 and above;
- pip for Python 3
To check that the required versions are installed, run these commands (shown with example output):
$ docker -v
Docker version 27.5.1, build 9f9e405
$ python3 --version
Python 3.12.3
$ pip3 --version
pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.12)On most systems, Python 3 comes with pip3 pre-installed. However,
in Ubuntu Python 3 and pip3 are installed separately. To install
pip3 run:
$ sudo apt install python3-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 with pip3 in your $PATH.
As a default server configuration, we recommend 8GB of RAM, 4 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.
After installing Docker, check Docker's
post-installation steps for Linux.
You probably want to make sure that you can run Docker commands without
sudo, and that Docker is configured to start on boot.
Install the latest version of Teamplify runner with pip:
$ pip3 install -U teamplifyOn 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 /Users folder is shared with Docker.
- Create a new Python virtual environment for Teamplify in your home directory:
$ python3 -m venv ~/.venv/teamplify- Activate it:
$ source ~/.venv/teamplify/bin/activate- At this point, a
pipcommand is linked to the virtual environment that you just created. Install Teamplify runner withpip:
$ pip install teamplifyTeamplify requires a configuration file to run.
- Run the following command to create the initial file:
$ teamplify configureThis creates a configuration file with default settings in your home
directory: ~/.teamplify.ini. You can specify the location of
your file with the --config option.
- 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]section
Other parameters are optional and can keep their default values. You can review them at the reference of all configuration options
When you run teamplify 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/file start
-
An environment variable named
TEAMPLIFY_CONF. Example:$ TEAMPLIFY_CONF=/path/to/configuration/file teamplify start
-
In the home directory of the current user:
~/.teamplify.ini; -
At
/etc/teamplify/teamplify.ini.
[main]
-
product_key- the product key of your installation. This is required. To get the product key, please email us at support@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, when it validates your domain with the HTTP-01 challenge, which does not support custom ports. You can still use custom HTTP and HTTPS ports if you switch to the DNS-01 challenge with theacme_challengeoption below, 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. Withmulti_workspaceenabled, it also needs a wildcard DNS record*.hostpointing to the same server, since every additional workspace is served on its own subdomain ofhost. IP addresses and single-label host names, such aslocalhost, work for a single workspace only;⚠️ Please use a dedicated domain or subdomain for Teamplify, such asteamplify.your-company-domain.com, rather than the apex domain of your company. Teamplify scopes its session and CSRF cookies to.{host}, so on an apex domain they would also be sent to every other host in that domain. This does not apply to IP addresses and single-label host names, which keep host-only cookies. -
port- the port on which Teamplify web interface will be running, the default is80. Must be80when Teamplify issues its own certificates over the HTTP-01 challenge (use_ssl = builtin,ssl_certsis empty andacme_challenge = http-01); -
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, theportsetting specifies the local port that Teamplify binds to (for the load balancer to forward traffic to), and the startup check will verify that your service is accessible athttps://<host>(standard port 443). Withmulti_workspaceenabled, both SSL modes need a certificate that covers*.host: see theacme_challengeandssl_certsoptions below forbuiltin, and make sure that your own proxy terminates wildcard TLS and forwards every*.hostname to Teamplify forexternal; -
ssl_port- the port on which Teamplify web interface will be running when SSL is enabled, the default is443. Must be443under the same condition asportabove; -
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 use Let's Encrypt to generate and renew SSL certificates for the domain that you specified in thehostparameter above.With
multi_workspaceenabled, the certificate must also cover*.host, either as a wildcard certificate or through a Subject Alternative Name. The file names, however, still follow thehostvalue and not the wildcard: forhost = example.comthe files must be namedexample.com.crtandexample.com.key, even though the certificate inside is issued for bothexample.comand*.example.com. If you would rather have Teamplify obtain and renew the wildcard certificate for you, leavessl_certsempty and use theacme_challengeoption below instead. -
acme_challenge(optional) - the challenge type that Let's Encrypt uses to verify that you own the domain. Possible values arehttp-01,dns-01andacme-dns, defaults tohttp-01. This option only has an effect whenuse_ssl = builtinandssl_certsis empty, that is, when Teamplify issues the certificates itself.The default,
http-01, verifies the domain over plain HTTP on the standard ports. It cannot issue wildcard certificates, so it cannot be combined withmulti_workspace.With
dns-01, the verification happens through a temporary TXT record that Teamplify creates in your DNS zone, so the certificate can also cover*.host, and it is renewed automatically just like the regular one. Nothing has to reach the server over HTTP for the validation, soportandssl_portare free to be non-standard. This requires API access to your DNS provider, configured through theacme_dns_api_configoption below.acme-dnsworks the same way for a DNS that has no API. Teamplify runs its own small DNS server, acme-dns, which answers the verification requests in a zone that you delegate to it once. On the firstteamplify start, the runner prints two records to add to the zone ofhost, for example:_acme.example.com. NS example.com. _acme-challenge.example.com. CNAME d420c923-bbd7-4056-ab64-c3ca54c9b3cf._acme.example.com.It then checks through a public resolver that they work and only starts Teamplify after that; run the first start in a terminal, so that you can confirm when the records are in place. From then on certificates are issued and renewed without touching your DNS again. This mode requires
hostto be a domain name whose A record points to this server, and port 53 of this server to be open to the Internet over both UDP and TCP. Docker publishes that port with firewall rules of its own, which on a host managed withufwmakes it reachable no matter whatufwallows; acme-dns answers for the delegated zone only. The records are tied to the credentials kept in theacme_dnsDocker volume: if the volume is lost, for example afterteamplify erase, the CNAME record has to be changed to the new value that the runner prints; -
acme_dns_api_config(optional) - a path to a file with the credentials of your DNS provider. Required whenacme_challengeis set todns-01, ignored otherwise, including foracme-dns. The file is in YAML format and is passed to acme.sh as is. TheDNS_APIkey names the acme.sh DNS API to use, and the rest of the keys are the credentials that this particular API expects. For example, for Cloudflare:DNS_API: dns_cf CF_Token: your-api-token CF_Account_ID: your-account-id
The list of the supported DNS providers and the credentials that each of them needs is available in the acme.sh documentation. The contents of this file are passed to the container that renews the certificates, where anyone who can use Docker on this server can read them, so we recommend an API token limited to the zone of
hostandchmod 600on the file itself; -
multi_workspace(optional) - possible values areyesandno, defaults tono. Set it toyesto host several independent workspaces on this installation. Each of them is then served on its own subdomain ofhost: a workspace nameddesignonhost = example.comis served atdesign.example.com. Teamplify serves every*.hostsubdomain and includes*.hostin the certificate it obtains. If the rest of the configuration cannot support this,teamplify startreports a configuration error and tells you what to change. The DNS record and the certificate that the subdomains need are not checked at startup: see thehost,use_sslandssl_certsoptions above; -
count(optional) - the number of web instances to run. The default is2.
[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 the SPF record of 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 is3.
After you have created the configuration file, start Teamplify with:
$ teamplify startOn 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 the host and
the port that 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 the Troubleshooting section below.
If you need to stop Teamplify, run:
$ teamplify stopAfter running Teamplify for the first time, follow the instructions to create an admin account
There's also a convenient command to stop the service and start it again. This is useful when applying changes made to the configuration:
$ teamplify restartAfter the first run, you need to create an admin account.
After the application first starts, run the following command:
$ teamplify createadmin --email <admin@email> --full-name <Full Name>Please check the output to make sure that no errors occurred.
With the createadmin command, 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.
Teamplify 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:
$ pip3 install -U teamplify
-
Update Teamplify itself:
$ teamplify update
The update command 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. The update command restarts the service only when necessary. If no
update has been downloaded, there is no restart and therefore no service
interruption.
Teamplify 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:
$ teamplify backup [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.
- for example,
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:
$ teamplify restore <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.
Backing 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 named
teamplify-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 && \
pip3 install -U teamplify && \
teamplify backup $BACKUP_LOCATION && \
teamplify update
# If the update was successful, clean up old backups:
if [ $? -eq 0 ]; then
find $BACKUP_LOCATION -type f -mmin +$((60 * 24 * $BACKUP_STORE_DAYS)) \
-name 'teamplify_*.sql.gz' -execdir rm -- '{}' \;
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_LOCATION and the value
for $BACKUP_STORE_DAYS as 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 use
aws s3 sync to
upload the backups to AWS S3.
-
When the maintenance script is ready, make it executable with
chmod +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):
0 3 * * * /path/to/the/script/teamplify-maintenance.shIn the example above, the script is scheduled to run daily at 3 AM. See cron syntax for a detailed explanation. When ready, save and close the file.
If 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:
$ teamplify erase- Uninstall Teamplify runner:
$ pip3 uninstall teamplifySo what could possibly go wrong?
Please check the following:
-
The service won't start if the configuration file is missing or contains errors. In such cases, the
teamplify startcommand will report a problem. Please inspect its output; -
There could be a problem with the domain name configuration. If the
teamplify 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 the Configuration. 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:
$ docker logs teamplify_app
Please let us know about the problem and attach the output from the command above. You can either open an issue on Github, or contact us at support@teamplify.com, or use the live chat on teamplify.com.
Emails 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 the SPF record of the domain used in
address_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:
$ docker logs teamplify_smtp
-
Alternatively, 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 in Configuration for details;
During 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 via Let's Encrypt that 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 the
hostparameter can be resolved from the public Internet and is pointing to the server on which you have installed Teamplify; - That ports
80and443are not blocked in the firewall.
It also might be helpful to check the logs:
$ docker logs teamplify_letsencryptA 503 error means that the request never reached Teamplify: the proxy in front of it received a host name that it doesn't serve. The main workspace keeps working in this case, only the workspace subdomains are affected. Please check the following:
- That
multi_workspace = yesis set in the[web]section of the configuration, and that Teamplify has been restarted since. Without it the built-in proxy only serves the barehost; - That the wildcard DNS record
*.hostexists and points to the same server as the record forhostitself. Without it, the browser either can't resolve the subdomain at all or resolves it to some other server; - That your proxy is configured for the subdomains, if you run Teamplify with
use_ssl = external. The proxy has to forward every*.hostname to Teamplify, and to pass the original host name through in theHostheader.
If the main workspace opens fine but a workspace subdomain reports an untrusted
certificate, then the certificate that Teamplify serves covers host but not
*.host. See the acme_challenge and ssl_certs options in the
Configuration for how to obtain a
certificate that covers both. If you have just switched acme_challenge to
dns-01, give the companion a few minutes to issue the new certificate, and
check its progress with:
$ docker logs teamplify_letsencryptWith acme_challenge = acme-dns, teamplify start doesn't start Teamplify
until it sees the records it asked for through a public resolver, and it lists
the problems it found. Please check the following:
- That both records are added exactly as printed, including the long name in the CNAME record. Changes to a DNS zone may take a while to become visible, so give them a few minutes and let the runner check again;
- That port 53 of this server is open to the Internet over both UDP and TCP, in the firewall of the server and of your cloud provider, if any. Otherwise neither the runner nor the certificate authority can reach acme-dns, even when the records are right;
- That nothing else on the server listens on port 53.
For any issue with Teamplify, we recommend that you try to check for updates first. 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 to open an issue on Github or contact us at support@teamplify.com. You can also use the live chat on teamplify.com. We're ready to help!
Teamplify 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 own terms and conditions.