Percepio Detect Server
----------------------
Release 2025.2, Aug 28, 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.bat 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.bat start

    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: percepio-server.bat stop

- To see logs from the server:
    On Linux: ./percepio-server.sh logs
    On Windows: percepio-server.bat logs
	
	In case of issues, please include these logs in your support request.
	To dump logs to a file, run "docker logs container > file.txt" 	
	where container is one of:
	  - detect-database
	  - detect-alert-sender
	  - detect-frontend
	  - detect-backend
	  
	The detect-backend log is usually the most valuable one.
 
- Clearing the server database:
  This will delete the docker containers and the Detect database.  
  	
  1. Stop the server, as explained above.
    
  2. Run the "cleanup" command.
       On Linux: ./percepio-server.sh cleanup
       On Windows: percepio-server.bat cleanup
		
  3. Note that any alert files in ALERTS_DIR will be ingested again when starting the server. 
     If not desired, remove any undesired alert files.
  
  4. Finally, start the server again.
  

Troubleshooting:
  
  - Check the Server logs for errors, as described above.
	
  - 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. This usually happens if the backend is not responding
	and such errors are normal when starting up the Detect server.
	   
  - 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
  
  
