How to Install Teampass on Debian 13 with a Two-Server Setup (MySQL 8 + Nginx & PHP 8.4)

Linux

If you are looking for an open source, self-hosted password manager for teams, Teampass is a solid choice. It gives you centralised credential storage, fine-grained access control and an audit trail, without sending sensitive data to a third-party cloud.

In this guide, we will build a clean two-server Teampass lab on Debian 13.2:

  • DB server: MySQL 8 on Debian 13.2
  • APP server: Nginx + PHP 8.4 (FPM) + Teampass
  • Hardware: 2 vCPU and 4 GB RAM per server (perfect for testing)

The goal is to give you a step-by-step installation that is realistic enough for later production hardening, but simple enough to follow in a lab.

Why use a two-server architecture for Teampass?

Teampass can run on a single machine, but splitting the database and application into two servers brings several advantages, even in a small environment:

  • Isolation: A compromise of the web server does not automatically give full control over the database host.
  • Scalability: You can scale the DB and APP tiers separately when the number of users grows.
  • Cleaner responsibilities: One VM for data storage, one VM for the web app and PHP runtime.

We will use the following example IP addresses. Adjust them to your own network:

  • DB server: 10.0.0.10
  • APP server: 10.0.0.11

Prerequisites

Before you start, make sure you have:

  • Two fresh Debian 13.2 virtual machines.
  • SSH access with sudo privileges.
  • Basic familiarity with editing configuration files in the terminal.

All commands below are executed as a regular user with sudo privileges.

Step 1 – Prepare the MySQL 8 database server

1.1 Install base packages

On the DB server:

sudo apt update
sudo apt install -y vim curl wget ca-certificates gnupg lsb-release apt-transport-https
sudo timedatectl set-timezone Europe/Bratislava

1.2 Install MySQL 8 from the official MySQL APT repository

Debian 13 repositories may not ship the exact MySQL version you want, so we use the official MySQL APT repo:

cd /tmp
wget https://dev.mysql.com/get/mysql-apt-config_0.8.36-1_all.deb
sudo dpkg -i mysql-apt-config_0.8.36-1_all.deb   # select MySQL 8.0 in the menu

sudo apt update
sudo apt install -y mysql-server
sudo systemctl enable --now mysql

1.3 Run the basic MySQL hardening script

Even in a lab, it is worth running the hardening wizard:

sudo mysql_secure_installation

For a test environment, you can keep the answers simple: remove anonymous users, disallow remote root, remove the test database and reload privileges.

1.4 Allow the APP server to connect

By default, MySQL listens only on 127.0.0.1. We need to open it for the APP server:

sudo vim /etc/mysql/mysql.conf.d/mysqld.cnf

Change the bind address to:

bind-address = 0.0.0.0

Then restart MySQL:

sudo systemctl restart mysql

In a production setup you would combine this with a firewall rule that only allows port 3306 from the application server.

1.5 Create the Teampass database and user

Connect to MySQL as root:

sudo mysql -u root -p

Create a dedicated database and user for Teampass:

CREATE DATABASE teampass
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_general_ci;

CREATE USER 'teampass'@'10.0.0.11'
  IDENTIFIED BY 'SuperTajneHeslo123!';

GRANT ALL PRIVILEGES ON teampass.* TO 'teampass'@'10.0.0.11';
FLUSH PRIVILEGES;
EXIT;

Remember this password – you will enter it later in the Teampass installer.

Step 2 – Prepare the application server (Nginx + PHP 8.4)

2.1 Install base packages

On the APP server:

sudo apt update
sudo apt install -y vim curl wget ca-certificates gnupg lsb-release apt-transport-https
sudo timedatectl set-timezone Europe/Bratislava

2.2 Add the Sury PHP repository

To get PHP 8.4 on Debian, we use the well-known Sury PHP repository:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://packages.sury.org/php/apt.gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/sury-php.gpg

echo "deb [signed-by=/etc/apt/keyrings/sury-php.gpg] https://packages.sury.org/php $(lsb_release -sc) main" \
  | sudo tee /etc/apt/sources.list.d/sury-php.list

sudo apt update

2.3 Install Nginx, PHP 8.4 and required PHP extensions

Teampass needs several PHP modules. Install Nginx, PHP-FPM and the extensions in one go:

sudo apt install -y nginx

sudo apt install -y \
  php8.4 php8.4-fpm \
  php8.4-mysql php8.4-curl php8.4-gd php8.4-mbstring \
  php8.4-xml php8.4-zip php8.4-bcmath php8.4-gmp php8.4-ldap

sudo systemctl enable --now nginx php8.4-fpm

2.4 Tune PHP settings for Teampass

Edit the PHP-FPM configuration:

sudo vim /etc/php/8.4/fpm/php.ini

Adjust a few important settings:

memory_limit = 512M
upload_max_filesize = 32M
post_max_size = 32M
max_execution_time = 300
date.timezone = Europe/Bratislava

Reload PHP-FPM:

sudo systemctl reload php8.4-fpm

2.5 (Optional) Test connectivity to MySQL

It is useful to verify the APP server can reach the database:

sudo apt install -y mysql-client
mysql -h 10.0.0.10 -u teampass -p

If you can log in and run SHOW TABLES; in the teampass database (it will be empty for now), network and credentials are correct.

Step 3 – Download and prepare Teampass

3.1 Clone the Teampass repository

On the APP server, we place the Teampass code under /var/www/teampass:

cd /var/www
sudo git clone https://github.com/nilsteampassnet/TeamPass.git teampass
cd teampass
sudo git checkout 3.1.4.43

Create the saltkey directory (used for encryption keys):

sudo mkdir /var/www/teampass/saltkey

3.2 Create a secure path outside the webroot

During installation Teampass will ask for the Absolute path to secure path. This is a directory where it stores sensitive data, ideally outside the webroot. Create it like this:

sudo mkdir -p /var/teampass-secure
sudo chown -R www-data:www-data /var/teampass-secure
sudo chmod 750 /var/teampass-secure

Later, in the installer, you will enter:

  • Absolute path to secure path: /var/teampass-secure

3.3 Set permissions for the Teampass files

For a lab environment we can use a practical, slightly relaxed permission set:

sudo chown -R www-data:www-data /var/www/teampass

sudo find /var/www/teampass -type d -exec chmod 750 {} \;
sudo find /var/www/teampass -type f -exec chmod 640 {} \;

cd /var/www/teampass
sudo chmod 770 backups files install saltkey \
  includes/config includes/avatars \
  includes/libraries/csrfp/log \
  includes/libraries/csrfp/libs \
  includes/libraries/csrfp/js 2>/dev/null || true

For production you would tighten some of these permissions later as part of your hardening phase.

Step 4 – Configure Nginx for Teampass

4.1 Create an Nginx server block

Create a new virtual host config on the APP server:

sudo vim /etc/nginx/sites-available/teampass.conf

Paste the following configuration and adjust the server_name to your own hostname or IP:

server {
    listen 80;
    server_name teampass.lab.local;  # change to your FQDN or IP

    root /var/www/teampass;
    index index.php index.html;

    access_log /var/log/nginx/teampass_access.log;
    error_log  /var/log/nginx/teampass_error.log;

    client_max_body_size 32M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        try_files $uri $uri/ =404;
        access_log off;
        expires max;
    }

    location ~ /\. {
        deny all;
    }
}

Enable the site and reload Nginx:

sudo ln -s /etc/nginx/sites-available/teampass.conf \
          /etc/nginx/sites-enabled/teampass.conf

sudo rm /etc/nginx/sites-enabled/default 2>/dev/null || true

sudo nginx -t
sudo systemctl reload nginx

At this point, browsing to http://teampass.lab.local should show the Teampass installer.

Step 5 – Run the Teampass web installer

5.1 Open the installer

In your browser, go to:

http://teampass.lab.local/install/install.php

The installer will run a series of checks: PHP version, extensions and file permissions. If you followed the previous steps, all requirements should pass.

5.2 Enter database connection details

Use the values we created earlier:

  • DB host: 10.0.0.10
  • DB name: teampass
  • DB user: teampass
  • DB password: SuperTajneHeslo123! (or your own)
  • DB port: 3306

Teampass will create the necessary tables in the database.

5.3 Configure salt key and secure path

In the next step, point Teampass to the paths we prepared:

  • Saltkey folder: /var/www/teampass/saltkey
  • Absolute path to secure path: /var/teampass-secure

Then create the first admin account with a strong password. This account will manage roles, folders and user permissions.

5.4 Clean up the installer

After the installation finishes successfully and you can log into Teampass, remove the installer directory:

cd /var/www/teampass
sudo rm -rf install

This prevents accidental re-runs of the installation wizard.

What to do next: hardening and integration

You now have a working two-server Teampass lab on Debian 13, using MySQL 8 and Nginx with PHP 8.4. From here you can:

  • Add HTTPS with a Let's Encrypt certificate for secure browser access.
  • Lock down MySQL and Nginx with a firewall and stricter access controls.
  • Integrate Teampass with your LDAP or Active Directory for centralised user management.
  • Set up regular backups of the Teampass database, the saltkey directory and the secure path under /var/teampass-secure.

Even if this is “only” a lab today, building it on a clean two-server architecture makes it much easier to turn into a production-ready, hardened password management service for your organisation tomorrow.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.