From e09a9e07a269df6b06e36f427ba3ed2cdda20a40 Mon Sep 17 00:00:00 2001 From: Az Builds Date: Tue, 31 Oct 2023 23:41:45 -0400 Subject: [PATCH 1/7] Update 1_install.md, reformat Adding first draft of RHEL/Fedora/Centos instructions Fix typos and update styling --- docs/docs/Installation/Linux/1_Install.md | 394 ++++++++++++---------- 1 file changed, 218 insertions(+), 176 deletions(-) diff --git a/docs/docs/Installation/Linux/1_Install.md b/docs/docs/Installation/Linux/1_Install.md index d3f7fa971..21c667269 100644 --- a/docs/docs/Installation/Linux/1_Install.md +++ b/docs/docs/Installation/Linux/1_Install.md @@ -1,322 +1,364 @@ -# 1. FreeTAK Server Installation -This guide will walk you through installing FreeTAKServer 1.9 on a Linux host. -you need to prepare for the followin steps, not all of them are required: +# FreeTAK Server Installation +This guide will walk you through installing FreeTAKServer 2.0 -- [Creates target machines](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/Installation/PyPi/Linux/ConfigureMachine.md) +## 0. Document Goals + +- Prepare host OS - Install FreeTAKServer - Configure and Run FreeTAKServer - Configure Web UI - Install [NodeRed](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/NodeRedinstallation.md) for FreeTAKHub -- Install the [web Map](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/WebMap/Installation.md) +- Install the [Web Map](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/WebMap/Installation.md) - Install the [Video Service](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/Video/Installation.md) +--- +## Note: Linux Distributions -## Linux Distribution +The main supported OS is Ubuntu 20.04. Due to cross-compatibility, Debian 10 and the latest Raspbian also work. -A part Ubuntu 20.04, you may use Debian 10 or Raspberry PI OS. +Centos/RHEL/Fedora installation instructions are provided on a best-effort volunteer basis. +--- +## 1. Update OS Packages -## Upgrade your distro +**Ubuntu** -``` +```bash sudo apt update && sudo apt upgrade ``` -tap Y and Enter -this will bring Ubuntu to the last pathch level -type +**RHEL** +```bash +sudo dnf update ``` -Python3 -``` -in the console -### OPTIONAL Install Python 3 -this should not be necessary if you follow the instruction until now, however if the command Python3 fails type: +--- +## 2. Pre-requisite Software + +**Ubuntu** + +Install packages from the distro repo ```bash sudo apt update && sudo apt install python3 && sudo apt install python3-pip +sudo apt install python3-dev python3-setuptools build-essential python3-gevent python3-lxml libcairo2-dev ``` -### Install Pip -Pip is the package manager for Python +**RHEL** -``` -sudo apt update && apt install python3-pip +Install distro repo packages + +```bash +sudo dnf group install "C Development Tools and Libraries" "Development Tools" +sudo dnf install python3 python3-pip cairo cairo-devel python3-cairo python3-cairo-devel python3-gevent python3-lxml python3-virtualenv ``` -### Install Python Libraries +Create and activate a virtualenv for the next steps ```bash -sudo apt install python3-dev python3-setuptools build-essential python3-gevent python3-lxml libcairo2-dev +virtualenv venv +source venv/bin/activate ``` + +--- +## 3. Install Python Libraries + +**Ubuntu** + +```bash +sudo pip3 install wheel pycairo ``` -sudo pip3 install wheel pycairo + +Note, use of pip with sudo is not recommended and you will be warned about this! + + +**RHEL** + + +```bash +pip install wheel pycairo ``` + ![image](https://user-images.githubusercontent.com/60719165/142766382-8a6e5d05-a198-488d-86f2-67cd49cc1ca6.png) -### delete previous installation -required only if: -- you have an existing installation -- Upgrade fails. +--- +## 4. Remove Old Installation +**YOU MUST DO THIS IF:** + +- Free TAK Server has been installed before +- An upgrade fails +- A previous installation was not completed + +**Ubuntu** ```bash sudo pip3 uninstall FreeTAKServer sudo pip3 uninstall FreeTAKServer-UI ``` -Delete the database +**RHEL** + ```bash -sudo rm /root/FTSDataBase.db +pip uninstall FreeTAKServer FreeTAKServer-UI ``` -and the various logs folders +Delete the database and log folders + ```bash -sudo rm -r /usr/local/lib/python3.8/dist-packages/FreeTAKServer +sudo rm /root/FTSDataBase.db +sudo rm -r /usr/local/lib//-packages/FreeTAKServer ``` -### Install FreeTAKServer -Install the FTS and the Web UI (suggested) +--- +## 5. Install FreeTAKServer +Install the FreeTAKServer and the associated Web UI + +**Ubuntu** + ```bash sudo python3 -m pip install FreeTAKServer[ui] ``` -in alternative Install the FTS only +**RHEL** + ```bash -sudo python3 -m pip install FreeTAKServer +pip install FreeTAKServer[ui] ``` -#### Install a specific version -To install a special version of a FTS package with Pip, you can use the following command: -```python3 -m pip install FreeTAKServer[ui]==version-number``` -For example, if you want to install version Alpha of the requests package, you can run the following command: +The FreeTAKServer can be installed without the UI, however this makes the +server much more difficult to use and is probably not what you want. This can be done using the `FreeTAKServer` pip package. -```python3 -m pip install FreeTAKServer[ui]==0.2.0.13``` -This will download and install version 0.2.0.13 of FTS, rather than the latest version available on PyPI. +### Advanced Installations: Install a specific version +To install a special version of a FreeTAKServer pip package by appending `==version-number` to the installation command. -### check your install ```bash -pip check FreeTakServer +python3 -m pip install FreeTAKServer[ui]==version-number ``` -![image](https://user-images.githubusercontent.com/60719165/142766403-b877a43b-ec9d-48ce-a13c-b216ddcfa295.png) -#### Install an old version -you can install a [past version](https://pypi.org/project/FreeTAKServer/#history) using this command -``` -sudo python3 -m pip install FreeTAKServer[ui]==[VERSIONNUMBER] -``` +For example, if you want to install version Alpha of the requests package, you can run the following command: -for example if you want to install version 1.5 -``` -sudo python3 -m pip install FreeTAKServer[ui]==1.5.10 +```bash +python3 -m pip install FreeTAKServer[ui]==0.2.0.13 ``` -## Configure and Run FTS (1.9+) -this works only for 1.9 or better, for see here for [manual configuration](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/Installation/PyPi/Linux/ManualConfiguration.md) -start FTS -``` -sudo python3 -m FreeTAKServer.controllers.services.FTS -``` +Old installations can be installed in the same way, if desired. -the first time a wizard will popup +This will download and install version 0.2.0.13 of FreeTAKServer. If no version number is specified, then the latest normal release will be installed. -![image](https://user-images.githubusercontent.com/60719165/142766476-f1b5bbb9-aba5-4e05-9b53-a15c075d7e96.png) +--- +## 6. Check Installation -if the wizard does not show up please check your config file (see [troubleshooting](https://freetakteam.github.io/FreeTAKServer-User-Docs/Installation/Troubleshooting/troubleshooting/) ) +The pip utility allows the user to check the installation status of a package. -``` -would you like to use a yaml config file, - if yes you will be prompted for further configuration options [yes]: yes +**Ubuntu/RHEL** -``` - - press enter - -``` -where would you like to save the yaml config [/opt/FTSConfig.yaml]: +```bash +pip check FreeTakServer ``` +![image](https://user-images.githubusercontent.com/60719165/142766403-b877a43b-ec9d-48ce-a13c-b216ddcfa295.png) -from now on, hit ENTER if you are happy with the default +--- +## 7. Configure and Run FreeTAKServer +this works only for 1.9 or better, for see here for [manual configuration](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/Installation/PyPi/Linux/ManualConfiguration.md) -the public IP will be automatically discovered (you can double check in your digital Ocena console for safety) +Start the FreeTAKServer +**Ubuntu** -``` -enter ip [10.0.2.15]: -10.0.2.15 +```bash +sudo python3 -m FreeTAKServer.controllers.services.FTS ``` -this is the FTS_MAIN_IP, must be you EXTERNAL IP -continue to follow the instructions: +**RHEL** -``` -**enter the preferred database path [/opt/FTSDataBase.db]: ** -/opt/FTSDataBase.db +```bash +python -m FreeTAKServer.controllers.services.FTS ``` -![image](https://user-images.githubusercontent.com/60719165/142766542-18876805-9454-4725-849b-f794036c2848.png) +On the first run, a configuration wizard will help set up the config file. +![image](https://user-images.githubusercontent.com/60719165/142766476-f1b5bbb9-aba5-4e05-9b53-a15c075d7e96.png) -next one is important, adjust the path to your Python install +**If the wizard does not show up, see [troubleshooting](https://freetakteam.github.io/FreeTAKServer-User-Docs/Installation/Troubleshooting/troubleshooting/).** -![image](https://user-images.githubusercontent.com/60719165/142766601-30560314-9ac1-4fe2-8e8b-91d0057b1991.png) +The default configuration option is presented in [brackets]. +If the default is acceptable you can simply press enter to use the default. +An example is provided, your exact configuration will differ. -``` -enter the preferred main_path [/usr/local/lib/python3.8/dist-packages/FreeTAKServer]: -/usr/local/lib/python3.8/dist-packages/FreeTAKServer -``` +```css +would you like to use a yaml config file, + if yes you will be prompted for further configuration options [yes]: +where would you like to save the yaml config [/opt/fts/FTSConfig.yaml]: +enter ip [127.0.0.1]: +enter the preferred database type (MySQL is highly experimental if you're not sure leave default) [SQLite]: +enter the preferred database path [/opt/fts/FTSDataBase.db]: +enter the preferred main path [/usr/local/lib/python3.11/site-packages/FreeTAKServer]: +enter the preferred log file path [/opt/fts/Logs]: -the log can be located anywhere on your machine ``` -enter the preferred log file path [/usr/local/lib/python3.8/dist-packages/FreeTAKServer/Logs]: -/usr/local/lib/python3.8/dist-packages/FreeTAKServer/Logs -``` - -at this point a YAML file is created under the location you selected (default is /opt/FTSConfig.yaml). FTS will start all the services. -![image](https://user-images.githubusercontent.com/60719165/142766645-210f09c3-88f5-435a-8a0d-d27bc3d4f1c3.png) -### content of the YAML file +**The IP in this configuration wizard is the FTS_MAIN_IP. +This must be your EXTERNAL IP.** -![image](https://user-images.githubusercontent.com/60719165/142766660-daac490a-3c0c-4089-b3b8-40c5e520c1ff.png) +MySQL usage is beyond the scope of this guide. -If you want to modify the YAML file you need to stop FTS and modify the YAML and then restart it. -CTRL + C (2 times) in the console will stoop FTS +The database and log filepath can be anywhere that the host user can access. -#### Additional FTS configuration -FTS sends a welcome message every time a client connects. This can be changed in the file MainConfig.py +The main path should be the directory where pip installed FreeTAKServer. This can be found under your python packages directory. In virtualenv installations, it is inside the virtualenv directory. -``` - ConnectionMessage = f'Welcome to FreeTAKServer {version}. The Parrot is not dead. It’s just resting' -``` -### SUCCESS!!! -your FTS is now started -![image](https://user-images.githubusercontent.com/60719165/142766636-16cb4097-73e3-4bce-8442-b6b034687dd0.png) +The wizard creates the YAML configuration file is created under the location you selected (default is /opt/FTSConfig.yaml). -After that you have completed the setup you may want to create a [Service](Service.md) so that FTS will run even if you close the console. +FreeTAKServer will then proceed start all the services. +![image](https://user-images.githubusercontent.com/60719165/142766645-210f09c3-88f5-435a-8a0d-d27bc3d4f1c3.png) +--- +## 7. FTSConfig.yaml Additional Configuration -### Configure Web UI -the Web UI is an optional component, however it's required to properly control FTS. +![image](https://user-images.githubusercontent.com/60719165/142766660-daac490a-3c0c-4089-b3b8-40c5e520c1ff.png) +Before modifying the YAML file FreeTAKServer **must be stopped**. -open a new console Session and type +Use the keyboard chord CTRL + C twice in the console will stop FreeTAKServer. +## 8. Additional FTS configuration +FTS sends a welcome message on client connection which is configurable. See the `FreeTAKServer/core/configuration/MainConfig.py` file to change it. ``` -cd /usr/local/lib/python3.8/dist-packages/FreeTAKServer-UI + ConnectionMessage = f'Welcome to FreeTAKServer {version}. The Parrot is not dead. It’s just resting' ``` -or use WinSCP to navigate -![image](https://user-images.githubusercontent.com/60719165/142766762-580c8faf-c7ee-4596-a966-b59c72696c20.png) +--- +## 9. Configure Web UI -edit the file called -``` -config.py -``` -![image](https://user-images.githubusercontent.com/60719165/142766782-e003c5b2-f707-4c9f-93ea-a7bef8d896c6.png) +Edit the `config.py` file in the `FreeTAKServer-UI` directory where it was installed by pip. -set the IP value to your external IP -``` - IP = '127.0.0.1' -``` -for example only do not use it -![image](https://user-images.githubusercontent.com/60719165/142766838-f5823555-9839-4a5e-81e3-196888215dd3.png) +Edit the IP value to your external IP, for example: -set the webmap IP -``` -WEBMAPIP = YOURIP +```python +# this IP will be used to connect with the FTS API +IP = '192.168.1.100' ``` -for example only do not use it +Set the web map IP address, for example: + +:warning: **Warning: Original intent is unknown, this configuration is a best-guess.** + +```python +# the public IP your server is exposing +APPIP = '0.0.0.0' +# webmap IP +WEBMAPIP = "192.168.1.100" + +``` -![image](https://user-images.githubusercontent.com/60719165/142767734-4346ff2a-0df8-4fa6-81ea-9a5c5cbc313c.png) +In a default installation, the port should be `19023`. +Advanced users may wish to use a different port. -the port the UI uses to communicate with the backend +```python + # Port the UI uses to communicate with the API PORT = '19023' +``` +The following can be updated to use your own secrets, however the values must be +updated in both the `FreeTAKServer-UI/config.py` and the `FreeTAKServer/core/configuration/MainConfig.py` files. + If you change those values in the UI you must change also the YAML file configurtation the API key used by the UI to comunicate with FTS. generate a new system user and then set it +```python +app.config['APIKEY'] = 'Bearer [API_TOKEN]' +app.config['WEBSOCKETKEY'] = '[Your_Web_socket_Key]' ``` -app.config['APIKEY'] = 'Bearer [API_TOKEN]' -``` - -the webSocket key used by the UI to comunicate with FTS. must be the same value specified in the FTS config. - ``` - app.config['WEBSOCKETKEY'] = '[Your_Web_socket_Key]' - ``` -OPTIONAL -``` - SQLALCHEMY_DATABASE_URI = 'sqlite:///' + '/root/FTSDataBase.db' -``` +### 9.1 MySQL Configuration + +To use a MySQL database, update the URI to point to your database. + +Database setup is beyond the scope of this document. -To use a MySQL database change the above line as follows ```python SQLALCHEMY_DATABASE_URI = 'mysql://' + 'user:pass@localhost/dbname' - ``` - #### Additional configuration - additional parameters for the UI are in the __init__.py - ``` +``` + +### 9.2 Miscellaneous Parameters +Additional parameters can be found in the `__init__.py` file. + +``` FreeTAKServer-UI/app/__init__.py ``` this include the frequence of the update for the dashboard and the file limit for data packages +```python +app.config['USERINTERVAL'] = '180000'; +app.config['SERVERHEALTHINTERVAL'] = '180000'; +app.config['SYSSTATUSINTERVAL'] = '600000'; +app.config['DATAPACKAGESIZELIMIT'] = '15360000'; ``` - app.config['USERINTERVAL'] = '180000'; - app.config['SERVERHEALTHINTERVAL'] = '180000'; - app.config['SYSSTATUSINTERVAL'] = '600000'; - app.config['DATAPACKAGESIZELIMIT'] = '15360000'; -``` - #### Installation on a Separate machine +### 10. Start UI +While in terminal, navigate to the `FreeTAKServer-UI` directory wherever it was +installed by the pip utility. + + Run the UI using + +**Ubuntu** + + ```bash + sudo python3 run.py + ``` + + **RHEL** + + ```bash + python run.py + ``` + + ![image](https://user-images.githubusercontent.com/60719165/142767800-e09ef09c-d6d7-4a11-bcc4-0f4a09597bb1.png) + + +--- +## 11. Next Steps + +### Create a service + +To run the server without keeping the console open, a service can be created. + +*See: [Service](Service.md)* + +### Installation on a Separate machine Typically the web UI is installed on the same machine as FTS, however you can install it on a separate machine and even use it to manage several instances. + If you're installing FTS-UI on a separate server the following commands may help: -``` Bash +```bash sudo pip install WTForms==2.3.3 sudo pip install SQLAlchemy==1.3.20 sudo pip install eventlet ``` -you will need also to set in the config file +The config file will also need to be updated. -``` +```python IP = [FTS external IP] APPIP = [FTS-UI internal IP] ``` - - ### start the UI - in the console type navigate to the installation path - - ``` - cd /usr/local/lib/python3.8/dist-packages/FreeTAKServer-UI - ``` - - type - - ``` - sudo python3 run.py - ``` - - ![image](https://user-images.githubusercontent.com/60719165/142767800-e09ef09c-d6d7-4a11-bcc4-0f4a09597bb1.png) +## Troubleshooting +### WTForms Error Troubleshooting -#### wtforms Form error -NOTE: If you have an error with 'wtforms' +In the event of a wtforms error, install it using pip: -type in the console -``` +```bash pip3 install WTForms==2.3.3 ``` -and press enter ### Test FTS Let's make sure your FTS server can start and run without errors. From 702db353da15dcd34a26109ee38d59db6ba87460 Mon Sep 17 00:00:00 2001 From: Az Builds Date: Thu, 2 Nov 2023 20:29:22 -0400 Subject: [PATCH 2/7] Updated linux install docs moved each distro to collapsing boxes RHEL install now working --- docs/docs/Installation/Linux/1_Install.md | 256 +++++++++++++++------- 1 file changed, 177 insertions(+), 79 deletions(-) diff --git a/docs/docs/Installation/Linux/1_Install.md b/docs/docs/Installation/Linux/1_Install.md index 21c667269..4a53228a1 100644 --- a/docs/docs/Installation/Linux/1_Install.md +++ b/docs/docs/Installation/Linux/1_Install.md @@ -21,22 +21,29 @@ Centos/RHEL/Fedora installation instructions are provided on a best-effort volun --- ## 1. Update OS Packages -**Ubuntu** +Update OS Packages before proceeding with the installation + +
+**Ubuntu** ```bash sudo apt update && sudo apt upgrade ``` +
-**RHEL** +
+**RHEL** ```bash sudo dnf update ``` +
--- ## 2. Pre-requisite Software -**Ubuntu** +
+**Ubuntu** Install packages from the distro repo @@ -44,8 +51,10 @@ Install packages from the distro repo sudo apt update && sudo apt install python3 && sudo apt install python3-pip sudo apt install python3-dev python3-setuptools build-essential python3-gevent python3-lxml libcairo2-dev ``` +
-**RHEL** +
+**RHEL** Install distro repo packages @@ -60,29 +69,31 @@ Create and activate a virtualenv for the next steps virtualenv venv source venv/bin/activate ``` +
--- ## 3. Install Python Libraries -**Ubuntu** +
+**Ubuntu** ```bash sudo pip3 install wheel pycairo ``` Note, use of pip with sudo is not recommended and you will be warned about this! +
-**RHEL** +
+**RHEL** ```bash pip install wheel pycairo ``` - - -![image](https://user-images.githubusercontent.com/60719165/142766382-8a6e5d05-a198-488d-86f2-67cd49cc1ca6.png) +
--- ## 4. Remove Old Installation @@ -92,23 +103,29 @@ pip install wheel pycairo - An upgrade fails - A previous installation was not completed -**Ubuntu** +
+**Ubuntu** ```bash sudo pip3 uninstall FreeTAKServer sudo pip3 uninstall FreeTAKServer-UI ``` +
-**RHEL** +
+**RHEL** ```bash +deactivate +rm -rf venv/ pip uninstall FreeTAKServer FreeTAKServer-UI ``` +
Delete the database and log folders ```bash -sudo rm /root/FTSDataBase.db +sudo rm /opt/FTSDataBase.db sudo rm -r /usr/local/lib//-packages/FreeTAKServer ``` @@ -116,22 +133,29 @@ sudo rm -r /usr/local/lib//-packages/FreeTAKS ## 5. Install FreeTAKServer Install the FreeTAKServer and the associated Web UI -**Ubuntu** +
+**Ubuntu** ```bash sudo python3 -m pip install FreeTAKServer[ui] ``` +
-**RHEL** +
+**RHEL** ```bash pip install FreeTAKServer[ui] ``` +
+ The FreeTAKServer can be installed without the UI, however this makes the -server much more difficult to use and is probably not what you want. This can be done using the `FreeTAKServer` pip package. +server much more difficult to use and is probably not what you want. This can be done using the `FreeTAKServer` pip package only. -### Advanced Installations: Install a specific version +### Advanced Installations: +
+**Install a specific version** To install a special version of a FreeTAKServer pip package by appending `==version-number` to the installation command. ```bash @@ -147,46 +171,61 @@ python3 -m pip install FreeTAKServer[ui]==0.2.0.13 Old installations can be installed in the same way, if desired. This will download and install version 0.2.0.13 of FreeTAKServer. If no version number is specified, then the latest normal release will be installed. +
--- ## 6. Check Installation -The pip utility allows the user to check the installation status of a package. +The pip utility allows the user to check the installation and dependency status of a package. -**Ubuntu/RHEL** ```bash pip check FreeTakServer ``` -![image](https://user-images.githubusercontent.com/60719165/142766403-b877a43b-ec9d-48ce-a13c-b216ddcfa295.png) + +You should see `No broken requirements found.` displayed, in which case you can +proceed. Otherwise there was an issue with the pip installation and you should +investigate the pip-generated installation logs for more information. --- ## 7. Configure and Run FreeTAKServer -this works only for 1.9 or better, for see here for [manual configuration](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/Installation/PyPi/Linux/ManualConfiguration.md) -Start the FreeTAKServer -**Ubuntu** +FTS versions older than 1.9 are not configured this way. For versions <1.9 you +will need to locate older versions of this document in the repo history. + +### Start the FreeTAKServer + +
+**Ubuntu** ```bash sudo python3 -m FreeTAKServer.controllers.services.FTS ``` +
-**RHEL** +
+**RHEL** ```bash python -m FreeTAKServer.controllers.services.FTS ``` +
+ +> :memo: **Note:** Warnings about `failed to register component` are OK. +Your system will run fine with these warnings. Starting with FTS 2.0 some future +functionality is declared but not fully implemented. On the first run, a configuration wizard will help set up the config file. -![image](https://user-images.githubusercontent.com/60719165/142766476-f1b5bbb9-aba5-4e05-9b53-a15c075d7e96.png) +> :memo: **Note:** If the wizard does not appear, see [troubleshooting](https://freetakteam.github.io/FreeTAKServer-User-Docs/Installation/Troubleshooting/troubleshooting/). -**If the wizard does not show up, see [troubleshooting](https://freetakteam.github.io/FreeTAKServer-User-Docs/Installation/Troubleshooting/troubleshooting/).** +### Using the Wizard The default configuration option is presented in [brackets]. -If the default is acceptable you can simply press enter to use the default. +If the default is acceptable you can simply press enter without entering any text +to automatically use the default. -An example is provided, your exact configuration will differ. +An example is provided below, your exact configuration will differ. ```css would you like to use a yaml config file, @@ -200,43 +239,62 @@ enter the preferred log file path [/opt/fts/Logs]: ``` -**The IP in this configuration wizard is the FTS_MAIN_IP. -This must be your EXTERNAL IP.** - -MySQL usage is beyond the scope of this guide. +> :memo: **Note:** The IP in this configuration wizard is the FTS_MAIN_IP. +This must be your EXTERNAL IP. -The database and log filepath can be anywhere that the host user can access. +MySQL usage is beyond the scope of this guide, if you wish to use MySQL, it is +assumed you know how to configure database servers already. Some additional +information for MySQL installations is available in the +[FTS-UI configuration section](### MySQL Configuration). -The main path should be the directory where pip installed FreeTAKServer. This can be found under your python packages directory. In virtualenv installations, it is inside the virtualenv directory. +The database and log filepaths can be anywhere that the server's host user can +access. +The main path should be the directory where pip installed FreeTAKServer. +This can be found under your python packages directory. In virtualenv installations, +it is inside the virtualenv directory. -The wizard creates the YAML configuration file is created under the location you selected (default is /opt/FTSConfig.yaml). +The wizard creates the YAML configuration file under the location you selected, +the default location is /opt/FTSConfig.yaml FreeTAKServer will then proceed start all the services. -![image](https://user-images.githubusercontent.com/60719165/142766645-210f09c3-88f5-435a-8a0d-d27bc3d4f1c3.png) --- -## 7. FTSConfig.yaml Additional Configuration +## 7. FTS Configuration +### Manual FTSConfig.yaml -![image](https://user-images.githubusercontent.com/60719165/142766660-daac490a-3c0c-4089-b3b8-40c5e520c1ff.png) +> :warning: **Warning:** Before modifying the YAML file, FreeTAKServer +**must be stopped!** -Before modifying the YAML file FreeTAKServer **must be stopped**. +Use the keyboard chord `CTRL + C` twice in the console running FTS to stop +FreeTAKServer. -Use the keyboard chord CTRL + C twice in the console will stop FreeTAKServer. +A separate guide is maintained for [manual configuration](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/Installation/PyPi/Linux/ManualConfiguration.md) of your FTS install. -## 8. Additional FTS configuration +### MainConfig.py FTS sends a welcome message on client connection which is configurable. See the `FreeTAKServer/core/configuration/MainConfig.py` file to change it. ``` - ConnectionMessage = f'Welcome to FreeTAKServer {version}. The Parrot is not dead. It’s just resting' +ConnectionMessage = f'Welcome to FreeTAKServer {version}. The Parrot is not dead. It’s just resting' ``` --- -## 9. Configure Web UI +## 9. FTS-UI Configuration + +Edit the `config.py` file in the `FreeTAKServer-UI` directory where it was installed by pip + +
+Where is that? +> The FreeTAKServer-UI directory lives at the same level as the FreeTAKServer +directory that was set in the initial configuration of FTS. -Edit the `config.py` file in the `FreeTAKServer-UI` directory where it was installed by pip. +>Usually that means it's inside your python packages directory. +In virtualenv installations, it is inside the python installation in side the +virtualenv directory. +
+### Standard UI Config Edit the IP value to your external IP, for example: @@ -247,7 +305,6 @@ IP = '192.168.1.100' Set the web map IP address, for example: -:warning: **Warning: Original intent is unknown, this configuration is a best-guess.** ```python # the public IP your server is exposing @@ -265,19 +322,23 @@ Advanced users may wish to use a different port. # Port the UI uses to communicate with the API PORT = '19023' ``` + +### Custom Secrets Configuration -The following can be updated to use your own secrets, however the values must be -updated in both the `FreeTAKServer-UI/config.py` and the `FreeTAKServer/core/configuration/MainConfig.py` files. +The following items can be updated to use your own secrets, however the values +must be updated in both the `FreeTAKServer-UI/config.py` and the +`FreeTAKServer/core/configuration/MainConfig.py` files. - If you change those values in the UI you must change also the YAML file configurtation -the API key used by the UI to comunicate with FTS. generate a new system user and then set it +The API key used by the UI to comunicate with FTS. +Generate a new system user and then set it. +~~What does this mean? Where is a user generated? What is a system user?~~ ```python app.config['APIKEY'] = 'Bearer [API_TOKEN]' app.config['WEBSOCKETKEY'] = '[Your_Web_socket_Key]' ``` -### 9.1 MySQL Configuration +### MySQL Configuration To use a MySQL database, update the URI to point to your database. @@ -287,14 +348,14 @@ Database setup is beyond the scope of this document. SQLALCHEMY_DATABASE_URI = 'mysql://' + 'user:pass@localhost/dbname' ``` -### 9.2 Miscellaneous Parameters -Additional parameters can be found in the `__init__.py` file. +### Miscellaneous Parameters -``` -FreeTAKServer-UI/app/__init__.py -``` +Some additional parameters can be found in the `__init__.py` file in the +`FreeTAKServer-UI/app/__init__.py` directory. -this include the frequence of the update for the dashboard and the file limit for data packages + +These configure dashboard update frequency, ~~health pings?~~, +~~status messages?~~, and the file size limit for data packages. ```python app.config['USERINTERVAL'] = '180000'; @@ -304,25 +365,35 @@ app.config['DATAPACKAGESIZELIMIT'] = '15360000'; ``` ### 10. Start UI -While in terminal, navigate to the `FreeTAKServer-UI` directory wherever it was + +In the terminal, navigate to the `FreeTAKServer-UI` directory wherever it was installed by the pip utility. - Run the UI using +Start the UI from the terminal using python: -**Ubuntu** +
+**Ubuntu** - ```bash - sudo python3 run.py - ``` - - **RHEL** +```bash +sudo python3 run.py +``` +
- ```bash - python run.py - ``` +
+**RHEL** - ![image](https://user-images.githubusercontent.com/60719165/142767800-e09ef09c-d6d7-4a11-bcc4-0f4a09597bb1.png) +```bash +python run.py +``` +
+You will see the UI server start up in your terminal, which should look similar +to that shown below. + +```python +(55501) wsgi starting up on http://0.0.0.0:5000 +(55501) accepted ('192.168.1.100', 49842) +``` --- ## 11. Next Steps @@ -350,18 +421,11 @@ The config file will also need to be updated. IP = [FTS external IP] APPIP = [FTS-UI internal IP] ``` - -## Troubleshooting -### WTForms Error Troubleshooting -In the event of a wtforms error, install it using pip: +## 12. Check Installation -```bash -pip3 install WTForms==2.3.3 -``` - -### Test FTS -Let's make sure your FTS server can start and run without errors. +After finishing all the steps, make sure your configuration is acceptable and +server running properly. ```bash sudo python3 -m FreeTAKServer.controllers.services.FTS @@ -372,9 +436,43 @@ If you see FTS start without error you may hit `ctrl+c` twice and move onto runn your FTS is now configured -![image](https://user-images.githubusercontent.com/60719165/142767335-c8283798-877e-4fab-b264-7c70f314b3d0.png) If you have setup the UI, from the Admin console send a message hello world to the client -![image](https://user-images.githubusercontent.com/60719165/142767408-8e754ffa-7102-42ac-8254-a5ba35ff6526.png) + +## Troubleshooting + +### Default Login +The default credentials for the UI are `admin` and `password`. + +You are encouraged to update these quickly. + + +### WTForms Error Troubleshooting + +In the event of a wtforms error, install it using pip: + +```bash +pip3 install WTForms==2.3.3 +``` + +### Failed to Register Components + +Warnings about `failed to register component` are OK. +Your system will run fine with these warnings. Starting with FTS 2.0 some future +functionality is declared but not fully implemented. +### UI Can't See Server + +Usually this happens when you are using an OS that has a strong default firewall. + +Ensure all the ports you have set in your config files are open on the firewall +for TCP traffic. + +
+**RHEL** + +```bash +firewall-cmd --add-port=19023/tcp +``` +
From fc179af72caf78fe30cf1ec38114feb74f5864d8 Mon Sep 17 00:00:00 2001 From: Az Builds Date: Thu, 2 Nov 2023 20:36:28 -0400 Subject: [PATCH 3/7] Formatting changes to match github markdown --- docs/docs/Installation/Linux/1_Install.md | 73 ++++++++++++++++------- 1 file changed, 53 insertions(+), 20 deletions(-) diff --git a/docs/docs/Installation/Linux/1_Install.md b/docs/docs/Installation/Linux/1_Install.md index 4a53228a1..ec1727e0b 100644 --- a/docs/docs/Installation/Linux/1_Install.md +++ b/docs/docs/Installation/Linux/1_Install.md @@ -7,9 +7,9 @@ This guide will walk you through installing FreeTAKServer 2.0 - Install FreeTAKServer - Configure and Run FreeTAKServer - Configure Web UI -- Install [NodeRed](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/NodeRedinstallation.md) for FreeTAKHub -- Install the [Web Map](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/WebMap/Installation.md) -- Install the [Video Service](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/Video/Installation.md) +- **TBD** ~~Install [NodeRed](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/NodeRedinstallation.md) for FreeTAKHub~~ +- **TBD** ~~Install the [Web Map](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/WebMap/Installation.md)~~ +- **TBD** ~~Install the [Video Service](https://github.com/FreeTAKTeam/FreeTAKServer-User-Docs/blob/main/docs/docs/FreeTAKHub/Video/Installation.md)~~ --- ## Note: Linux Distributions @@ -24,7 +24,9 @@ Centos/RHEL/Fedora installation instructions are provided on a best-effort volun Update OS Packages before proceeding with the installation
-**Ubuntu** + +**Ubuntu** + ```bash sudo apt update && sudo apt upgrade @@ -32,7 +34,9 @@ sudo apt update && sudo apt upgrade
-**RHEL** + +**RHEL** + ```bash sudo dnf update @@ -43,7 +47,9 @@ sudo dnf update ## 2. Pre-requisite Software
-**Ubuntu** + +**Ubuntu** + Install packages from the distro repo @@ -54,7 +60,9 @@ sudo apt install python3-dev python3-setuptools build-essential python3-gevent p
-**RHEL** + +**RHEL** + Install distro repo packages @@ -76,7 +84,9 @@ source venv/bin/activate ## 3. Install Python Libraries
-**Ubuntu** + +**Ubuntu** + ```bash sudo pip3 install wheel pycairo @@ -87,7 +97,9 @@ Note, use of pip with sudo is not recommended and you will be warned about this!
-**RHEL** + +**RHEL** + ```bash @@ -104,7 +116,9 @@ pip install wheel pycairo - A previous installation was not completed
-**Ubuntu** + +**Ubuntu** + ```bash sudo pip3 uninstall FreeTAKServer @@ -113,7 +127,9 @@ sudo pip3 uninstall FreeTAKServer-UI
-**RHEL** + +**RHEL** + ```bash deactivate @@ -134,7 +150,9 @@ sudo rm -r /usr/local/lib//-packages/FreeTAKS Install the FreeTAKServer and the associated Web UI
-**Ubuntu** + +**Ubuntu** + ```bash sudo python3 -m pip install FreeTAKServer[ui] @@ -142,7 +160,9 @@ sudo python3 -m pip install FreeTAKServer[ui]
-**RHEL** + +**RHEL** + ```bash pip install FreeTAKServer[ui] @@ -153,9 +173,12 @@ pip install FreeTAKServer[ui] The FreeTAKServer can be installed without the UI, however this makes the server much more difficult to use and is probably not what you want. This can be done using the `FreeTAKServer` pip package only. -### Advanced Installations: +### Advanced Installations: +
-**Install a specific version** + +**Install a specific version** + To install a special version of a FreeTAKServer pip package by appending `==version-number` to the installation command. ```bash @@ -196,7 +219,9 @@ will need to locate older versions of this document in the repo history. ### Start the FreeTAKServer
-**Ubuntu** + +**Ubuntu** + ```bash sudo python3 -m FreeTAKServer.controllers.services.FTS @@ -204,7 +229,9 @@ sudo python3 -m FreeTAKServer.controllers.services.FTS
-**RHEL** + +**RHEL** + ```bash python -m FreeTAKServer.controllers.services.FTS @@ -372,7 +399,9 @@ installed by the pip utility. Start the UI from the terminal using python:
-**Ubuntu** + +**Ubuntu** + ```bash sudo python3 run.py @@ -380,7 +409,9 @@ sudo python3 run.py
-**RHEL** + +**RHEL** + ```bash python run.py @@ -470,7 +501,9 @@ Ensure all the ports you have set in your config files are open on the firewall for TCP traffic.
-**RHEL** + +**RHEL** + ```bash firewall-cmd --add-port=19023/tcp From 14e25a4475231489fa73ff0d2ed734e64eedaed7 Mon Sep 17 00:00:00 2001 From: Az Builds Date: Thu, 2 Nov 2023 20:39:37 -0400 Subject: [PATCH 4/7] Additional github markdown formatting --- docs/docs/Installation/Linux/1_Install.md | 32 +++++++++++------------ 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/docs/Installation/Linux/1_Install.md b/docs/docs/Installation/Linux/1_Install.md index ec1727e0b..6315926b6 100644 --- a/docs/docs/Installation/Linux/1_Install.md +++ b/docs/docs/Installation/Linux/1_Install.md @@ -25,7 +25,7 @@ Update OS Packages before proceeding with the installation
-**Ubuntu** +Ubuntu ```bash @@ -35,7 +35,7 @@ sudo apt update && sudo apt upgrade
-**RHEL** +RHEL ```bash @@ -48,7 +48,7 @@ sudo dnf update
-**Ubuntu** +Ubuntu Install packages from the distro repo @@ -61,7 +61,7 @@ sudo apt install python3-dev python3-setuptools build-essential python3-gevent p
-**RHEL** +RHEL Install distro repo packages @@ -85,7 +85,7 @@ source venv/bin/activate
-**Ubuntu** +Ubuntu ```bash @@ -98,7 +98,7 @@ Note, use of pip with sudo is not recommended and you will be warned about this!
-**RHEL** +RHEL @@ -117,7 +117,7 @@ pip install wheel pycairo
-**Ubuntu** +Ubuntu ```bash @@ -128,7 +128,7 @@ sudo pip3 uninstall FreeTAKServer-UI
-**RHEL** +RHEL ```bash @@ -151,7 +151,7 @@ Install the FreeTAKServer and the associated Web UI
-**Ubuntu** +Ubuntu ```bash @@ -161,7 +161,7 @@ sudo python3 -m pip install FreeTAKServer[ui]
-**RHEL** +RHEL ```bash @@ -177,7 +177,7 @@ server much more difficult to use and is probably not what you want. This can be
-**Install a specific version** +Install a specific version To install a special version of a FreeTAKServer pip package by appending `==version-number` to the installation command. @@ -220,7 +220,7 @@ will need to locate older versions of this document in the repo history.
-**Ubuntu** +Ubuntu ```bash @@ -230,7 +230,7 @@ sudo python3 -m FreeTAKServer.controllers.services.FTS
-**RHEL** +RHEL ```bash @@ -400,7 +400,7 @@ Start the UI from the terminal using python:
-**Ubuntu** +Ubuntu ```bash @@ -410,7 +410,7 @@ sudo python3 run.py
-**RHEL** +RHEL ```bash @@ -502,7 +502,7 @@ for TCP traffic.
-**RHEL** +RHEL ```bash From d7548313d265e5b79d3ee9d3a0a07d4334ec2235 Mon Sep 17 00:00:00 2001 From: Az Builds Date: Sat, 4 Nov 2023 13:19:21 -0400 Subject: [PATCH 5/7] Updated documentation with centos/fedora differences --- docs/docs/Installation/Linux/1_Install.md | 53 ++++++++++++++++------- 1 file changed, 38 insertions(+), 15 deletions(-) diff --git a/docs/docs/Installation/Linux/1_Install.md b/docs/docs/Installation/Linux/1_Install.md index 6315926b6..cb434087a 100644 --- a/docs/docs/Installation/Linux/1_Install.md +++ b/docs/docs/Installation/Linux/1_Install.md @@ -35,7 +35,7 @@ sudo apt update && sudo apt upgrade
-RHEL +Centos/RHEL/Fedora ```bash @@ -46,12 +46,14 @@ sudo dnf update --- ## 2. Pre-requisite Software + +Install packages from the distro repo
Ubuntu -Install packages from the distro repo + ```bash sudo apt update && sudo apt install python3 && sudo apt install python3-pip @@ -61,13 +63,29 @@ sudo apt install python3-dev python3-setuptools build-essential python3-gevent p
-RHEL +RHEL/Centos -Install distro repo packages +```bash +sudo dnf group install "Development Tools" +sudo dnf install python3 pip virtualenv virtualenvwrapper cairo cairo-devel python3-gevent python3-lxml bzip2-devel libffi-devel +``` + +Create and activate a virtualenv for the next steps + +```bash +virtualenv venv +source venv/bin/activate +``` +
+ +
+ +Fedora + ```bash -sudo dnf group install "C Development Tools and Libraries" "Development Tools" +sudo dnf group install "Development Tools" "C Development Tools and Libraries" sudo dnf install python3 python3-pip cairo cairo-devel python3-cairo python3-cairo-devel python3-gevent python3-lxml python3-virtualenv ``` @@ -79,7 +97,6 @@ source venv/bin/activate ```
- --- ## 3. Install Python Libraries @@ -98,7 +115,7 @@ Note, use of pip with sudo is not recommended and you will be warned about this!
-RHEL +Centos/RHEL/Fedora @@ -124,11 +141,18 @@ Ubuntu sudo pip3 uninstall FreeTAKServer sudo pip3 uninstall FreeTAKServer-UI ``` + +Delete the database and log folders + +```bash +sudo rm /opt/FTSDataBase.db +sudo rm -r /usr/local/lib//-packages/FreeTAKServer +```
-RHEL +Centos/RHEL/Fedora ```bash @@ -136,14 +160,13 @@ deactivate rm -rf venv/ pip uninstall FreeTAKServer FreeTAKServer-UI ``` -
Delete the database and log folders ```bash -sudo rm /opt/FTSDataBase.db -sudo rm -r /usr/local/lib//-packages/FreeTAKServer +sudo rm /opt/FTS/FTSDataBase.db ``` +
--- ## 5. Install FreeTAKServer @@ -161,7 +184,7 @@ sudo python3 -m pip install FreeTAKServer[ui]
-RHEL +Centos/RHEL/Fedora ```bash @@ -230,7 +253,7 @@ sudo python3 -m FreeTAKServer.controllers.services.FTS
-RHEL +Centos/RHEL/Fedora ```bash @@ -410,7 +433,7 @@ sudo python3 run.py
-RHEL +Centos/RHEL/Fedora ```bash @@ -502,7 +525,7 @@ for TCP traffic.
-RHEL +Centos/RHEL/Fedora ```bash From fa73cc5749543b2ccc5dd890b5b5eea959614ec6 Mon Sep 17 00:00:00 2001 From: Az Builds Date: Wed, 13 Dec 2023 19:53:11 -0500 Subject: [PATCH 6/7] renaming to match current main --- docs/docs/Installation/Linux/{1_Install.md => 1_Installation.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/docs/Installation/Linux/{1_Install.md => 1_Installation.md} (100%) diff --git a/docs/docs/Installation/Linux/1_Install.md b/docs/docs/Installation/Linux/1_Installation.md similarity index 100% rename from docs/docs/Installation/Linux/1_Install.md rename to docs/docs/Installation/Linux/1_Installation.md From 509d96276ecbd501e59449aad6e8348f9aa9d5e1 Mon Sep 17 00:00:00 2001 From: Az Builds Date: Wed, 13 Dec 2023 20:00:32 -0500 Subject: [PATCH 7/7] Renaming again to match current main --- .../Installation/Linux/{1_Installation.md => 1.Installation.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/docs/Installation/Linux/{1_Installation.md => 1.Installation.md} (100%) diff --git a/docs/docs/Installation/Linux/1_Installation.md b/docs/docs/Installation/Linux/1.Installation.md similarity index 100% rename from docs/docs/Installation/Linux/1_Installation.md rename to docs/docs/Installation/Linux/1.Installation.md