slms/docs/BACKUP_GUIDE.md

SLMS Project Backup Guide

Overview

This guide provides comprehensive instructions for backing up the SLMS project and all related configurations before performing the repository restructure.

Quick Start

To create a backup, run:

cd /d %PROJECT_ROOT%
scripts\backup_project.bat

This will create a timestamped backup directory containing:

• Complete project files
• Jenkins configuration backup
• SonarQube configuration backup
• Backup summary and verification checklist

Backup Components

1. Project Files Backup

What's Included:

• Source code (src/, backend/, android/)
• Build configurations (pom.xml, build.gradle, settings.gradle)
• Scripts (scripts/)
• Documentation (docs/)
• Configuration files (Jenkinsfile, sonar-project.properties)

What's Excluded:

• Build artifacts (target/, build/)
• IDE files (.idea/, .vscode/)
• Git history (.git/)
• Temporary files (*.tmp, *.log)

Manual Backup Alternative:

REM Create backup directory
mkdir backup_manual

REM Copy project files
xcopy /E /I /H /Y /EXCLUDE:backup_exclude.txt . backup_manual\project

2. Jenkins Configuration Backup

Automated Backup: The script backs up:

• Jenkinsfile

Manual Steps Required:

Export Job Configuration

1. Via Jenkins UI:

   • Navigate to: http://localhost:8080/job/YOUR_JOB_NAME/config.xml
   • Save the XML file

2. Via Jenkins CLI:

   java -jar jenkins-cli.jar -s http://localhost:8080/ -auth USER:TOKEN get-job SLMS > job-config.xml
   

Export Credentials

Document the following credential IDs:

• gitea-credentials - Local Gitea access
• educoder-credentials - 头歌 repository access
• sonarqube-token - SonarQube authentication

Note: Credential values cannot be exported for security reasons. Document the IDs and be prepared to recreate them.

Export System Configuration

1. Global Tool Configuration:

   • Navigate to: http://localhost:8080/configureTools/
   • Document JDK, Maven, Gradle installations

2. System Configuration:

   • Navigate to: http://localhost:8080/configure/
   • Document environment variables and system settings

Export Installed Plugins

java -jar jenkins-cli.jar -s http://localhost:8080/ -auth USER:TOKEN list-plugins > plugins.txt

3. SonarQube Configuration Backup

Automated Backup: The script backs up:

• sonar-project.properties

Manual Steps Required:

Export Project Settings

1. Via SonarQube UI:

   • Navigate to: http://localhost:9000/dashboard?id=slms
   • Go to: Project Settings > General Settings
   • Document all custom settings

2. Via SonarQube API:

   curl -u YOUR_TOKEN: http://localhost:9000/api/settings/values?component=slms > sonar-settings.json
   

Export Quality Gates

1. Via SonarQube UI:

   • Navigate to: http://localhost:9000/quality_gates
   • Document quality gate name and conditions

2. Via SonarQube API:

   curl -u YOUR_TOKEN: http://localhost:9000/api/qualitygates/show?name=YOUR_GATE > qualitygate.json
   

Export Quality Profiles

1. Via SonarQube UI:

   • Navigate to: http://localhost:9000/profiles
   • Document active profiles for Java

2. Via SonarQube API:

   curl -u YOUR_TOKEN: http://localhost:9000/api/qualityprofiles/search > profiles.json
   

Export Webhooks

1. Via SonarQube UI:

   • Navigate to: http://localhost:9000/project/webhooks?id=slms
   • Document webhook URLs and configurations

2. Via SonarQube API:

   curl -u YOUR_TOKEN: http://localhost:9000/api/webhooks/list?project=slms > webhooks.json
   

Backup Verification

After creating the backup, verify completeness using the checklist:

type backup_TIMESTAMP\VERIFICATION_CHECKLIST.md

Critical Verification Steps

1. Check Backup Size:

   dir backup_TIMESTAMP /s
   

   Expected size: 50-200 MB (depending on project size)

2. Verify Key Files:

   dir backup_TIMESTAMP\project\pom.xml
   dir backup_TIMESTAMP\project\Jenkinsfile
   dir backup_TIMESTAMP\project\sonar-project.properties
   

3. Test File Accessibility:

   • Open a few source files to ensure they're readable
   • Check that no files are corrupted

Restoration Instructions

Restore Project Files

REM Navigate to desired restoration location
cd /d C:\restoration_location

REM Restore all project files
xcopy /E /I /H /Y backup_TIMESTAMP\project\* .

Restore Jenkins Configuration

1. Restore Jenkinsfile:

   copy backup_TIMESTAMP\jenkins\Jenkinsfile.backup Jenkinsfile
   

2. Import Job Configuration:

   • Via Jenkins UI: New Item > Copy from existing job
   • Via Jenkins CLI:

     java -jar jenkins-cli.jar -s http://localhost:8080/ create-job SLMS < job-config.xml
     

3. Recreate Credentials:

   • Navigate to: http://localhost:8080/credentials/
   • Add credentials with the same IDs as documented

Restore SonarQube Configuration

1. Restore Project Properties:

   copy backup_TIMESTAMP\sonarqube\sonar-project.properties.backup sonar-project.properties
   

2. Recreate Project:

   • Navigate to: http://localhost:9000/projects/create
   • Use project key: slms (or slms:slms if that was the original)

3. Restore Quality Gates and Profiles:

   • Apply documented quality gates
   • Activate documented quality profiles

4. Recreate Webhooks:

   • Add webhooks with documented URLs

Backup Storage Recommendations

Short-term Storage (During Restructure)

• Keep backup in a separate directory on the same machine
• Location: C:\backups\slms\ or similar
• Duration: Until restructure is verified successful (1-2 weeks)

Long-term Storage (Archive)

• Compress backup directory:

  tar -czf slms_backup_%date%.tar.gz backup_TIMESTAMP\
  

• Store in:
  • Network drive
  • External hard drive
  • Cloud storage (if permitted)
• Duration: 3-6 months

Troubleshooting

Backup Script Fails

Issue: Permission denied errors

Solution:

REM Run as administrator
runas /user:Administrator "cmd /c scripts\backup_project.bat"

Issue: Disk space insufficient

Solution:

• Check available space: dir C:\ | findstr "bytes free"
• Clean up unnecessary files
• Use external drive for backup

Incomplete Backup

Issue: Some files not copied

Solution:

• Check backup_exclude.txt for unintended exclusions
• Manually copy missing files
• Verify file permissions

Jenkins Export Fails

Issue: Cannot access Jenkins CLI

Solution:

• Download Jenkins CLI: http://localhost:8080/jnlpJars/jenkins-cli.jar
• Verify Jenkins is running
• Check authentication credentials

SonarQube Export Fails

Issue: API authentication fails

Solution:

• Generate new token: http://localhost:9000/account/security
• Use token in curl commands: -u TOKEN:
• Verify SonarQube is running

Backup Checklist

Before proceeding with restructure, ensure:

• Backup script executed successfully
• Project files backed up completely
• Jenkinsfile backed up
• Jenkins job configuration exported
• Jenkins credentials documented
• sonar-project.properties backed up
• SonarQube project settings documented
• SonarQube quality gates documented
• Backup verification checklist completed
• Backup stored in safe location
• Restoration process understood

Next Steps

After completing the backup:

1. Review backup summary: backup_TIMESTAMP\BACKUP_SUMMARY.md
2. Complete verification checklist: backup_TIMESTAMP\VERIFICATION_CHECKLIST.md
3. Store backup in safe location
4. Proceed with task 2: Modify Jenkinsfile

Support

If you encounter issues during backup:

1. Check error messages in console output
2. Review this guide's troubleshooting section
3. Verify system requirements (disk space, permissions)
4. Document any issues for future reference

---

Last Updated: 2025-11-26 Version: 1.0