🐳 DEVSFORGE - Installation and Usage Guide

Complete documentation for building and running devsforge on Docker with automated scripts.

Repository: https://github.com/iscar-ucm/devsforge

---

⚡ Quick Start

Clone the Repository

git clone https://github.com/iscar-ucm/devsforge.git
cd devsforge

Run Immediately

• Windows (Recommended): .\run_devsforge_init.cmd
• Windows (PowerShell): powershell -ExecutionPolicy RemoteSigned -File run_devsforge.ps1
• Windows (CMD): run_devsforge.bat
• Linux/macOS: bash run_devsforge.sh

Access the Application (Default URL)

http://localhost:8090/devsforge

📁 Note: The example code is located in the shared volume:

• Windows: C:\devsforge\code
• Linux: ~/devsforge/code (or /home/your-user/devsforge/code)
• macOS: ~/devsforge/code (or /Users/your-user/devsforge/code)

---

📋 Table of Contents

1. Requirements
2. Installing Requirements
3. Execution Files
4. Script Usage
5. Configuration
6. Application Access
7. Useful Commands
8. Troubleshooting
9. Project Structure

---

✅ Requirements

Minimum Hardware

• CPU: Dual-core processor or higher
• RAM: 4 GB minimum (8 GB recommended)
• Disk Space: 10 GB minimum for the Docker image

Required Software

• Docker Desktop (version 4.0 or higher)
  • On Windows: Requires WSL 2 or Hyper-V
  • On macOS: Apple Silicon or Intel
  • On Linux: Docker Engine
• PowerShell 5.1 (for Windows with .ps1)
• CMD/MS-DOS (for Windows with .bat)
• Bash (for Linux/macOS with .sh)

---

🔧 Installing Requirements

Windows - Installing Docker Desktop

Option 1: Direct Download

1. Go to https://www.docker.com/products/docker-desktop
2. Download Docker Desktop for Windows
3. Run the installer
4. Restart your computer when prompted

Option 2: Using Package Manager (winget)

winget install Docker.DockerDesktop

Verify Installation

docker --version
docker run hello-world

macOS - Installing Docker Desktop

Option 1: Direct Download

1. Go to https://www.docker.com/products/docker-desktop
2. Download based on your processor:
   • Apple Silicon: ARM64 version
   • Intel: x86_64 version
3. Open the .dmg file and drag Docker to Applications

Option 2: Using Homebrew

brew install docker
brew install --cask docker

Verify Installation

docker --version
docker run hello-world

Linux - Installing Docker Engine

Ubuntu/Debian

# Update package indexes
sudo apt-get update

# Install dependencies
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Add official Docker repository
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Install Docker
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# Add current user to docker group (optional, to avoid sudo)
sudo usermod -aG docker $USER
newgrp docker

Verify Installation

docker --version
docker run hello-world

---

📁 Execution Files

The project includes automated scripts for different platforms:

File	Platform	Usage	Execution
run_devsforge_init.cmd	Windows	RECOMMENDED - Resolves policy errors automatically	.\run_devsforge_init.cmd
run_devsforge.ps1	Windows (PowerShell)	Direct execution	.\run_devsforge.ps1 or powershell -ExecutionPolicy RemoteSigned -File run_devsforge.ps1
run_devsforge.bat	Windows (CMD)	Alternative if PowerShell doesn't work	run_devsforge.bat
run_devsforge.sh	Linux/macOS (Bash)	Bash script	bash run_devsforge.sh

Script Location

devsforge/
├── run_devsforge_init.cmd   ← Windows initializer (recommended)
├── run_devsforge.ps1        ← PowerShell script (Windows)
├── run_devsforge.bat        ← CMD script (Windows)
├── run_devsforge.sh         ← Bash script (Linux/macOS)
├── docker/
│   └── Dockerfile
├── app/
├── assets/
├── code/
└── README.md

---

🚀 Script Usage

Windows - PowerShell (RECOMMENDED - Automatically fixes policy error)

Option A: Using the Initializer (Easier - Recommended)

# 1. Open a normal terminal (NOT admin)
# 2. Navigate to the project folder
cd C:\path\to\project\devsforge

# 3. Run the initializer
.\run_devsforge_init.cmd

Benefit: Automatically resolves the execution policy error. ✅

Option B: Run PowerShell Directly (If Option A doesn't work)

# 1. Open a normal terminal (NOT admin)
# 2. Navigate to the project folder
cd C:\path\to\project\devsforge

# 3. Run the script with adjusted policy
powershell -NoProfile -ExecutionPolicy RemoteSigned -File run_devsforge.ps1

Note: If you still get policy errors, go to "Troubleshooting" → "Execution Policy Error"

Windows - CMD (MS-DOS)

Step 1: Open CMD

1. Press Win + R
2. Type cmd and press Enter
3. Or search for "CMD" in the Start menu

Step 2: Navigate to Project Folder

cd C:\path\to\project\devsforge

Step 3: Run the Script

run_devsforge.bat

Step 4: Wait for Completion

The script runs all steps automatically and will display colors for easy reading.

---

Linux / macOS - Bash

Step 1: Open Terminal

• Linux: Press Ctrl + Alt + T
• macOS: Cmd + Space, search for "Terminal"

Step 2: Navigate to Project Folder

cd ~/path/to/project/devsforge

Step 3: Grant Execution Permissions (first time)

chmod +x run_devsforge.sh

Step 4: Run the Script

./run_devsforge.sh

Or if permissions weren't granted:

bash run_devsforge.sh

Step 5: Wait for Completion

The script automatically runs all required steps.

---

⚙️ Configuration

Customize Paths and Ports

If you need to change the shared folder path, port, or container name, open the corresponding file and modify the variables at the beginning:

PowerShell - run_devsforge.ps1

# ⚙️  CONFIGURATION - Modify these variables as needed
$CONTAINER_NAME = "devsforge-container"
$IMAGE_NAME = "devsforge-apache"
$DOCKER_PORT = "8090"           # Port on your machine
$HOST_PORT = "80"               # Port in the container
$SHARED_FOLDER = "C:\devsforge\code"  # ← Change this path if needed
$CONTAINER_PATH = "/var/www/html/devsforge/code"

CMD - run_devsforge.bat

REM ⚙️  CONFIGURATION
set CONTAINER_NAME=devsforge-container
set IMAGE_NAME=devsforge-apache
set DOCKER_PORT=8090
set HOST_PORT=80
set SHARED_FOLDER=C:\devsforge\code    REM ← Change this path if needed
set CONTAINER_PATH=/var/www/html/devsforge/code

Bash - run_devsforge.sh

# ⚙️  CONFIGURATION
CONTAINER_NAME="devsforge-container"
IMAGE_NAME="devsforge-apache"
DOCKER_PORT="8090"
HOST_PORT="80"
SHARED_FOLDER="$HOME/devsforge/code"  # ← Change this path if needed
CONTAINER_PATH="/var/www/html/devsforge/code"

Example: Change Port to 3000

Open the corresponding file and change:

$DOCKER_PORT = "3000"

Then access: http://localhost:3000/devsforge

---

🌐 Application Access

Default URL

http://localhost:8090/devsforge

After Running the Script

1. Wait 30-60 seconds for the container to start completely
2. Open your favorite browser
3. Navigate to: http://localhost:8090/devsforge

If the Page Doesn't Load

1. Verify that the container is running:

   docker ps

2. Check the container logs:

   docker logs devsforge-container

3. Restart the container:

   docker restart devsforge-container

---

🛠️ Useful Commands

View Container Status

docker ps                           # View active containers
docker ps -a                        # View all containers
docker ps -a --filter "name=devsforge"  # Filter by name

View Container Logs

docker logs devsforge-container           # View all logs
docker logs -f devsforge-container        # View logs in real time
docker logs -f --tail 100 devsforge-container  # Last 100 lines

Manage the Container

docker stop devsforge-container      # Stop
docker start devsforge-container     # Start
docker restart devsforge-container   # Restart
docker pause devsforge-container     # Pause
docker unpause devsforge-container   # Resume

Delete Container and Image

# Delete container only
docker stop devsforge-container
docker rm devsforge-container

# Delete image
docker rmi devsforge-apache

# Clean everything (unused containers, images, volumes)
docker system prune -a --volumes

Access the Container

# Enter the container terminal
docker exec -it devsforge-container bash

# Run commands in the container
docker exec devsforge-container php -v
docker exec devsforge-container python3 --version
docker exec devsforge-container java -version

Check Installed Versions

docker exec devsforge-container php -v            # PHP
docker exec devsforge-container python3 --version # Python
docker exec devsforge-container java -version     # Java
docker exec devsforge-container rustc --version   # Rust
docker exec devsforge-container cargo --version   # Cargo
docker exec devsforge-container pip list | grep xdevs  # xdevs.py
docker exec devsforge-container ls -la /opt/xdevs.rs  # xdevs.rs

---

📊 Step-by-Step Process

When you run the script, this happens:

1. VERIFICATION
   ✓ Docker installed and accessible
   ✓ Project location identified

2. IMAGE BUILDING (5-10 minutes)
   ✓ Download Ubuntu 22.04
   ✓ Install Apache 2
   ✓ Install PHP + extensions
   ✓ Install Java
   ✓ Install Python 3
   ✓ Install Rust (rustup) and Cargo
   ✓ Install xdevs.py
   ✓ Install xdevs.rs
   ✓ Configure shared volume
   
3. FOLDER PREPARATION
   ✓ Delete old folder (if exists)
   ✓ Create new empty folder
   
4. CONTAINER STARTUP
   ✓ Run container in background
   ✓ Map port 8090 → 80
   ✓ Mount shared volume
   
5. FINAL VERIFICATION
   ✓ Verify container is running
   ✓ Display access information

---

🐛 Troubleshooting

Execution Policy Error (PowerShell)

Error:

Cannot load file [...] because script execution is disabled

Solutions (in recommended order):

✅ Option 1: Use the Initializer (RECOMMENDED)

.\run_devsforge_init.cmd

This runs PowerShell with the correct policy automatically.

✅ Option 2: Run with Policy in Command Line

powershell -NoProfile -ExecutionPolicy RemoteSigned -File run_devsforge.ps1

✅ Option 3: Change Policy Permanently (If other options don't work)

1. Open PowerShell as Administrator
2. Run:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

3. Type Y or press Enter when asked for confirmation
4. Close PowerShell completely
5. Open a new PowerShell window (without admin)
6. Try again:

   .\run_devsforge.ps1

Explanation:

• Restricted: Doesn't allow running scripts (default policy)
• RemoteSigned: Allows running local scripts
• CurrentUser: Only applies to your user, not the entire system
• -Force: Without confirmation

Error: "Docker is not installed"

Solution:

1. Download Docker Desktop from https://www.docker.com/products/docker-desktop
2. Install and restart your computer
3. Run the script again

Error: "Port 8090 is already in use"

Solution:

1. Change the port in the script (e.g.: 3000, 5000, etc.)
2. Or stop the previous container:

   docker stop devsforge-container
   docker rm devsforge-container

Error: "Execution policy" (PowerShell on Windows)

Solution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Browser can't access http://localhost:8090/devsforge

Solutions:

1. Wait 60 seconds after running the script
2. Verify Docker is running: docker ps
3. Check logs: docker logs devsforge-container
4. Try with: http://localhost:8090 (without /devsforge)
5. Restart the container: docker restart devsforge-container

The code folder doesn't sync

Solution:

# Verify the volume is mounted correctly
docker inspect devsforge-container | findstr -A 5 "Mounts"

# If it doesn't appear, delete and recreate the container
docker stop devsforge-container
docker rm devsforge-container
# Run the script again

"Error: Cannot connect to Docker daemon"

Solution:

1. Open Docker Desktop (it must be running)
2. Wait for it to completely initialize
3. Run the script again

Files don't appear in the shared folder

Solution:

1. Verify the path in the script (variable $SHARED_FOLDER)
2. Check folder permissions
3. On Linux/macOS, make sure the folder exists:

   mkdir -p $HOME/devsforge/code

---

📦 Docker Image Contents

The image includes:

• Operating System: Ubuntu 22.04 LTS
• Web Server: Apache 2.4 with mod_rewrite enabled
• PHP: Recent version with extensions:
  • php-cli
  • php-mbstring
  • php-xml
  • libapache2-mod-php
• Java: OpenJDK (default-jdk) + Maven
• xDEVS for Java: DEVS Framework for Java
  • ✅ INCLUDED in the repository: bin/xdevs.jar
  • Repository: https://github.com/iscar-ucm/xdevs
  • The JAR is automatically copied during Docker build
  • See bin/README.md for more details
• Python 3: With pip installed
• xdevs.py: DEVS Framework for Python from GitHub
• Rust: Latest stable version with Cargo (rustup)
• xdevs.rs: DEVS Framework for Rust cloned from GitHub (/opt/xdevs.rs)
• Build Tools: build-essential, pkg-config, libssl-dev
• Tools: git, curl, wget, unzip
• Time Zone: America/Lima

---

📁 Project Structure

devsforge/
├── README.md                    ← You are here
├── run_devsforge.ps1            ← PowerShell script (Windows)
├── run_devsforge.bat            ← CMD script (Windows)
├── run_devsforge.sh             ← Bash script (Linux/macOS)
├── config.php                   ← Configuration
├── errors.php                   ← Error handling
├── index.php                    ← Entry point
│
├── app/                         ← Application
│   ├── help_about_modeling.php
│   ├── help_about_simulation.php
│   ├── modeling_structure.php
│   ├── run_simulation.php
│   └── ...
│
├── assets/                      ← Static resources
│   ├── css/
│   ├── img/
│   ├── js/
│
├── bin/                         ← Binaries (xdevs.jar)
│   └── README.md
│   └── fonts/
│
├── code/                        ← SHARED VOLUME
│   ├── Generator.java
│   ├── generator.py
│   ├── src/                     ← Rust files
│   │   ├── generator.rs
│   │   ├── processor.rs
│   │   └── transducer.rs
│   ├── processor.py
│   ├── transducer.py
│   └── ...
│
├── docker/                      ← Docker configuration
│   ├── Dockerfile
│   └── Dockerfile.md
│
├── layout/                      ← Layout
│   └── ...
│
├── lib/                         ← Libraries
│   └── Router.php
│
├── .gitignore                   ← Git
└── ...

---

🔄 Recommended Workflow

First Run

# 1. Open PowerShell/CMD in the project folder
cd C:\path\to\project\devsforge

# 2. Run the script
.\run_devsforge.ps1

# 3. Wait 5-10 minutes (image building)
# 4. Wait 30-60 seconds more (container startup)
# 5. Open http://localhost:8090/devsforge

Subsequent Use

# If you need to restart the container
docker restart devsforge-container

# If you need to see the logs
docker logs -f devsforge-container

# To stop
docker stop devsforge-container

# To start again
docker start devsforge-container

---

📞 Support and Resources

Project

• GitHub Repository: https://github.com/iscar-ucm/devsforge
• Issues: https://github.com/iscar-ucm/devsforge/issues
• Discussions: https://github.com/iscar-ucm/devsforge/discussions

Official Documentation

• Docker: https://docs.docker.com/
• Docker Compose: https://docs.docker.com/compose/
• Apache: https://httpd.apache.org/docs/
• PHP: https://www.php.net/docs.php

Community

• Docker Community: https://community.docker.com/
• Stack Overflow: https://stackoverflow.com/questions/tagged/docker

---

📝 Important Notes

1. Port 8090: The application uses port 8090 by default (configurable)
2. First build: May take 5-10 minutes on the first run
3. Synchronization: The code folder syncs in real-time with the container
4. Initial files: Are copied automatically on first run
5. Docker must be running: Make sure Docker Desktop is active
6. WSL 2 (Windows): WSL 2 is recommended over Hyper-V for better performance
7. Permissions: On Linux/macOS, you may need execution permissions for the script

---

✅ Verification Checklist

Before reporting issues, verify:

• Docker is installed: docker --version
• Docker is running (Docker Desktop open)
• Port 8090 is not in use: netstat -ano | findstr :8090
• Project cloned/downloaded correctly
• Scripts have execution permissions (Linux/macOS)
• Sufficient disk space (10 GB minimum)
• Active internet connection (to download the image)

---

📄 Change History

Version	Date	Changes
1.0	2025-11-30	Initial version with automated scripts

---

🤝 Contributing

Contributions are welcome. To contribute:

1. Fork the repository: https://github.com/iscar-ucm/devsforge/fork
2. Create a branch for your feature (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

For more details, visit the repository: https://github.com/iscar-ucm/devsforge

---

Last updated: November 30, 2025

To report issues or suggestions, visit: https://github.com/iscar-ucm/devsforge/issues