2.3 System Deployment Guide

This document provides comprehensive deployment instructions for the system components. The platform consists of multiple interconnected services that work together to provide vulnerability scanning and project management capabilities.

2.3.1 System Overview

The ASTRI deployment consists of the following services:

Service	Port	Description	Detailed Deployment Guide
Documentation	3001	Docusaurus-based documentation site	N/A
Frontend	3000	React-based user interface	Frontend Deployment Guide
Workflow Server	3008	Core workflow management engine	Workflow Server Deployment Guide
API Documentation	8080	Swagger API documentation	N/A
Vulnerability Repository	8088	Vulnerability data management	N/A

Component Library

For frontend development, the system uses a shared component library:

• SourceGuard Frontend Components: Reusable React components for security applications
  • Component Library Deployment Guide

2.3.2 Prerequisites

Ensure the following components are installed and configured on the target server:

2.3.2.1 System Requirements

• Operating System: Ubuntu 24+ (LTS recommended)
• Node.js: Version 22+ (LTS)
• Bun: Latest stable version
• Process Manager: pm2 with startup configuration
• Container Runtime: Docker 27+
• Programming Language: Go 1.24.1+

2.3.2.2 Initial Server Setup

1. Connect to the deployment server:

   ssh 192.168.3.60

2. Create the deployment directory structure:

   mkdir -p repo
   cd repo

3. Configure pm2 for automatic startup (if not already configured):

   pm2 startup
   # Follow the displayed instructions to complete setup

2.4 Service Deployment

2.4.1 Documentation Service (Docusaurus)

Purpose: Hosts the project documentation and technical guides.

Deployment Steps:

cd ~/repo

# Clone the repository (skip if already present)
git clone https://gitlab.astricsa.cf/PRP069-24CI/docs.git

cd docs

# Start the documentation service
pm2 start "bun run ci" --name docs:3001

# Persist the PM2 configuration
pm2 save

2.4.2 Frontend Application

Purpose: Provides the main user interface for the system.

📖 For complete deployment instructions, environment configuration, Docker setup, and troubleshooting, see the Frontend Deployment Guide

2.4.3 Workflow Management Server

Purpose: Handles core workflow processing and task management.

📖 For comprehensive deployment options, environment configuration, Docker setup, and production deployment, see the Workflow Server Deployment Guide

2.4.4 API Documentation Service

Purpose: Provides interactive API documentation using Swagger UI.

Deployment Steps:

cd ~/repo

# Clone the repository (skip if already present)
git clone https://gitlab.astricsa.cf/PRP069-24CI/swagger-api-docs.git
# Enter credentials when prompted

cd swagger-api-docs

# Remove any existing container instance
docker rm -f swagger-ui

# Deploy the Swagger UI container via PM2
pm2 start "docker run -p 8080:8080 --name swagger-ui \
      -v $(pwd):/usr/share/nginx/html/swagger \
      -e URLS=\"$(jq -r -c . urls.json)\" \
      docker.swagger.io/swaggerapi/swagger-ui" --name swagger-ui:8080

# Persist the PM2 configuration
pm2 save

2.4.5 Vulnerability Repository Service

Purpose: Manages vulnerability data storage and retrieval.

Deployment Steps:

cd ~/repo

# Clone the repository (skip if already present)
git clone https://gitlab.astricsa.cf/PRP069-24CI/vulnerability_repo.git
# Enter credentials when prompted

cd vulnerability_repo/stack

# Configure the service port
export PORT=8088

# Deploy using Docker Compose via PM2
pm2 start "docker compose -f docker-compose-dev.yml up -d" --name vul-repo:8088

# Persist the PM2 configuration
pm2 save

2.5 Operational Management

2.5.1 Service Status Verification

To verify all services are running correctly:

pm2 status

2.5.2 Service Monitoring

Monitor real-time logs for all services:

pm2 logs

Monitor logs for a specific service:

pm2 logs <service-name>

2.6 Troubleshooting

2.6.1 PM2 Service Recovery After System Reboot

If PM2 services fail to automatically restart after a system reboot, manually restore them using:

pm2 resurrect

2.6.2 Common Issues and Solutions

1. Port conflicts: Ensure no other services are using the specified ports (3000, 3001, 3008, 8080, 8088).

2. Permission issues: Verify the deployment user has appropriate permissions for the repository directory and Docker daemon.

3. Memory issues: Monitor system resources with pm2 monit to ensure adequate memory allocation.

4. Network connectivity: Ensure GitLab repository access and Docker registry connectivity.

For additional support, consult the system logs and PM2 monitoring tools to diagnose specific service issues.