DocsInstallationBare-metal (Linux)

Bare-metal (Linux)

Install Tether directly on a Linux server without Docker, using a Python virtual environment and optionally systemd for process management.

Consider Docker instead

Unless you have a specific reason to avoid Docker — existing infrastructure, no Docker available, policy restrictions — the Docker installation is simpler and more consistent.

Supported operating systems

Ubuntu 22.04 LTS or newer is recommended. Debian 12+ also works well. Other Linux distributions are supported but the commands below may differ.

Step 1 — Install system dependencies

bash
sudo apt update
sudo apt install -y python3 python3-pip python3-venv git curl

Verify your Python version:

bash
python3 --version
# Must be 3.10 or newer

Step 2 — Install and configure MariaDB

MariaDB is the recommended database. If you want to use PostgreSQL, see Database setup. If you want SQLite (not recommended for production), skip this step.

bash
sudo apt install -y mariadb-server

# Run the security script to set a root password and remove test data
sudo mysql_secure_installation

Create the Tether database and user:

bash
sudo mysql -e "CREATE DATABASE tether CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'tether'@'localhost' IDENTIFIED BY 'yourpassword';"
sudo mysql -e "GRANT ALL PRIVILEGES ON tether.* TO 'tether'@'localhost'; FLUSH PRIVILEGES;"
Use a strong database password

Replace yourpassword with a real password and record it — you will need it in your .env file.

Step 3 — Clone Tether

bash
git clone https://github.com/atechlab-am/tether
cd tether

Step 4 — Run the installer

bash
./install.sh

The installer:

  1. Creates a Python virtual environment at .venv/
  2. Installs all dependencies from requirements.txt into the venv
  3. Generates a .env file with a randomly generated SECRET_KEY
  4. Creates the data/ directory
  5. Prints instructions for starting the server

Step 5 — Configure .env

bash
nano .env

The most important values to set:

bash
# Already generated by install.sh — leave this as-is
SECRET_KEY=auto-generated-value

# Your actual domain
BASE_DOMAIN=yourdomain.com

# Admin account
[email protected]
ADMIN_PASSWORD=strong-password-here

# MariaDB connection
DB_HOST=localhost
DB_USER=tether
DB_PASSWORD=yourpassword
DB_NAME=tether

Step 6 — Start Tether

bash
source .venv/bin/activate
cd backend
export $(grep -v '^#' ../.env | xargs)
export TETHER_DATA=../data
uvicorn main:app --host 0.0.0.0 --port 8000

Visit http://your-server-ip:8000 to confirm it's running. Press Ctrl+C to stop.

Step 7 — Install as a systemd service (auto-start on boot)

bash
# Run as root — creates /etc/systemd/system/tether.service
sudo ./install.sh --service

After running this, Tether starts automatically on boot. Useful commands:

bash
# Check status
systemctl status tether

# View logs (live)
journalctl -u tether -f

# Restart after a config change
sudo systemctl restart tether

# Stop
sudo systemctl stop tether

# Start
sudo systemctl start tether

Updating

Always back up your database first. See Backup & restore.

bash
git pull
source .venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart tether

File permissions

Tether writes to the data/ directory (SQLite file, if used). This directory must be writable by the user running uvicorn. If you used sudo ./install.sh --service, check which user the service runs as: 

bash
grep "^User=" /etc/systemd/system/tether.service
# If it says root, it will have no permission issues
# If it says another user, make sure that user owns data/
sudo chown -R thetheruser:tetheruser data/

Related pages

← Previous
Docker
Last updated: May 2026