FJurmanovic/acc-server-manager
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
07407e4db170eb0fe19e00a960e31d3cba6d6614
acc-server-manager/scripts/README.md
Fran Jurmanović b1792e1c71 deploy CI
2025-07-04 19:25:34 +02:00

6.9 KiB
Raw Blame History

ACC Server Manager Deployment Scripts

This directory contains scripts and tools for deploying the ACC Server Manager to a Windows server.

Overview

The deployment process automates the following steps:

  1. Build the application binaries for Windows
  2. Copy binaries to the target server
  3. Stop the Windows service
  4. Backup current deployment
  5. Deploy new binaries
  6. Run database migrations
  7. Start the Windows service
  8. Verify deployment success

Files

  • deploy.ps1 - Main PowerShell deployment script
  • deploy.bat - Batch file wrapper for easier execution
  • deploy.config.example - Configuration template
  • README.md - This documentation

Prerequisites

Local Machine (Build Environment)

  • Go 1.23 or later
  • PowerShell (Windows PowerShell 5.1+ or PowerShell Core 7+)
  • SSH client (OpenSSH recommended)
  • SCP utility

Target Windows Server

  • Windows Server 2016 or later
  • PowerShell 5.1 or later
  • SSH Server (OpenSSH Server or similar)
  • ACC Server Manager Windows service configured

Setup

1. Configure SSH Access

Ensure SSH access to your Windows server:

# On Windows Server, install OpenSSH Server
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType 'Automatic'

2. Create Deployment Configuration

Copy the configuration template and customize it:

cp deploy.config.example deploy.config
# Edit deploy.config with your server details

3. Set Up Windows Service

Ensure the ACC Server Manager is installed as a Windows service on the target server. You can use tools like NSSM or create a native Windows service.

Usage

Option 1: Using Batch Script (Recommended)

# Basic deployment
deploy.bat 192.168.1.100 admin "C:\AccServerManager"

# With additional options
deploy.bat 192.168.1.100 admin "C:\AccServerManager" -SkipTests

# Test deployment (dry run)
deploy.bat 192.168.1.100 admin "C:\AccServerManager" -WhatIf

Option 2: Using PowerShell Script Directly

# Basic deployment
.\deploy.ps1 -ServerHost "192.168.1.100" -ServerUser "admin" -DeployPath "C:\AccServerManager"

# With custom service name
.\deploy.ps1 -ServerHost "192.168.1.100" -ServerUser "admin" -DeployPath "C:\AccServerManager" -ServiceName "MyAccService"

# Skip tests and build
.\deploy.ps1 -ServerHost "192.168.1.100" -ServerUser "admin" -DeployPath "C:\AccServerManager" -SkipTests -SkipBuild

# Dry run
.\deploy.ps1 -ServerHost "192.168.1.100" -ServerUser "admin" -DeployPath "C:\AccServerManager" -WhatIf

Option 3: Using GitHub Actions

The CI/CD pipeline automatically deploys when changes are pushed to the main branch. Configure the following secrets in your GitHub repository:

  • WINDOWS_SERVER_HOST - Server hostname or IP
  • WINDOWS_SERVER_USER - SSH username
  • WINDOWS_SERVER_SSH_KEY - SSH private key
  • DEPLOY_PATH - Deployment directory on server
  • SLACK_WEBHOOK_URL - (Optional) Slack webhook for notifications

Parameters

Required Parameters

  • ServerHost - Target Windows server hostname or IP address
  • ServerUser - Username for SSH connection
  • DeployPath - Full path where the application will be deployed

Optional Parameters

  • ServiceName - Windows service name (default: "ACC Server Manager")
  • BinaryName - Main binary name (default: "acc-server-manager")
  • MigrateBinaryName - Migration binary name (default: "acc-migrate")
  • SkipBuild - Skip the build process
  • SkipTests - Skip running tests
  • WhatIf - Show what would be done without executing

Deployment Process Details

1. Build Phase

  • Runs Go tests (unless -SkipTests is specified)
  • Builds API binary for Windows (GOOS=windows, GOARCH=amd64)
  • Builds migration tool for Windows
  • Creates binaries in .\build directory

2. Pre-deployment

  • Copies binaries to server's temporary directory
  • Creates deployment script on server

3. Deployment

  • Stops the Windows service
  • Creates backup of current deployment
  • Copies new binaries to deployment directory
  • Runs database migrations
  • Starts the Windows service
  • Verifies service is running

4. Rollback (if deployment fails)

  • Restores from backup
  • Restarts service with previous version
  • Reports failure

5. Cleanup

  • Removes temporary files
  • Keeps last 5 backups (configurable)

Troubleshooting

Common Issues

SSH Connection Failed

Test-NetConnection -ComputerName <server> -Port 22

Ensure SSH server is running and accessible.

Service Not Found

Verify the service name matches exactly:

Get-Service -Name "ACC Server Manager"

Permission Denied

Ensure the SSH user has permissions to:

  • Stop/start the service
  • Write to the deployment directory
  • Execute PowerShell scripts

Build Failures

Check Go version and dependencies:

go version
go mod tidy
go test ./...

Debug Mode

Run with verbose output:

$VerbosePreference = "Continue"
.\deploy.ps1 -ServerHost "..." -ServerUser "..." -DeployPath "..." -Verbose

Log Files

Deployment logs are stored in:

  • Local: PowerShell transcript files
  • Remote: Windows Event Log (Application log)

Security Considerations

  1. SSH Keys: Use SSH key authentication instead of passwords
  2. Service Account: Run the service with minimal required permissions
  3. Firewall: Restrict SSH access to deployment machines only
  4. Backup Encryption: Consider encrypting backup files
  5. Secrets Management: Use secure storage for configuration files

Customization

Custom Migration Scripts

Place custom migration scripts in the scripts/migrations directory. They will be executed in alphabetical order.

Pre/Post Deployment Hooks

Configure custom scripts in the deployment configuration:

PreDeployScript=scripts/pre-deploy.ps1
PostDeployScript=scripts/post-deploy.ps1

Environment Variables

Set environment variables during deployment:

EnvironmentVariables=ENV=production,LOG_LEVEL=info

Monitoring and Notifications

Slack Notifications

Configure Slack webhook URL to receive deployment notifications:

SlackWebhookUrl=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Health Checks

Configure health check endpoint to verify deployment:

HealthCheckUrl=http://localhost:8080/health
HealthCheckTimeout=60

Best Practices

  1. Test deployments in a staging environment first
  2. Use the -WhatIf flag to preview changes
  3. Monitor service logs after deployment
  4. Keep backups of working deployments
  5. Use version tagging for releases
  6. Document configuration changes
  7. Test rollback procedures regularly

Support

For issues with deployment scripts:

  1. Check the troubleshooting section
  2. Review deployment logs
  3. Verify server prerequisites
  4. Test SSH connectivity manually
  5. Check Windows service configuration

For application-specific issues, refer to the main project documentation.