Installation

Detailed installation guide for FreeTAKServer on Linux, Windows, and macOS

This guide covers installing FreeTAKServer on different operating systems, including system requirements, dependencies, and deployment options.

System requirements

Before installing FreeTAKServer, ensure your system meets these minimum requirements:

Hardware requirements

Component	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	2 GB	4 GB+
Storage	1 GB	10 GB+ (for database and data packages)
Network	100 Mbps	1 Gbps

Software requirements

FreeTAKServer 2.x requires Python 3.11. Earlier versions are not compatible.

• Python: 3.11 or higher (3.11 recommended)
• Pip: Latest version
• Operating System:
  • Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+, or equivalent)
  • Windows 10/11 or Windows Server 2019+
  • macOS 11+ (Big Sur or later)

Network requirements

FTS requires these ports to be accessible:

Port	Protocol	Service	Purpose
8087	TCP	CoT Service	Client connections (ATAK/WinTAK)
8080	HTTP	Data Package Service	Data package uploads/downloads
8443	HTTPS	Secure Data Package Service	SSL data packages
8089	TCP/SSL	SSL CoT Service	Encrypted client connections
19023	HTTP	REST API	API endpoints
9000	TCP	Federation Server	Server-to-server connections (optional)

All ports are configurable. These are the default values.

Installing Python 3.11

If you don’t have Python 3.11 installed, follow these platform-specific instructions:

Ubuntu/Debian

# Add deadsnakes PPA for Python 3.11
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update

# Install Python 3.11
sudo apt install python3.11 python3.11-dev python3.11-venv

# Install pip
sudo apt install python3-pip

# Verify installation
python3.11 --version

RHEL/CentOS/Fedora

# RHEL 8/9 or CentOS 8/9
sudo dnf install python3.11 python3.11-devel

# Install pip
sudo dnf install python3-pip

# Verify installation
python3.11 --version

Windows

1. Download Python 3.11 from python.org/downloads
2. Run the installer
3. Important: Check “Add Python to PATH” during installation
4. Verify installation:

python --version

macOS

# Using Homebrew
brew install python@3.11

# Verify installation
python3.11 --version

# Ensure pip is installed
python3.11 -m ensurepip --upgrade

Installation methods

Choose the installation method that best fits your deployment:

Method 1: PyPI installation (recommended)

The simplest way to install FreeTAKServer is using pip from PyPI.

1. Install FreeTAKServer

   Install the latest stable version:

   Linux/macOS

   # Basic installation
   pip3 install FreeTAKServer
   
   # With optional UI
   pip3 install FreeTAKServer[ui]
   
   # With development tools
   pip3 install FreeTAKServer[dev]
   

   The [ui] extra installs FreeTAKServer_UI for web-based administration. The [dev] extra includes testing tools like pytest.

2. Verify installation

   Confirm FreeTAKServer is installed:

   pip3 show FreeTAKServer
   

   Expected output:

   Name: FreeTAKServer
   Version: 2.2.1
   Summary: An open source server for the TAK family of applications.
   

Method 2: Virtual environment installation

Using a virtual environment isolates FTS dependencies from other Python packages.

1. Create virtual environment

   # Create project directory
   mkdir freetakserver
   cd freetakserver
   
   # Create virtual environment
   python3.11 -m venv venv
   
   # Activate virtual environment
   source venv/bin/activate  # Linux/macOS
   venv\Scripts\activate     # Windows
   
2. Install FreeTAKServer

   # Upgrade pip
   pip install --upgrade pip
   
   # Install FreeTAKServer
   pip install FreeTAKServer[ui]
   
3. Create startup script

   Create a script to activate the environment and start FTS:

   start_fts.sh (Linux/macOS)

   #!/bin/bash
   cd /path/to/freetakserver
   source venv/bin/activate
   python -m FreeTAKServer.controllers.services.FTS -DataPackageIP $(hostname -I | awk '{print $1}')
   

   Make it executable (Linux/macOS):

   chmod +x start_fts.sh
   

Method 3: Development installation

For contributors or those who want to modify FTS source code:

1. Clone repository

   git clone https://github.com/FreeTAKTeam/FreeTakServer.git
   cd FreeTakServer
   
2. Install in editable mode

   # Create virtual environment
   python3.11 -m venv venv
   source venv/bin/activate
   
   # Install in editable mode
   pip install -e .
   
   # Or install with extras
   pip install -e ".[ui,dev]"
   
3. Run from source

   python -m FreeTAKServer.controllers.services.FTS -DataPackageIP YOUR_IP
   

Dependencies

FreeTAKServer automatically installs these core dependencies:

Web framework

Flask==3.0.2              # Web application framework
Flask-Cors==4.0.0         # Cross-origin resource sharing
Flask-HTTPAuth==4.8.0     # HTTP authentication
Flask-Login==0.6.3        # User session management
Flask-SocketIO==5.3.6     # WebSocket support
Flask-SQLAlchemy==3.1.1   # Database ORM
Flask-Classy==0.6.10      # Class-based views
Werkzeug==3.0.1           # WSGI utilities

Database and ORM

SQLAlchemy==2.0.29        # SQL toolkit and ORM

Data processing

lxml                      # XML processing
defusedxml==0.7.1         # Secure XML parsing
xmltodict                 # XML to dict conversion
protobuf==3.18.3          # Protocol buffers
pykml==0.2.0              # KML generation

Async and networking

eventlet==0.36.1          # Concurrent networking
python-socketio==5.11.1   # Socket.IO server
python-engineio==4.9.0    # Engine.IO server
pyzmq                     # ZeroMQ messaging

Security and cryptography

cryptography==36.0.2      # Cryptographic primitives
pyOpenSSL==22.0.0         # OpenSSL wrapper
bcrypt==3.1.7             # Password hashing
PyJWT                     # JSON Web Tokens

Geospatial

geographiclib==1.52       # Geodesic calculations
geopy==2.2.0              # Geocoding and distance

Utilities

tabulate==0.8.7           # Table formatting
click==8.1.7              # Command-line interface
colorama==0.4.4           # Colored terminal output
PyYAML==6.0.1             # YAML parser
ruamel.yaml==0.17.21      # Advanced YAML processing
qrcode==7.3.1             # QR code generation
pillow==9.3.0             # Image processing

FTS-specific

digitalpy>=0.3.13.7       # FTS framework layer
opentelemetry-sdk         # Telemetry and tracing

You don’t need to install these manually. Pip handles all dependencies automatically.

Platform-specific installation

Ubuntu/Debian

Complete installation on Ubuntu:

1. Update system

   sudo apt update && sudo apt upgrade -y
   
2. Install dependencies

   # Install Python 3.11 and development tools
   sudo apt install python3.11 python3.11-dev python3.11-venv \
                    python3-pip build-essential libssl-dev \
                    libffi-dev libxml2-dev libxslt1-dev zlib1g-dev
   
3. Install FreeTAKServer

   pip3 install FreeTAKServer[ui]
   
4. Configure firewall

   # Allow FTS ports
   sudo ufw allow 8087/tcp  # CoT Service
   sudo ufw allow 8080/tcp  # Data Packages
   sudo ufw allow 8443/tcp  # HTTPS Data Packages
   sudo ufw allow 8089/tcp  # SSL CoT
   sudo ufw allow 19023/tcp # REST API
   sudo ufw enable
   

Windows

Complete installation on Windows:

1. Install Python

   1. Download Python 3.11 from python.org
   2. Run installer with “Add to PATH” checked
   3. Open Command Prompt as Administrator
2. Install FreeTAKServer

   python -m pip install --upgrade pip
   python -m pip install FreeTAKServer[ui]
   
3. Configure Windows Firewall

   Open PowerShell as Administrator:

   # Allow FTS ports
   New-NetFirewallRule -DisplayName "FTS CoT Service" -Direction Inbound -LocalPort 8087 -Protocol TCP -Action Allow
   New-NetFirewallRule -DisplayName "FTS Data Packages" -Direction Inbound -LocalPort 8080 -Protocol TCP -Action Allow
   New-NetFirewallRule -DisplayName "FTS SSL CoT" -Direction Inbound -LocalPort 8089 -Protocol TCP -Action Allow
   
4. Start FTS

   python -m FreeTAKServer.controllers.services.FTS -DataPackageIP YOUR_IP
   

   Use Command Prompt, not PowerShell. PowerShell can cause issues with FTS.

RHEL/CentOS

Complete installation on RHEL-based systems:

1. Install EPEL repository

   # RHEL 8/9
   sudo dnf install epel-release
   sudo dnf update
   
2. Install dependencies

   sudo dnf install python3.11 python3.11-devel gcc \
                    openssl-devel libffi-devel libxml2-devel \
                    libxslt-devel zlib-devel
   
3. Install FreeTAKServer

   pip3.11 install FreeTAKServer[ui]
   
4. Configure firewalld

   # Allow FTS ports
   sudo firewall-cmd --permanent --add-port=8087/tcp
   sudo firewall-cmd --permanent --add-port=8080/tcp
   sudo firewall-cmd --permanent --add-port=8089/tcp
   sudo firewall-cmd --permanent --add-port=19023/tcp
   sudo firewall-cmd --reload
   

macOS

Complete installation on macOS:

1. Install Homebrew

   If not already installed:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
2. Install Python 3.11

   brew install python@3.11
   brew link python@3.11
   
3. Install FreeTAKServer

   pip3.11 install FreeTAKServer[ui]
   
4. Configure firewall (if enabled)

   If macOS firewall is enabled, allow FTS in: System Preferences → Security & Privacy → Firewall → Firewall Options

Running as a system service

For production deployments, run FTS as a system service that starts automatically.

Linux systemd service

1. Create service file

   Create /etc/systemd/system/freetakserver.service:

   [Unit]
   Description=FreeTAKServer
   After=network.target
   
   [Service]
   Type=simple
   User=fts
   WorkingDirectory=/home/fts
   ExecStart=/usr/bin/python3.11 -m FreeTAKServer.controllers.services.FTS -DataPackageIP YOUR_IP
   Restart=on-failure
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
   

   Replace YOUR_IP with your server’s IP address.

2. Create FTS user

   # Create dedicated user
   sudo useradd -r -s /bin/false fts
   
   # Create home directory
   sudo mkdir -p /home/fts
   sudo chown fts:fts /home/fts
   
3. Enable and start service

   # Reload systemd
   sudo systemctl daemon-reload
   
   # Enable service to start on boot
   sudo systemctl enable freetakserver
   
   # Start service
   sudo systemctl start freetakserver
   
   # Check status
   sudo systemctl status freetakserver
   
4. View logs

   # Follow logs in real-time
   sudo journalctl -u freetakserver -f
   
   # View recent logs
   sudo journalctl -u freetakserver -n 100
   

Windows service

To run FTS as a Windows service:

1. Install NSSM

   Download and install NSSM (Non-Sucking Service Manager): nssm.cc/download

2. Create service

   Open Command Prompt as Administrator:

   nssm install FreeTAKServer
   

   Configure in the GUI:

   • Path: C:\Python311\python.exe
   • Startup directory: C:\FTS
   • Arguments: -m FreeTAKServer.controllers.services.FTS -DataPackageIP YOUR_IP
3. Start service

   nssm start FreeTAKServer
   

Updating FreeTAKServer

To update to the latest version:

# Stop FTS if running
sudo systemctl stop freetakserver  # Linux

# Update via pip
pip3 install --upgrade FreeTAKServer

# Restart FTS
sudo systemctl start freetakserver  # Linux

Subscribe to the PyPI RSS feed to be notified of new releases.

Verifying installation

After installation, verify everything is working:

1. Check Python version

   python3 --version
   # Should show Python 3.11.x
   
2. Check FreeTAKServer version

   pip3 show FreeTAKServer | grep Version
   
3. Test startup

   python3 -m FreeTAKServer.controllers.services.FTS --help
   

   Should display command-line options without errors.

4. Check ports

   After starting FTS, verify ports are listening:

   # Linux/macOS
   sudo netstat -tuln | grep -E '8087|8080|19023'
   
   # Windows
   netstat -an | findstr "8087 8080 19023"
   

Troubleshooting

pip install fails with compiler errors

Install build dependencies:

Ubuntu/Debian:

sudo apt install build-essential python3.11-dev libssl-dev libffi-dev

RHEL/CentOS:

sudo dnf install gcc python3.11-devel openssl-devel libffi-devel

macOS:

xcode-select --install

ModuleNotFoundError when starting FTS

Ensure you’re using the correct Python version:

# Check which Python installed FTS
pip3 show FreeTAKServer

# Use that Python version to run FTS
python3.11 -m FreeTAKServer.controllers.services.FTS -DataPackageIP YOUR_IP

Permission denied errors

Linux:

# Install for current user only
pip3 install --user FreeTAKServer

# Or use virtual environment (recommended)
python3.11 -m venv venv
source venv/bin/activate
pip install FreeTAKServer

Windows: Run Command Prompt as Administrator.

SSL/TLS errors during installation

Update pip and try again:

pip3 install --upgrade pip setuptools wheel
pip3 install --upgrade certifi
pip3 install FreeTAKServer

lxml installation fails

Install XML development libraries:

Ubuntu/Debian:

sudo apt install libxml2-dev libxslt1-dev

RHEL/CentOS:

sudo dnf install libxml2-devel libxslt-devel

macOS:

brew install libxml2 libxslt

Next steps

Quick start

Follow the quick start guide to get FTS running

Configuration

Configure ports, SSL, and advanced options

SSL setup

Set up SSL encryption for secure communications

Docker deployment

Deploy FTS in production with Docker