added installer

Installer/README-FIRST.txt

@@ -0,0 +1,334 @@
+================================================================================
+GSP WINDOWS AGENT INSTALLER
+================================================================================
+
+This installer package contains everything needed to deploy the GSP Windows
+Agent on a Windows server. The agent runs game server processes and provides
+RPC communication with the OGP Panel.
+
+================================================================================
+SYSTEM REQUIREMENTS
+================================================================================
+
+- Windows Server 2016 or later (or Windows 10/11 for testing)
+- Administrator privileges (required to create C:\GSP and Task Scheduler entry)
+- Network connectivity to Panel server
+- Sufficient disk space for game server installations
+
+================================================================================
+BEFORE YOU START
+================================================================================
+
+1. Unzip this installer package to any folder
+2. You may need to edit the installation path (default: C:\GSP)
+3. You MUST have the Panel's encryption key (shared key for agent communication)
+
+================================================================================
+INSTALLATION STEPS
+================================================================================
+
+1. Right-click on install.bat
+2. Select "Run as Administrator"
+3. Click "Yes" when prompted for Administrator permission
+4. Answer the configuration questions:
+   - Installation path (default: C:\GSP)
+   - Git repository URL (can use default)
+   - Git branch (default: master)
+   - Agent listen IP (default: 0.0.0.0)
+   - Agent listen port (default: 12679)
+   - Encryption key (MUST match Panel configuration)
+
+The installer will:
+- Create C:\GSP directory structure
+- Extract Portable Git (included in this package)
+- Clone the Windows Agent repository
+- Create configuration files from templates
+- Set up a Windows Task Scheduler entry
+- Configure the agent to auto-start at system boot
+
+================================================================================
+INSTALLATION DETAILS
+================================================================================
+
+Install Layout
+--------------
+After installation, you'll have:
+
+C:\GSP\
+  Agent\           - Git clone of Windows Agent repository
+    .git\          - Git metadata (allows updates)
+    OGP64\         - Bundled Cygwin runtime
+    Cfg\           - Configuration files
+    docs\          - Documentation
+  home\            - Game server files directory (never deleted by installer)
+  tools\
+    PortableGit\   - Bundled Git (for updates/rollback)
+  backups\
+    agent\         - Automatic backups from updates
+  logs\            - Installation, update, and rollback logs
+
+First Run
+---------
+The agent will:
+1. Start automatically with Windows system startup
+2. Run under SYSTEM account (highest privileges)
+3. Execute startup scripts with Cygwin environment
+4. Listen on the configured IP and port
+5. Write logs to: C:\GSP\Agent\OGP64\OGP\ogp_agent.log
+
+Manual Start
+------------
+If you need to start the agent manually:
+  1. Open Command Prompt as Administrator
+  2. Run: C:\GSP\Agent\OGP64\agent_start.bat
+
+Manual Stop
+-----------
+To stop the agent:
+  1. Open Command Prompt as Administrator
+  2. Run: C:\GSP\Agent\OGP64\agent_stop.bat
+
+================================================================================
+AFTER INSTALLATION
+================================================================================
+
+Configure Panel
+---------------
+1. Log in to the Panel as admin
+2. Add the Windows Agent:
+   - IP/Hostname: (the Windows server's IP)
+   - Port: 12679 (or your configured port)
+   - Encryption Key: (use the same key you entered during install)
+   - Shared Key: (same as encryption key)
+
+Verify Agent Connection
+-----------------------
+1. From the Panel, check the agent's status
+2. Run a test command from the Panel
+3. Check C:\GSP\Agent\OGP64\OGP\ogp_agent.log for debug output
+
+================================================================================
+UPDATING THE AGENT
+================================================================================
+
+The bundled Portable Git allows easy updates without requiring system Git.
+
+To Update
+---------
+1. Right-click update.bat (in the original Installer folder)
+2. Select "Run as Administrator"
+3. The updater will:
+   - Stop the running agent
+   - Back up the current version
+   - Fetch updates from Git
+   - Restore your configuration and game files
+   - Restart the agent
+
+Updates preserve:
+  - C:\GSP\home (all game server files)
+  - C:\GSP\Agent\Cfg (agent configuration)
+  - C:\GSP\Agent\screenlogs (server logs)
+  - C:\GSP\Agent\startups (startup flags)
+  - C:\GSP\Agent\OGP64\steamcmd (SteamCMD files)
+
+================================================================================
+ROLLING BACK
+================================================================================
+
+If an update causes problems, you can restore a previous version.
+
+To Rollback
+-----------
+1. Right-click rollback.bat (in the original Installer folder)
+2. Select "Run as Administrator"
+3. The rollback script will:
+   - List available backups (with timestamps)
+   - Let you select which version to restore
+   - Optionally preserve your current configuration
+   - Restore the previous version
+   - Restart the agent
+
+Available Backups
+-----------------
+Backups are stored in: C:\GSP\backups\agent\
+
+Each backup includes:
+  - Agent binaries and scripts
+  - Perl modules
+  - Cygwin runtime
+  - But NOT game server files or logs
+
+================================================================================
+PERMANENT REMOVAL
+================================================================================
+
+To Remove Only the Scheduled Task
+-----------------------------------
+1. Right-click uninstall-task.bat (in the original Installer folder)
+2. Select "Run as Administrator"
+3. This removes only the Task Scheduler entry
+4. The agent directory and game servers remain intact
+5. You can manually start the agent later with agent_start.bat
+
+Full Removal (if needed)
+------------------------
+To completely remove the agent:
+1. Run uninstall-task.bat first
+2. Manually delete C:\GSP\Agent
+3. Leave C:\GSP\home (contains your game servers)
+4. Leave C:\GSP\backups (for recovery)
+
+WARNING: Do NOT delete C:\GSP\home - it contains your game server installations!
+
+================================================================================
+TROUBLESHOOTING
+================================================================================
+
+Agent Won't Start
+-----------------
+1. Check the log file:
+   C:\GSP\Agent\OGP64\OGP\ogp_agent.log
+
+2. Try manual start:
+   Right-click C:\GSP\Agent\OGP64\agent_start.bat
+   Select "Run as Administrator"
+
+3. Verify configuration:
+   Check C:\GSP\Agent\OGP64\OGP\Cfg\Config.pm for encryption key
+
+4. Check Windows Event Viewer:
+   Windows Logs > System (for Task Scheduler errors)
+
+Panel Can't Connect
+-------------------
+1. Verify the agent is running:
+   tasklist | findstr /i bash
+
+2. Check Windows Firewall:
+   Allow C:\GSP\Agent\OGP64\bin\bash.exe through firewall
+   Allow TCP port 12679 (or configured port) inbound
+
+3. Verify Panel encryption key matches:
+   Must match exactly in both Panel and C:\GSP\Agent\OGP64\OGP\Cfg\Config.pm
+
+4. Check agent log:
+   C:\GSP\Agent\OGP64\OGP\ogp_agent.log
+
+Installation Failed
+-------------------
+1. Check the installation log:
+   C:\GSP\logs\install.log
+
+2. Verify permissions:
+   Run as Administrator (right-click, "Run as Administrator")
+
+3. Check free disk space:
+   At least 500MB required for Portable Git and agent
+
+4. Check Portable Git extraction:
+   Should be at: C:\GSP\tools\PortableGit\cmd\git.exe
+
+================================================================================
+ADVANCED TOPICS
+================================================================================
+
+Configuration Files (reference only)
+------------------------------------
+Important Agent configuration files are in:
+  C:\GSP\Agent\OGP64\OGP\Cfg\
+
+Main files:
+  Config.pm       - Encryption key, listen port/IP
+  Preferences.pm  - Optional preferences
+  bash_prefs.cfg  - Bash shell preferences
+
+Do NOT edit these manually unless you understand Perl syntax!
+
+Manual Git Operations
+---------------------
+You can use Portable Git directly:
+  C:\GSP\tools\PortableGit\cmd\git.exe [command]
+
+Example - Check current branch:
+  cd C:\GSP\Agent
+  C:\GSP\tools\PortableGit\cmd\git.exe status
+
+Environmental Variables
+------------------------
+The following directories are set by the installer:
+
+C:\GSP\
+  Agent\         - Windows Agent Git clone
+  home\          - Game servers
+  tools\         - Portable Git
+  backups\       - Automatic backups
+  logs\          - Installation logs
+  
+These locations can be changed by editing install.bat parameters.
+
+================================================================================
+SUPPORT & DOCUMENTATION
+================================================================================
+
+More Information
+----------------
+- Main documentation: C:\GSP\Agent\README.md
+- Agent guide: C:\GSP\Agent\docs\AGENT_ARCHITECTURE.md
+- Panel documentation: Check your Panel installation
+
+Getting Help
+------------
+1. Check the relevant log file
+2. Review documentation in C:\GSP\Agent\docs\
+3. Check Panel logs on the Panel server
+4. Verify network connectivity between servers
+
+================================================================================
+SECURITY NOTES
+================================================================================
+
+1. Encryption Key
+   - The encryption key in Config.pm is critical
+   - Must match exactly on Panel and Agent
+   - Treat this key as a production secret
+   - Do NOT commit Config.pm to public Git repositories
+
+2. Network Security
+   - Agent runs as SYSTEM (highest Windows privileges)
+   - Restrict network access to Panel server IP only
+   - Use Windows Firewall to limit inbound connections
+   - Consider VPN or internal network isolation
+
+3. File Permissions
+   - C:\GSP\home must be accessible to all game processes
+   - C:\GSP\Agent must be readable by SYSTEM account
+   - Configure Windows ACLs as needed for your environment
+
+4. Logging
+   - Agent logs contain diagnostic information
+   - Logs may include command parameters
+   - Rotate logs to manage disk space
+   - Archive logs for audit trails if needed
+
+================================================================================
+VERSION INFORMATION
+================================================================================
+
+Installer Version: GSP Windows Agent 1.0
+Release Date: June 2026
+Portable Git Version: 2.54.0 (64-bit)
+
+Compatible With:
+  - Windows Server 2016+
+  - Windows 10/11 (for testing)
+  - OGP Panel v1.4+
+  - Linux Agent v1.4+ (for comparison)
+
+================================================================================
+
+For more information, see:
+  - Installer folder: README.txt (this file)
+  - Agent repository: C:\GSP\Agent\README.md
+  - Documentation folder: C:\GSP\Agent\docs\
+
+================================================================================