Percepio Detect Server
----------------------
Release 2025.1, April 15, 2025.


The Percepio Detect Server (or "Server" for short) is the core of Percepio Detect.

The Server provides the Dashboard in the web browser and manages the database.

The Server also monitors the alert directory for new alert files (from Percepio Receiver)
and processes new alert files, making them appear in the dashboard within a few seconds.


1. Server Installation - For Demo and other Single-user Setups
--------------------------------------------------------------

1.1 Make sure that Docker is installed.
   
    On Linux, Docker Engine is sufficient.
    - See https://docs.docker.com/engine/install/ for installation instructions.
    - If you get a ”permission denied” error, you might need to add the ”docker” group to your user and reboot your computer. 
    - You may also need to start the Docker service. See https://docs.docker.com/engine/daemon/start/.

    On Windows
    - Install Docker Desktop from https://www.docker.com/.
    - Start Docker Desktop and make sure it states "Engine Running" in the bottom left corner. 
   
    In a terminal, run "docker run hello-world" to see that Docker works as expected.
   
1.2 Specify your Detect license key in the server start script, i.e., percepio-server.sh
    for Linux or percepio-server.ps1 for Windows. Open the start script in a text editor
    and update the LICENSE variable with your license key. Leave the other variables
    unchanged. Note that Tracealyzer and Detect Server have separate license keys.  

1.3 Start the server by running the start script:
   
     On Linux, run "./percepio-server.sh start".

     On Windows, run ".\percepio-server.ps1 start" in a PowerShell window,
     alternatively run "percepio-server.bat start" at the command prompt.

    (Note: To run unsigned powershell scripts, you may need to change the execution policy
    using "Set-ExecutionPolicy Unrestricted". Changing this setting requires running
    PowerShell as Administrator. This is not needed if using the .bat file.)
	
    Note: If using Linux and ./percepio-server.sh doesn't start, the file is probably
    missing execution permissions. Correct this using e.g. "sudo chmod +x percepio-server.sh".
   
Docker now downloads the Detect Server images from Docker Hub and starts the server. 
The server should be accessible http://127.0.0.1:8080 in your web browser.

To run the demo, see the Percepio Detect Demo Guide (pdf).


Server Installation - Multi-user setup
--------------------------------------

2.1 Make sure that Docker is installed (see 1.1).
      	  
2.2 Create a directory for the alert data files. This will be the main storage
    for your Percepio Detect installation. This is where the Percepio Receiver
    should store the alert files, and where the server should look for input.
    This is typically a shared folder in your local network, e.g. on a file server. 
   
2.3 Make sure the alert directory is readable and writable also by a different user.
    For example, by running "sudo chmod -R o+rw /path/to/alert-directory". 

2.4 Open the start script in a text editor, percepio-server.sh for Linux or percepio-server.ps1
    for Windows, and update the following to match your setup:
       
	- ALERTS_DIR: The alert data directory, created in step 2.2.	              
	  
	- BACKEND_IP: The local IP address of the server, as seen by the users. 
	              For example BACKEND_IP="192.168.100.42".
				  
	- LICENSE: Your Percepio Detect Server license key, for example LICENSE="ABCD-ABCD-ABCD-ABCD"
                   Note that Tracealyzer and the Detect Server have separate license keys, so
                   make sure to use the right key.

2.5 Start the server (see 1.3). The server should now be accessible at http://<BACKEND_IP>:8080 in your web browser.

2.6 Accessing Perceio Detect over HTTPS
    You may also access the Percepio Detect server over HTTPS on port 8081, i.e. using an encrypted connection to the Server.
    Self-signed certificates are included as example and located in the percepio-server/cert folder (detect.crt and detect.key).
    Note that the example certificate will trigger security warnings in your web browser since not issued by a trusted Certificate Authority (CA).
    To use HTTPS, please replace your certificate files with a proper certificate issued by a trusted Certificate Authority (CA).
    
2.7 Updating the SSL Certificates
    If you prefer to use your own SSL certificate for HTTPS access, replace the default self-signed certificates with your own certificate.
    Here is how:
    - Obtain Your Certificates: Acquire an SSL certificate (your_certificate.crt) and a private key (your_private.key) from a trusted Certificate Authority.
    - Rename Your Files: Rename your certificate and key files to match the expected filenames (detect.crt, detect.key).
    - Replace the Default Certificates: Copy your renamed files into the cert folder from percepio-server folder.
    - Restart the Docker Container: For the changes to take effect, restart your Docker container.

Server Management:

- To stop the server:
    On Linux: ./percepio-server.sh stop
    On Windows: run ".\percepio-server.ps1 stop" in a PowerShell window,
    alternatively run "percepio-server.bat stop" at the command prompt.

- To see logs from the server:
    On Linux: ./percepio-server.sh logs
    On Windows: run ".\percepio-server.ps1 logs" in a PowerShell window,
    alternatively run "percepio-server.bat logs" at the command prompt.
 
- Clearing the server database:
  This will delete the docker containers and the docker volume storing the Detect database.
  This can useful for cleaning up the dashboard and reclaiming some storage space, although
  the alert files are typically small.
	
  1. Stop the server, as explained above.
    
  2. Run the "cleanup" command.
       On Linux, run: ./percepio-server.sh cleanup
       On Windows, run: ".\percepio-server.ps1 cleanup" in a PowerShell window, or "percepio-server.bat cleanup".
		
  3. You may also choose to remove the old alert files in ALERTS_DIR, if so desired.
     If you want to keep some of them, make sure to delete "lasttrace.txt".
	 All files in ALERTS_DIR will then be ingested after starting the server again.
  
  4. Finally, start the server again.
  

Troubleshooting:
  
  - Check the Server logs for errors, as described above.
	
  - Check that the ports specified in the percepio-server script are not
    already in use. For example "MYSQL_PORT=3306".
  
  - Check if the file "failure.txt" has been created in the ALERTS_DIR.
    This contains information about alert data files where the processing
	failed for some reason.
	   
  - Make sure the computer and user running Receiver is allowed to write
    to the ALERTS_DIR directory.

  - Make sure the computer and user running Client is allowed to read
    from the ALERTS_DIR directory.

  - Note that a single alert may produce multiple alert files, so it is normal
    to have more alert files than the number of generated alerts.
	
For questions and assistance, please contact Percepio at 
 
     https://percepio.com/contact-us/

Copyright (c), Percepio AB, 2025
https://percepio.com
  
  
