Skip to Content
PacketScope 1.1 is released 🎉
DocsGetting Started

Getting Started

Installation Video

Prerequisites

Before getting started, ensure Docker is installed and running on your system:

  • Docker: Version 20.10 or higher
  • Docker Compose: Version 2.0 or higher

Verify Docker installation:

docker --version
docker compose version

If Docker is not installed, visit the Docker Official Website  for installation instructions.

PacketScope provides a convenient deployment script that automatically builds and starts all services using Docker Compose.

Clone the Repository

git clone https://github.com/Internet-Architecture-and-Security/PacketScope.git
cd PacketScope

Run the Deployment Script

Execute the startup script with root privileges:

sudo bash starter.sh

The script will automatically complete the following operations:

  • âś“ Check Docker environment
  • âś“ Stop existing services
  • âś“ Build all service containers in the correct order
  • âś“ Start all services
  • âś“ Display service status and access information

Access the Application

After deployment is complete, open your browser and visit:

http://localhost:4173/

Service Endpoints

After successful deployment, the following services will be available:

ServicePortAccess URL
Web UI4173http://localhost:4173 
Guarder API8080http://localhost:8080 
Tracer API8000http://localhost:8000 
Analyzer-Monitor API5000http://localhost:5000 
Analyzer-ProtocolStack API19999http://localhost:19999 

Service Management

View Service Status

sudo docker compose ps

View Service Logs

View logs for all services:

sudo docker compose logs -f

View logs for a specific service:

sudo docker compose logs -f <service-name>

Available service names:

  • web-ui - Frontend interface
  • guarder - Security protection module
  • tracer - Network tracing module
  • analyzer-monitor - Traffic monitoring module
  • analyzer-protocolstack - Protocol stack analysis module

Stop All Services

sudo docker compose down

Restart Services

Restart all services:

sudo docker compose restart

Restart a specific service:

sudo docker compose restart <service-name>

Update Services

If there are code updates, you need to rebuild and redeploy:

# Stop and remove existing containers
sudo docker compose down
 
# Rebuild and start
sudo bash starter.sh

Or rebuild only a specific service:

sudo docker compose up -d --build <service-name>

Manual Deployment (Optional)

If you need manual deployment or advanced configuration, you can refer to the following steps.

Starting Server Modules

This project contains multiple server-side modules implemented in different languages. Please refer to the README.md file in each module to install dependencies and start services.

modules
├── Analyzer  # Python-based protocol stack analysis module
│   ├── Monitor/           # Traffic monitoring submodule
│   └── ProtocolStack/     # Protocol analysis submodule
├── Guarder   # Go-based security policy module
└── Tracer    # Python-based network path mapping module

Analyzer Module

The Analyzer module contains two submodules: Monitor and ProtocolStack.

Enter the Monitor directory:

cd modules/Analyzer/Monitor

Install dependencies and start:

pip install -r requirements.txt
python app.py

Enter the ProtocolStack directory:

cd modules/Analyzer/ProtocolStack

Install dependencies and start:

pip install -r requirements.txt
python app.py

Guarder Module

Enter the Guarder directory:

cd modules/Guarder

Install dependencies and start:

go mod download
go run main.go

Tracer Module

Enter the Tracer directory:

cd modules/Tracer

Install dependencies and start:

pip install -r requirements.txt
python app.py

Starting the Frontend Service

The frontend is built with Node.js . Ensure Node.js (version ≥ 16) is installed.

Install Dependencies

Run the following command in the project root directory:

npm install
Note

Users in mainland China can set up an npm mirror to speed up installation:

npm config set registry http://registry.npmmirror.com

Start the Preview Server

npm run preview

The application runs on local port 4173 by default.

Access the Application

Open your browser and visit:

http://127.0.0.1:4173/
Tip

To run in development mode with hot reload enabled, use the following command:

npm run dev
Tip

To build for production, use the following command:

npm run build

Common Issues

Docker Permission Issues

If you encounter Docker permission errors, ensure your user is in the docker group:

sudo usermod -aG docker $USER

Then log out and log back in, or run:

newgrp docker

Port Conflicts

If default ports are occupied, you can:

  1. Check which process is using the port:
sudo lsof -i :4173
  1. Stop the process using the port, or modify the port mapping in docker-compose.yml

Service Fails to Start

  1. Check Docker logs to diagnose the issue:
sudo docker compose logs <service-name>

  1. Ensure all required ports are not occupied

  2. Verify that Docker and Docker Compose versions meet the requirements

Build Failures

If errors occur during the build process:

  1. Clean Docker cache:
sudo docker system prune -a
  1. Rebuild:
sudo bash starter.sh

Network Connection Issues

If the frontend cannot connect to backend services:

  1. Check if all services are running properly:
sudo docker compose ps

  1. Verify that service ports are correctly mapped

  2. Check if firewall settings are blocking port access

Performance Issues

If services are running slowly:

  1. Check system resource usage:
sudo docker stats

  1. Increase available Docker resources (memory, CPU)

  2. Check logs for errors or warning messages

Troubleshooting

Complete Reset

If you encounter unresolvable issues, you can completely reset the environment:

# Stop and delete all containers
sudo docker compose down -v
 
# Delete all related images
sudo docker images | grep packetscope | awk '{print $3}' | xargs sudo docker rmi -f
 
# Redeploy
sudo bash starter.sh

Get Help

For additional help, please:

  1. Check GitHub Issues 
  2. Review detailed documentation for each module
  3. Submit a new Issue with detailed error logs

Next Steps

After successfully deploying PacketScope, you can:

Enjoy using PacketScope!

Last updated on
IntroductionServer Modules