Installation - capstone-hermes/hermes-fullstack GitHub Wiki

Installation

Overview

This guide provides comprehensive installation instructions for the Weak Website application across different environments and operating systems. The application supports Docker-based deployment (recommended) and local development setup.

🚨 Security Warning

This application contains intentional security vulnerabilities for educational purposes:

  • Only install in isolated, controlled environments
  • Never deploy on public-facing systems or production networks
  • Use only for authorized security testing and education

Prerequisites

System Requirements

Minimum Requirements

  • CPU: 2 cores, 2.4 GHz
  • RAM: 4 GB available memory
  • Storage: 10 GB free disk space
  • Network: Internet connection for initial setup

Recommended Requirements

  • CPU: 4 cores, 3.0 GHz
  • RAM: 8 GB available memory
  • Storage: 20 GB free disk space (for logs and testing data)
  • Network: Isolated network or VLAN for security testing

Software Dependencies

Required Software

  • Docker: 20.10+ and Docker Compose 2.0+
  • Git: 2.30+ for repository management
  • Node.js: 18+ (for local development)
  • curl: For API testing (usually pre-installed)

Optional Software

  • Postman: API testing and exploration
  • Burp Suite: Web application security testing
  • OWASP ZAP: Automated vulnerability scanning
  • MySQL Client: Direct database access

Installation Methods

Method 1: Docker Compose (Recommended)

This is the easiest and most reliable installation method.

Step 1: Clone Repository

# Clone the repository
git clone <repository-url>
cd hermes-fullstack/weak-website

# Verify repository structure
ls -la
# Expected: client/, server/, docker-compose.yml, docker-compose.dev.yml, README.md

Step 2: Environment Setup

# Create environment file from template
cp .env.example .env

# Edit environment variables (optional - defaults work for basic setup)
nano .env

Step 3: Build and Start Services

# Start all services (development mode with hot reload)
docker-compose -f docker-compose.dev.yml up --build -d

# Or start in production mode
docker-compose up --build -d

# Verify all containers are running
docker-compose ps

Step 4: Verify Installation

# Check application accessibility
curl http://localhost:8081  # Client application
curl http://localhost:8080  # Server API
curl http://localhost:8080/api  # API documentation

# Check container logs
docker-compose logs -f

Method 2: Local Development Setup

For developers who want to run services locally without Docker.

Step 1: Database Setup

# Install and start MySQL (Ubuntu/Debian)
sudo apt update
sudo apt install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql

# Install and start MySQL (macOS with Homebrew)
brew install mysql
brew services start mysql

# Install and start MySQL (Windows)
# Download MySQL installer from https://dev.mysql.com/downloads/installer/
# Follow installer instructions

Step 2: Database Configuration

# Connect to MySQL as root
mysql -u root -p

# Create database and user
CREATE DATABASE `hermes-weak-website-db`;
CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON `hermes-weak-website-db`.* TO 'user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

# Verify database connection
mysql -u user -p hermes-weak-website-db

Step 3: Server Setup

# Navigate to server directory
cd server

# Install dependencies
npm install

# Create environment file
cat > .env << EOF
DB_HOST=localhost
DB_PORT=3306
DB_USER=user
DB_PASSWORD=password
DB_DATABASE=hermes-weak-website-db
SERVER_PORT=8080
JWT_SECRET=hardcoded-secret
CLIENT_URL=http://localhost:8081
EOF

# Start development server
npm run start:dev

# Verify server is running
curl http://localhost:8080/api

Step 4: Client Setup

# Open new terminal and navigate to client directory
cd client

# Install dependencies
npm install

# Create environment file
cat > .env << EOF
VITE_SERVER_URL=http://localhost:8080
VITE_CLIENT_PORT=8081
EOF

# Start development server
npm run dev

# Verify client is running
curl http://localhost:8081

Method 3: Docker Individual Services

For advanced users who want granular control over each service.

Step 1: Network Creation

# Create Docker network
docker network create weak-website-network

Step 2: Database Container

# Start MySQL container
docker run -d \
  --name weak-website-db \
  --network weak-website-network \
  -e MYSQL_ROOT_PASSWORD=rootpassword \
  -e MYSQL_DATABASE=hermes-weak-website-db \
  -e MYSQL_USER=user \
  -e MYSQL_PASSWORD=password \
  -p 3306:3306 \
  mysql:latest

# Wait for database to initialize
sleep 30

# Verify database connection
docker exec weak-website-db mysql -u user -ppassword -e "SHOW DATABASES;"

Step 3: Server Container

# Build server image
cd server
docker build -f Dockerfile.dev -t weak-website-server .

# Start server container
docker run -d \
  --name weak-website-server \
  --network weak-website-network \
  -e DB_HOST=weak-website-db \
  -e DB_PORT=3306 \
  -e DB_USER=user \
  -e DB_PASSWORD=password \
  -e DB_DATABASE=hermes-weak-website-db \
  -e JWT_SECRET=hardcoded-secret \
  -e SERVER_PORT=8080 \
  -p 8080:8080 \
  weak-website-server

# Verify server
curl http://localhost:8080/api

Step 4: Client Container

# Build client image
cd ../client
docker build -t weak-website-client .

# Start client container
docker run -d \
  --name weak-website-client \
  --network weak-website-network \
  -e VITE_SERVER_URL=http://localhost:8080 \
  -p 8081:8081 \
  weak-website-client

# Verify client
curl http://localhost:8081

Platform-Specific Installation

Ubuntu/Debian Linux

System Preparation

# Update package manager
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install -y git curl wget gnupg2 software-properties-common

# Install Docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version
docker-compose --version

Installation Commands

# Clone and setup
git clone <repository-url>
cd hermes-fullstack/weak-website

# Setup environment
cp .env.example .env

# Start application
docker-compose -f docker-compose.dev.yml up --build -d

# Verify installation
curl http://localhost:8081
curl http://localhost:8080/api

CentOS/RHEL/Fedora

System Preparation

# Update system
sudo dnf update -y  # Fedora
# sudo yum update -y  # CentOS/RHEL

# Install required packages
sudo dnf install -y git curl wget

# Install Docker
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

macOS

Using Homebrew

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install git docker docker-compose node

# Start Docker Desktop
open /Applications/Docker.app

# Clone and setup application
git clone <repository-url>
cd hermes-fullstack/weak-website
cp .env.example .env

# Start application
docker-compose -f docker-compose.dev.yml up --build -d

Using Docker Desktop

# Download Docker Desktop for Mac
# https://www.docker.com/products/docker-desktop

# Install Docker Desktop and start

# Verify installation
docker --version
docker-compose --version

# Continue with standard installation steps
git clone <repository-url>
cd hermes-fullstack/weak-website
docker-compose -f docker-compose.dev.yml up --build -d

Windows

Using Docker Desktop

# Download and install Docker Desktop for Windows
# https://www.docker.com/products/docker-desktop

# Enable WSL 2 if prompted
# Install Git for Windows from https://git-scm.com/download/win

# Open PowerShell or Command Prompt
git clone <repository-url>
cd hermes-fullstack\weak-website

# Copy environment file
copy .env.example .env

# Start application
docker-compose -f docker-compose.dev.yml up --build -d

Using WSL 2 (Recommended for Windows)

# Install WSL 2 and Ubuntu distribution
# Follow Microsoft's WSL installation guide

# In WSL terminal, follow Ubuntu installation steps
sudo apt update
sudo apt install -y git curl

# Install Docker in WSL
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Start Docker service
sudo service docker start

# Continue with standard Linux installation
git clone <repository-url>
cd hermes-fullstack/weak-website
docker-compose -f docker-compose.dev.yml up --build -d

Post-Installation Setup

Initial Configuration

Verify Services

# Check all containers are running
docker-compose ps

# Expected output:
# NAME                     STATUS
# weak-website-client-1    Up
# weak-website-server-1    Up  
# weak-website-db-1       Up

# Check logs for any errors
docker-compose logs

Test Application Access

# Test client application
curl -I http://localhost:8081
# Expected: HTTP/1.1 200 OK

# Test server API
curl -I http://localhost:8080
# Expected: HTTP/1.1 404 Not Found (no root endpoint)

# Test API documentation
curl -I http://localhost:8080/api
# Expected: HTTP/1.1 200 OK

# Test database connectivity
docker-compose exec db mysql -u user -ppassword -e "SELECT 1;"

Create Test Accounts

# Register test users via API
curl -X POST http://localhost:8080/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"TestPass123!"}'

# Verify login works
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"TestPass123!"}'

Security Testing Setup

Install Testing Tools

# Install common security testing tools (Ubuntu/Debian)
sudo apt install -y nmap nikto dirb sqlmap

# Install Python testing tools
pip3 install requests beautifulsoup4 selenium

# Install Node.js testing tools
npm install -g newman postman-collection-runner

Basic Vulnerability Verification

# Test SQL injection
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin'\''--","password":"anything"}'

# Test path traversal
curl "http://localhost:8080/file/retrieve?path=../../../../etc/passwd"

# Test command injection
curl -X POST http://localhost:8080/file/execute \
  -H "Content-Type: application/json" \
  -d '{"command":"whoami"}'

Development Environment Setup

IDE Configuration

Visual Studio Code Setup

# Install VS Code extensions for development
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension bradlc.vscode-tailwindcss
code --install-extension ms-vscode.vscode-docker
code --install-extension ms-vscode.remote-containers

# Open project in VS Code
code .

Development Tools Setup

# Install development dependencies globally
npm install -g @nestjs/cli typescript ts-node nodemon

# Install database management tools
npm install -g mysql-client

# Install API testing tools
npm install -g @apidevtools/swagger-parser

Hot Reload Configuration

Server Hot Reload

# Development mode with file watching
cd server
npm run start:dev

# Or with Docker (already configured in docker-compose.dev.yml)
docker-compose -f docker-compose.dev.yml up

Client Hot Reload

# Development server with HMR
cd client
npm run dev

# Or with Docker (already configured)
docker-compose -f docker-compose.dev.yml up

Performance Optimization

Development Performance

# Increase Node.js memory limit for development
export NODE_OPTIONS="--max-old-space-size=4096"

# Enable Docker BuildKit for faster builds
export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

# Use Docker layer caching
docker-compose build --parallel

Database Performance

-- MySQL optimization for development
SET GLOBAL innodb_buffer_pool_size = 268435456;  -- 256MB
SET GLOBAL query_cache_size = 67108864;  -- 64MB
SET GLOBAL query_cache_type = 1;

Automated Installation Script

Complete Setup Script

#!/bin/bash
# install-weak-website.sh - Automated installation script

set -e  # Exit on any error

echo "🚀 Starting Weak Website Installation"
echo "⚠️  Educational use only - Do not use in production!"

# Check prerequisites
check_prerequisites() {
    echo "📋 Checking prerequisites..."
    
    # Check Docker
    if ! command -v docker &> /dev/null; then
        echo "❌ Docker is not installed. Please install Docker first."
        exit 1
    fi
    
    # Check Docker Compose
    if ! command -v docker-compose &> /dev/null; then
        echo "❌ Docker Compose is not installed. Please install Docker Compose first."
        exit 1
    fi
    
    # Check Git
    if ! command -v git &> /dev/null; then
        echo "❌ Git is not installed. Please install Git first."
        exit 1
    fi
    
    echo "✅ All prerequisites satisfied"
}

# Clone repository
clone_repository() {
    echo "📥 Cloning repository..."
    
    if [ ! -d "hermes-fullstack" ]; then
        git clone <repository-url>
    else
        echo "📁 Repository already exists, pulling latest changes..."
        cd hermes-fullstack && git pull && cd ..
    fi
    
    cd hermes-fullstack/weak-website
}

# Setup environment
setup_environment() {
    echo "⚙️  Setting up environment..."
    
    if [ ! -f ".env" ]; then
        cp .env.example .env
        echo "📝 Created .env file with default settings"
    else
        echo "📄 .env file already exists"
    fi
    
    # Create necessary directories
    mkdir -p logs uploads backups
    chmod 755 logs uploads backups
}

# Start application
start_application() {
    echo "🚀 Starting application..."
    
    # Build and start services
    docker-compose -f docker-compose.dev.yml up --build -d
    
    # Wait for services to be ready
    echo "⏳ Waiting for services to start..."
    sleep 30
    
    # Verify services
    if curl -s http://localhost:8081 > /dev/null && curl -s http://localhost:8080/api > /dev/null; then
        echo "✅ Application started successfully!"
        echo ""
        echo "🌐 Application URLs:"
        echo "   Client: http://localhost:8081"
        echo "   Server: http://localhost:8080"
        echo "   API Docs: http://localhost:8080/api"
        echo ""
        echo "👤 Default Test Account:"
        echo "   Email: [email protected]"
        echo "   Password: password123"
        echo ""
        echo "📚 Next Steps:"
        echo "   1. Visit http://localhost:8081 to access the application"
        echo "   2. Read the documentation at /wiki/"
        echo "   3. Start with SQL injection testing: admin'--"
        echo ""
        echo "⚠️  Remember: This is for educational purposes only!"
    else
        echo "❌ Application failed to start properly"
        echo "📋 Check logs with: docker-compose logs"
        exit 1
    fi
}

# Main installation flow
main() {
    check_prerequisites
    clone_repository
    setup_environment
    start_application
}

# Run installation
main "$@"

Usage

# Make script executable
chmod +x install-weak-website.sh

# Run installation
./install-weak-website.sh

# Or one-liner installation
curl -fsSL https://raw.githubusercontent.com/user/repo/main/install-weak-website.sh | bash

Uninstallation

Complete Removal

# Stop and remove containers
docker-compose down -v

# Remove images
docker rmi $(docker images | grep weak-website | awk '{print $3}')

# Remove volumes (this will delete all data)
docker volume prune -f

# Remove networks
docker network prune -f

# Remove project directory
cd ..
rm -rf hermes-fullstack

# Remove Docker completely (optional)
sudo apt remove docker-ce docker-ce-cli containerd.io
sudo rm -rf /var/lib/docker

Next Steps:

Related Topics: