created a README for deployment
I hope at makes me remember the right steps
This commit is contained in:
@@ -1,306 +0,0 @@
|
||||
# BaMoRT Deployment CLI Tool
|
||||
|
||||
Command-line interface for BaMoRT database deployment and maintenance operations.
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
go build -o deploy cmd/deploy/main.go
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### Fresh Installation
|
||||
|
||||
Create a new database installation from scratch:
|
||||
|
||||
```bash
|
||||
./deploy install
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Create all database tables using GORM AutoMigrate
|
||||
2. Initialize version tracking
|
||||
3. Import master data from files
|
||||
4. Optionally create an admin user
|
||||
|
||||
**Interactive prompts:**
|
||||
- Master data directory (default: `./masterdata`)
|
||||
- Create admin user? (y/N)
|
||||
- Admin username and password (if yes)
|
||||
|
||||
### Apply Migrations
|
||||
|
||||
Apply pending database migrations:
|
||||
|
||||
```bash
|
||||
./deploy migrate
|
||||
```
|
||||
|
||||
**Dry-run mode** (preview without applying):
|
||||
```bash
|
||||
./deploy migrate --dry-run
|
||||
```
|
||||
|
||||
### Check Status
|
||||
|
||||
Display current database version and compatibility status:
|
||||
|
||||
```bash
|
||||
./deploy status
|
||||
```
|
||||
|
||||
Shows:
|
||||
- Current database version
|
||||
- Backend version
|
||||
- Required DB version
|
||||
- Compatibility status
|
||||
- Pending migrations (if any)
|
||||
|
||||
### Create Backup
|
||||
|
||||
Create a JSON backup of the database:
|
||||
|
||||
```bash
|
||||
./deploy backup
|
||||
```
|
||||
|
||||
Automatically:
|
||||
- Creates timestamped backup file
|
||||
- Shows backup metadata (version, size, table count)
|
||||
- Cleans up backups older than 30 days
|
||||
|
||||
### Sync Master Data
|
||||
|
||||
Import/update master data from files:
|
||||
|
||||
```bash
|
||||
./deploy sync-masterdata [directory]
|
||||
```
|
||||
|
||||
Default directory: `./masterdata`
|
||||
|
||||
**Dry-run mode:**
|
||||
```bash
|
||||
./deploy sync-masterdata --dry-run
|
||||
```
|
||||
|
||||
### Rollback Migration
|
||||
|
||||
Rollback the last applied migration:
|
||||
|
||||
```bash
|
||||
./deploy rollback
|
||||
```
|
||||
|
||||
⚠️ **Warning:** Only use if migration caused issues. Requires rollback SQL to be defined.
|
||||
|
||||
### Version Information
|
||||
|
||||
Display version information:
|
||||
|
||||
```bash
|
||||
./deploy version
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### New Production Setup
|
||||
|
||||
```bash
|
||||
# 1. Build the tool
|
||||
go build -o deploy cmd/deploy/main.go
|
||||
|
||||
# 2. Fresh installation
|
||||
./deploy install
|
||||
# Enter master data path: /opt/bamort/masterdata
|
||||
# Create admin user? y
|
||||
# Admin username: admin
|
||||
# Admin password: ********
|
||||
|
||||
# 3. Verify status
|
||||
./deploy status
|
||||
|
||||
# 4. Create initial backup
|
||||
./deploy backup
|
||||
```
|
||||
|
||||
### Upgrading Existing Database
|
||||
|
||||
```bash
|
||||
# 1. Check current status
|
||||
./deploy status
|
||||
|
||||
# 2. Create backup before migration
|
||||
./deploy backup
|
||||
|
||||
# 3. Preview migrations (dry-run)
|
||||
./deploy migrate --dry-run
|
||||
|
||||
# 4. Apply migrations
|
||||
./deploy migrate
|
||||
|
||||
# 5. Verify status
|
||||
./deploy status
|
||||
```
|
||||
|
||||
### Updating Master Data
|
||||
|
||||
```bash
|
||||
# 1. Preview sync
|
||||
./deploy sync-masterdata --dry-run
|
||||
|
||||
# 2. Apply sync
|
||||
./deploy sync-masterdata
|
||||
|
||||
# Or specify custom directory
|
||||
./deploy sync-masterdata /path/to/masterdata
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The tool uses the same configuration as the backend application:
|
||||
|
||||
- `DATABASE_TYPE`: `mysql` or `sqlite` (default: `mysql`)
|
||||
- `DATABASE_HOST`: Database host (default: `localhost`)
|
||||
- `DATABASE_PORT`: Database port (default: `3306`)
|
||||
- `DATABASE_NAME`: Database name (default: `bamort`)
|
||||
- `DATABASE_USER`: Database user
|
||||
- `DATABASE_PASSWORD`: Database password
|
||||
|
||||
## Exit Codes
|
||||
|
||||
- `0`: Success
|
||||
- `1`: Error occurred (check stderr output)
|
||||
|
||||
## Color Output
|
||||
|
||||
The tool uses ANSI colors for better readability:
|
||||
|
||||
- 🟢 Green: Success messages
|
||||
- 🔴 Red: Error messages
|
||||
- 🟡 Yellow: Warnings and prompts
|
||||
- 🔵 Cyan: Informational headers
|
||||
|
||||
## Safety Features
|
||||
|
||||
### Confirmation Prompts
|
||||
|
||||
Destructive operations require confirmation:
|
||||
- Fresh installation (overwrites database)
|
||||
- Applying migrations
|
||||
- Rolling back migrations
|
||||
|
||||
### Dry-Run Mode
|
||||
|
||||
Test operations without making changes:
|
||||
- `--dry-run` or `-n` flag
|
||||
- Available for: `migrate`, `sync-masterdata`
|
||||
|
||||
### Automatic Backups
|
||||
|
||||
Recommended workflow:
|
||||
1. `deploy backup` before any migration
|
||||
2. `deploy migrate --dry-run` to preview
|
||||
3. `deploy migrate` to apply
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Database not initialized"
|
||||
|
||||
If `deploy status` shows this error:
|
||||
|
||||
```bash
|
||||
# Fresh installation required
|
||||
./deploy install
|
||||
```
|
||||
|
||||
### "Backend Too Old"
|
||||
|
||||
Database version is newer than backend:
|
||||
|
||||
```bash
|
||||
# Upgrade backend application to latest version
|
||||
# DO NOT rollback database
|
||||
```
|
||||
|
||||
### "Migration Required"
|
||||
|
||||
Database is behind backend version:
|
||||
|
||||
```bash
|
||||
# Create backup first
|
||||
./deploy backup
|
||||
|
||||
# Apply migrations
|
||||
./deploy migrate
|
||||
```
|
||||
|
||||
### Connection Errors
|
||||
|
||||
Check environment variables and database accessibility:
|
||||
|
||||
```bash
|
||||
# Test database connection
|
||||
mysql -h $DATABASE_HOST -u $DATABASE_USER -p $DATABASE_NAME
|
||||
|
||||
# Or for SQLite
|
||||
sqlite3 $DATABASE_PATH
|
||||
```
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
### Example GitLab CI
|
||||
|
||||
```yaml
|
||||
deploy:production:
|
||||
stage: deploy
|
||||
script:
|
||||
- cd backend
|
||||
- go build -o deploy cmd/deploy/main.go
|
||||
- ./deploy status
|
||||
- ./deploy backup
|
||||
- ./deploy migrate
|
||||
only:
|
||||
- main
|
||||
environment:
|
||||
name: production
|
||||
```
|
||||
|
||||
### Example Docker
|
||||
|
||||
```dockerfile
|
||||
FROM golang:1.21
|
||||
|
||||
WORKDIR /app
|
||||
COPY backend/ .
|
||||
|
||||
RUN go build -o deploy cmd/deploy/main.go
|
||||
|
||||
ENTRYPOINT ["./deploy"]
|
||||
CMD ["status"]
|
||||
```
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
docker run bamort-deploy status
|
||||
docker run -it bamort-deploy install
|
||||
docker run bamort-deploy migrate
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
Run without building:
|
||||
|
||||
```bash
|
||||
go run cmd/deploy/main.go status
|
||||
go run cmd/deploy/main.go migrate --dry-run
|
||||
```
|
||||
|
||||
## Security Notes
|
||||
|
||||
1. **Password Input**: Uses terminal mode for secure password entry (no echo)
|
||||
2. **Backups**: Contain sensitive data - store securely
|
||||
3. **Admin User**: Create strong passwords in production
|
||||
4. **Environment Variables**: Never commit credentials to version control
|
||||
@@ -1,577 +0,0 @@
|
||||
# Deployment Runbook
|
||||
|
||||
**Version:** 1.0
|
||||
**Last Updated:** 16. Januar 2026
|
||||
**Target System:** BaMoRT
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
1. [Overview](#overview)
|
||||
2. [Pre-Deployment Checklist](#pre-deployment-checklist)
|
||||
3. [Deployment Procedures](#deployment-procedures)
|
||||
4. [Post-Deployment Validation](#post-deployment-validation)
|
||||
5. [Common Scenarios](#common-scenarios)
|
||||
6. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
### What is a Deployment?
|
||||
|
||||
A deployment updates the Bamort system with:
|
||||
- New backend code (Go)
|
||||
- New frontend code (Vue.js)
|
||||
- Database migrations (schema changes)
|
||||
- Master data updates (skills, spells, etc.)
|
||||
|
||||
### Deployment Frequency
|
||||
|
||||
- **Expected**: Once per week to once per month
|
||||
- **Duration**: 20-50 minutes including backup
|
||||
- **Downtime**: System unavailable during deployment
|
||||
|
||||
### Deployment Components
|
||||
|
||||
```
|
||||
Deployment Package Contains:
|
||||
├── Backend Binary (`deploy`)
|
||||
├── Database Migrations (SQL scripts)
|
||||
├── Master Data (JSON exports)
|
||||
├── Frontend Build (static files)
|
||||
└── Deployment Metadata (version info)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pre-Deployment Checklist
|
||||
|
||||
###Before You Start
|
||||
|
||||
- [ ] **Backup Current System**
|
||||
```bash
|
||||
docker exec bamort-backend /app/deploy backup create
|
||||
```
|
||||
|
||||
- [ ] **Verify Docker Containers Running**
|
||||
```bash
|
||||
docker ps | grep bamort
|
||||
# Should show: backend, frontend, mariadb, phpmyadmin
|
||||
```
|
||||
|
||||
- [ ] **Check Current Version**
|
||||
```bash
|
||||
docker exec bamort-backend /app/deploy status
|
||||
```
|
||||
|
||||
- [ ] **Check Disk Space**
|
||||
```bash
|
||||
df -h
|
||||
# Ensure at least 2GB free
|
||||
```
|
||||
|
||||
- [ ] **Notify Users** (if applicable)
|
||||
- Send maintenance notification
|
||||
- Set maintenance window (e.g., 22:00-23:00)
|
||||
|
||||
- [ ] **Review Changes**
|
||||
- Check `CHANGELOG.md`
|
||||
- Review migration scripts in `backend/deployment/migrations/`
|
||||
- Review new features/fixes
|
||||
|
||||
### Required Information
|
||||
|
||||
- [ ] **Current Version**: ______________
|
||||
- [ ] **Target Version**: ______________
|
||||
- [ ] **Migration Count**: ______________
|
||||
- [ ] **Deployment Package**: ______________
|
||||
- [ ] **Backup Location**: ______________
|
||||
|
||||
---
|
||||
|
||||
## Deployment Procedures
|
||||
|
||||
### Procedure 1: Standard Deployment (Update Existing System)
|
||||
|
||||
**When to Use:** Updating an existing Bamort installation
|
||||
|
||||
**Steps:**
|
||||
|
||||
#### 1. Create Pre-Deployment Backup
|
||||
|
||||
```bash
|
||||
# Create full backup
|
||||
docker exec bamort-backend /app/deploy backup create
|
||||
|
||||
# Verify backup created
|
||||
docker exec bamort-backend /app/deploy backup list
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Backup created: backup_20260116_220000_v0.4.0_m3.json
|
||||
Size: 2.4 MB
|
||||
```
|
||||
|
||||
#### 2. Stop Frontend (Prevent User Access)
|
||||
|
||||
```bash
|
||||
docker-compose -f docker/docker-compose.yml stop frontend
|
||||
```
|
||||
|
||||
**Verification:**
|
||||
```bash
|
||||
curl http://localhost:5173
|
||||
# Should fail or show "connection refused"
|
||||
```
|
||||
|
||||
#### 3. Apply Database Migrations
|
||||
|
||||
```bash
|
||||
# Check pending migrations
|
||||
docker exec bamort-backend /app/deploy migrations pending
|
||||
|
||||
# Apply all pending migrations
|
||||
docker exec bamort-backend /app/deploy migrations apply --all
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Found 2 pending migrations:
|
||||
Migration 4: Add learning_category column
|
||||
Migration 5: Create equipment_cache table
|
||||
|
||||
Applying migrations...
|
||||
✓ Migration 4 completed (executed in 450ms)
|
||||
✓ Migration 5 completed (executed in 320ms)
|
||||
|
||||
All migrations applied successfully.
|
||||
Database version: 0.4.0 → 0.5.0
|
||||
```
|
||||
|
||||
**If Errors Occur:** See [Rollback Guide](ROLLBACK_GUIDE.md)
|
||||
|
||||
#### 4. Import Master Data
|
||||
|
||||
```bash
|
||||
# Check what will be imported
|
||||
docker exec bamort-backend /app/deploy masterdata import \
|
||||
--source /app/masterdata \
|
||||
--dry-run
|
||||
|
||||
# Import master data
|
||||
docker exec bamort-backend /app/deploy masterdata import \
|
||||
--source /app/masterdata
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Importing master data from /app/masterdata...
|
||||
✓ Sources: 12 records (2 new, 10 updated)
|
||||
✓ Character Classes: 15 records (0 new, 0 updated)
|
||||
✓ Skills: 245 records (5 new, 8 updated)
|
||||
✓ Spells: 189 records (3 new, 2 updated)
|
||||
✓ Learning Costs: 1,234 records (45 new, 12 updated)
|
||||
|
||||
Master data import completed successfully.
|
||||
```
|
||||
|
||||
#### 5. Restart Backend
|
||||
|
||||
```bash
|
||||
# Pull latest backend image
|
||||
docker-compose -f docker/docker-compose.yml pull backend
|
||||
|
||||
# Restart backend
|
||||
docker-compose -f docker/docker-compose.yml restart backend
|
||||
|
||||
# Wait for backend to start (check logs)
|
||||
docker logs bamort-backend --tail=50 --follow
|
||||
# Press Ctrl+C when you see "Server started on :8180"
|
||||
```
|
||||
|
||||
#### 6. Restart Frontend
|
||||
|
||||
```bash
|
||||
# Pull latest frontend image
|
||||
docker-compose -f docker/docker-compose.yml pull frontend
|
||||
|
||||
# Start frontend
|
||||
docker-compose -f docker/docker-compose.yml start frontend
|
||||
```
|
||||
|
||||
#### 7. Verify Deployment
|
||||
|
||||
See [Post-Deployment Validation](#post-deployment-validation) section below.
|
||||
|
||||
---
|
||||
|
||||
### Procedure 2: Fresh Installation (New System)
|
||||
|
||||
**When to Use:** Setting up Bamort for the first time
|
||||
|
||||
**Steps:**
|
||||
|
||||
#### 1. Prepare Environment
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/Bardioc26/bamort.git
|
||||
cd bamort
|
||||
|
||||
# Copy environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Edit configuration
|
||||
nano .env
|
||||
# Set:
|
||||
# DATABASE_PASSWORD=<secure-password>
|
||||
# JWT_SECRET=<random-secret>
|
||||
```
|
||||
|
||||
#### 2. Start Docker Containers
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
cd docker
|
||||
./start-prd.sh
|
||||
|
||||
# Verify all containers running
|
||||
docker ps | grep bamort
|
||||
```
|
||||
|
||||
#### 3. Initialize Database
|
||||
|
||||
```bash
|
||||
# Run initialization
|
||||
docker exec bamort-backend /app/deploy init \
|
||||
--masterdata /app/masterdata \
|
||||
--create-admin \
|
||||
--admin-user admin \
|
||||
--admin-password <secure-password>
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Initializing new Bamort installation...
|
||||
Backend version: 0.5.0
|
||||
|
||||
Step 1/4: Creating database schema...
|
||||
✓ Database schema created successfully
|
||||
|
||||
Step 2/4: Initializing version tracking...
|
||||
✓ Version tracking initialized (DB version: 0.5.0)
|
||||
|
||||
Step 3/4: Importing master data...
|
||||
✓ Master data imported successfully
|
||||
|
||||
Step 4/4: Creating admin user...
|
||||
✓ Admin user 'admin' created successfully
|
||||
|
||||
═══════════════════════════════════════════
|
||||
Installation completed successfully!
|
||||
Version: 0.5.0
|
||||
Tables created: 42
|
||||
Admin created: Yes
|
||||
Master data: Imported
|
||||
Execution time: 8.5s
|
||||
═══════════════════════════════════════════
|
||||
```
|
||||
|
||||
#### 4. Verify Installation
|
||||
|
||||
```bash
|
||||
# Check system health
|
||||
curl http://localhost:8180/api/system/health | jq
|
||||
|
||||
# Access frontend
|
||||
open http://localhost:5173
|
||||
|
||||
# Login with admin credentials
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Procedure 3: Rollback Deployment
|
||||
|
||||
See [ROLLBACK_GUIDE.md](ROLLBACK_GUIDE.md) for detailed rollback procedures.
|
||||
|
||||
---
|
||||
|
||||
## Post-Deployment Validation
|
||||
|
||||
### Automated Checks
|
||||
|
||||
Run the validation script:
|
||||
|
||||
```bash
|
||||
docker exec bamort-backend /app/deploy validate
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Running post-deployment validation...
|
||||
|
||||
Database Checks:
|
||||
✓ All expected tables exist
|
||||
✓ All expected columns exist
|
||||
✓ No orphaned tables
|
||||
✓ Foreign key constraints valid
|
||||
✓ Indexes created
|
||||
|
||||
Version Checks:
|
||||
✓ Backend version: 0.5.0
|
||||
✓ Database version: 0.5.0
|
||||
✓ Versions compatible
|
||||
|
||||
Data Integrity:
|
||||
✓ Master data tables populated
|
||||
✓ Sources: 12 records
|
||||
✓ Skills: 245 records
|
||||
✓ Spells: 189 records
|
||||
|
||||
All validation checks passed ✓
|
||||
```
|
||||
|
||||
### Manual Verification
|
||||
|
||||
#### 1. Check System Health
|
||||
|
||||
```bash
|
||||
curl http://localhost:8180/api/system/health | jq
|
||||
```
|
||||
|
||||
**Expected:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"backend_version": "0.5.0",
|
||||
"required_db_version": "0.5.0",
|
||||
"actual_db_version": "0.5.0",
|
||||
"migrations_pending": false,
|
||||
"compatible": true,
|
||||
"timestamp": "2026-01-16T22:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Check Frontend
|
||||
|
||||
- [ ] Open http://localhost:5173
|
||||
- [ ] No warning banner displayed
|
||||
- [ ] Login works
|
||||
- [ ] Dashboard loads
|
||||
- [ ] Character list loads
|
||||
- [ ] Can view character details
|
||||
|
||||
#### 3. Check Backend Logs
|
||||
|
||||
```bash
|
||||
docker logs bamort-backend --tail=100
|
||||
```
|
||||
|
||||
**Look for:**
|
||||
- [ ] No ERROR messages
|
||||
- [ ] Server started successfully
|
||||
- [ ] Database connection OK
|
||||
- [ ] No migration errors
|
||||
|
||||
#### 4. Test Core Functionality
|
||||
|
||||
- [ ] **Create Character**: Can create new character
|
||||
- [ ] **Edit Character**: Can edit existing character
|
||||
- [ ] **Skills**: Skills load and display correctly
|
||||
- [ ] **Spells**: Spells load and display correctly
|
||||
- [ ] **Learning Costs**: Learning cost calculations work
|
||||
- [ ] **Export**: Can export character to PDF
|
||||
|
||||
#### 5. Check Database
|
||||
|
||||
```bash
|
||||
# Connect to database
|
||||
docker exec -it bamort-mariadb mysql -u bamort -p bamort
|
||||
|
||||
# Check version
|
||||
SELECT * FROM schema_version ORDER BY id DESC LIMIT 1;
|
||||
|
||||
# Check migration history
|
||||
SELECT * FROM migration_history ORDER BY migration_number DESC LIMIT 5;
|
||||
|
||||
# Exit
|
||||
exit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: Minor Update (No Migrations)
|
||||
|
||||
When deployment only updates code without database changes:
|
||||
|
||||
```bash
|
||||
# No migrations needed, just restart services
|
||||
docker-compose -f docker/docker-compose.yml pull
|
||||
docker-compose -f docker/docker-compose.yml restart
|
||||
```
|
||||
|
||||
### Scenario 2: Major Update (Multiple Migrations)
|
||||
|
||||
When deployment includes 5+ migrations:
|
||||
|
||||
```bash
|
||||
# Create backup first
|
||||
docker exec bamort-backend /app/deploy backup create
|
||||
|
||||
# Apply migrations with verbose output
|
||||
docker exec bamort-backend /app/deploy migrations apply --all --verbose
|
||||
|
||||
# Verify each migration
|
||||
docker exec bamort-backend /app/deploy migrations history
|
||||
```
|
||||
|
||||
### Scenario 3: Hotfix Deployment
|
||||
|
||||
Emergency fix during business hours:
|
||||
|
||||
```bash
|
||||
# 1. Create backup (fast JSON backup)
|
||||
docker exec bamort-backend /app/deploy backup create
|
||||
|
||||
# 2. Pull latest code
|
||||
docker-compose -f docker/docker-compose.yml pull backend
|
||||
|
||||
# 3. Restart backend only
|
||||
docker-compose -f docker/docker-compose.yml restart backend
|
||||
|
||||
# 4. Monitor logs
|
||||
docker logs bamort-backend --tail=100 --follow
|
||||
|
||||
# 5. Verify health endpoint
|
||||
curl http://localhost:8180/api/system/health
|
||||
```
|
||||
|
||||
### Scenario 4: Master Data Update Only
|
||||
|
||||
When only updating skills/spells/costs:
|
||||
|
||||
```bash
|
||||
# Import new master data (dev exports to production)
|
||||
docker cp ./masterdata bamort-backend:/tmp/masterdata
|
||||
docker exec bamort-backend /app/deploy masterdata import \
|
||||
--source /tmp/masterdata
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Migration Fails
|
||||
|
||||
**Symptom:** Migration error during `migrations apply`
|
||||
|
||||
**Solution:**
|
||||
1. Check error message in logs
|
||||
2. If safe, rollback last migration:
|
||||
```bash
|
||||
docker exec bamort-backend /app/deploy migrations rollback --steps 1
|
||||
```
|
||||
3. Fix migration script if needed
|
||||
4. Re-apply migration
|
||||
|
||||
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions.
|
||||
|
||||
### Issue: Frontend Shows Warning Banner
|
||||
|
||||
**Symptom:** Yellow warning banner: "Database migration required"
|
||||
|
||||
**Cause:** Database version doesn't match backend version
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check versions
|
||||
docker exec bamort-backend /app/deploy status
|
||||
|
||||
# Apply pending migrations
|
||||
docker exec bamort-backend /app/deploy migrations apply --all
|
||||
```
|
||||
|
||||
### Issue: Backend Won't Start
|
||||
|
||||
**Symptom:** Backend container crashes or restarts repeatedly
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check logs
|
||||
docker logs bamort-backend --tail=100
|
||||
|
||||
# Common causes:
|
||||
# - Database connection failed → Check DATABASE_PASSWORD in .env
|
||||
# - Migration failed → Rollback to previous version
|
||||
# - Port conflict → Check if port 8180 is available
|
||||
```
|
||||
|
||||
### Issue: Cannot Access Frontend
|
||||
|
||||
**Symptom:** http://localhost:5173 not reachable
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check frontend container
|
||||
docker ps | grep frontend
|
||||
|
||||
# If not running, start it
|
||||
docker-compose -f docker/docker-compose.yml start frontend
|
||||
|
||||
# Check frontend logs
|
||||
docker logs bamort-frontend --tail=50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Timeline
|
||||
|
||||
Typical deployment timeline:
|
||||
|
||||
| Step | Duration | Description |
|
||||
|------|----------|-------------|
|
||||
| 1. Backup | 2-5 min | Create database backup |
|
||||
| 2. Stop Frontend | 10 sec | Prevent user access |
|
||||
| 3. Migrations | 5-15 min | Apply database changes |
|
||||
| 4. Master Data | 3-8 min | Import updated data |
|
||||
| 5. Restart Backend | 1-2 min | Load new code |
|
||||
| 6. Restart Frontend | 30 sec | Load new UI |
|
||||
| 7. Validation | 5-10 min | Verify deployment |
|
||||
| **Total** | **20-45 min** | Complete deployment |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful deployment:
|
||||
|
||||
1. **Monitor System** for 24 hours
|
||||
- Check error logs daily
|
||||
- Monitor system health endpoint
|
||||
- Watch for user-reported issues
|
||||
|
||||
2. **Update Documentation**
|
||||
- Update `CHANGELOG.md`
|
||||
- Document any manual changes
|
||||
- Update version in README
|
||||
|
||||
3. **Cleanup Old Backups**
|
||||
```bash
|
||||
docker exec bamort-backend /app/deploy backup cleanup --keep 30
|
||||
```
|
||||
|
||||
4. **Notify Users**
|
||||
- Send "System Updated" notification
|
||||
- Highlight new features
|
||||
- Mention any breaking changes
|
||||
|
||||
---
|
||||
|
||||
**For Emergency Rollback:** See [ROLLBACK_GUIDE.md](ROLLBACK_GUIDE.md)
|
||||
**For Common Issues:** See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||
**For Version Info:** See [VERSION_COMPATIBILITY.md](VERSION_COMPATIBILITY.md)
|
||||
@@ -1,314 +0,0 @@
|
||||
# Maintenance SkillView Enhancement - Implementation Summary
|
||||
|
||||
## Overview
|
||||
Enhanced the maintenance SkillView to support multiple categories and difficulties per skill, with improved filtering and editing capabilities.
|
||||
|
||||
## Changes Implemented
|
||||
|
||||
### 1. Data Model Enhancement
|
||||
|
||||
#### Backend (`backend/models/`)
|
||||
- Leveraged existing `SkillCategoryDifficulty` table to support many-to-many relationship between skills, categories, and difficulties
|
||||
- No schema changes needed - the relational structure was already in place
|
||||
- Created migration utility to populate relationships from legacy single-field data
|
||||
|
||||
#### Migration Utility (`backend/maintenance/skill_migration.go`)
|
||||
- `MigrateSkillCategoriesToRelations()` - Main migration function
|
||||
- Converts old `Category` and `Difficulty` string fields to relational `SkillCategoryDifficulty` records
|
||||
- Handles missing categories/difficulties by creating defaults
|
||||
- Idempotent - can be run multiple times safely
|
||||
- Tests: `backend/maintenance/skill_migration_test.go`
|
||||
|
||||
### 2. Backend API Enhancements
|
||||
|
||||
#### New Handlers (`backend/gsmaster/skill_enhanced_handlers.go`)
|
||||
Created three new endpoints for enhanced skill management:
|
||||
|
||||
1. **GET `/api/maintenance/skills-enhanced`**
|
||||
- Returns all skills with their categories and difficulties
|
||||
- Includes available sources, categories, and difficulties for dropdowns
|
||||
- Response structure:
|
||||
```json
|
||||
{
|
||||
"skills": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Schwimmen",
|
||||
"categories": [
|
||||
{
|
||||
"category_id": 5,
|
||||
"category_name": "Körper",
|
||||
"difficulty_id": 2,
|
||||
"difficulty_name": "leicht",
|
||||
"learn_cost": 5
|
||||
}
|
||||
],
|
||||
"difficulties": ["leicht"],
|
||||
...
|
||||
}
|
||||
],
|
||||
"sources": [...],
|
||||
"categories": [...],
|
||||
"difficulties": [...]
|
||||
}
|
||||
```
|
||||
|
||||
2. **GET `/api/maintenance/skills-enhanced/:id`**
|
||||
- Returns single skill with full category/difficulty details
|
||||
|
||||
3. **PUT `/api/maintenance/skills-enhanced/:id`**
|
||||
- Updates skill with multiple categories and their difficulties
|
||||
- Request body:
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Schwimmen",
|
||||
"initialwert": 12,
|
||||
"improvable": true,
|
||||
"innateskill": false,
|
||||
"bonuseigenschaft": "Gw",
|
||||
"beschreibung": "...",
|
||||
"source_id": 5,
|
||||
"page_number": 42,
|
||||
"category_difficulties": [
|
||||
{
|
||||
"category_id": 5,
|
||||
"difficulty_id": 2,
|
||||
"learn_cost": 5
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Helper Functions
|
||||
- `GetSkillWithCategories()` - Retrieves skill with all relationships
|
||||
- `GetAllSkillsWithCategories()` - Retrieves all skills with relationships
|
||||
- `UpdateSkillWithCategories()` - Transactional update of skill and relationships
|
||||
|
||||
#### Tests (`backend/gsmaster/skill_enhanced_handlers_test.go`)
|
||||
- `TestGetSkillWithCategories` - Single skill retrieval
|
||||
- `TestGetSkillWithCategories_MultipleCategories` - Multiple categories per skill
|
||||
- `TestUpdateSkillWithCategories` - Update with category changes
|
||||
- All tests passing ✅
|
||||
|
||||
#### Routes (`backend/gsmaster/routes.go`)
|
||||
Added new enhanced endpoints alongside existing ones for backward compatibility.
|
||||
|
||||
### 3. Frontend Enhancements
|
||||
|
||||
#### Updated SkillView (`frontend/src/components/maintenance/SkillView.vue`)
|
||||
|
||||
**Display Mode Changes:**
|
||||
- **category**: Now shows comma-separated list of all categories (e.g., "Körper, Bewegung")
|
||||
- **difficulty**: Shows comma-separated list of difficulties matching category order (e.g., "leicht, normal")
|
||||
- **improvable**: Displays as disabled checkbox (✓/✗)
|
||||
- **innateskill**: Displays as disabled checkbox (✓/✗)
|
||||
- **quelle**: Shows as "CODE:page" format (e.g., "KOD:42")
|
||||
|
||||
**Edit Mode Changes:**
|
||||
- **bonuseigenschaft**: Select dropdown with options: St, Gs, Gw, Ko, In, Zt, Au, pA, Wk, B
|
||||
- **quelle**: Split into two fields:
|
||||
- Select dropdown for source code
|
||||
- Numeric input for page number
|
||||
- **categories**: Checkboxes for all available categories
|
||||
- **difficulties**: Dynamic difficulty selects - one per checked category
|
||||
|
||||
**New Filtering System:**
|
||||
- Filter by Category (dropdown)
|
||||
- Filter by Difficulty (dropdown)
|
||||
- Filter by Improvable (Yes/No/All)
|
||||
- Filter by Innateskill (Yes/No/All)
|
||||
- "Clear Filters" button to reset all filters
|
||||
- Filters work in combination with search
|
||||
|
||||
**Data Flow:**
|
||||
1. Component loads enhanced skills via new API endpoint
|
||||
2. Displays categories/difficulties as comma-separated lists
|
||||
3. On edit, converts to checkboxes and per-category difficulty selects
|
||||
4. On save, constructs `category_difficulties` array and sends to API
|
||||
|
||||
#### Styling (`frontend/src/assets/main.css`)
|
||||
Added comprehensive styles for:
|
||||
- Filter row with responsive layout
|
||||
- Edit form with structured rows and fields
|
||||
- Category checkboxes with scrollable container
|
||||
- Difficulty selects with category labels
|
||||
- Action buttons with proper colors
|
||||
- Mobile-responsive adjustments
|
||||
|
||||
## Key Features
|
||||
|
||||
### Multi-Category Support
|
||||
- Skills can belong to multiple categories
|
||||
- Each category can have its own difficulty
|
||||
- Example: "Reiten" can be in both "Bewegung" (normal) and "Reiten" (schwer)
|
||||
|
||||
### Enhanced Filtering
|
||||
- Excel-like column filtering
|
||||
- Multiple filter criteria work together
|
||||
- Filters persist during editing
|
||||
- Quick "Clear All" option
|
||||
|
||||
### Improved Edit Experience
|
||||
- Visual category checkboxes instead of dropdown
|
||||
- Automatic difficulty assignment per category
|
||||
- Split source/page fields for better UX
|
||||
- Proper attribute dropdown for bonuseigenschaft
|
||||
|
||||
### Data Integrity
|
||||
- Transactional updates ensure consistency
|
||||
- Validation on both frontend and backend
|
||||
- Migrationutility maintains data during structure changes
|
||||
- Backward compatibility with existing endpoints
|
||||
|
||||
## Testing Status
|
||||
|
||||
### Backend Tests ✅
|
||||
All tests passing:
|
||||
```bash
|
||||
cd /data/dev/bamort/backend
|
||||
go test -v ./maintenance/ -run TestMigrate # Migration tests
|
||||
go test -v ./gsmaster/ -run "TestGetSkill|TestUpdate" # Handler tests
|
||||
```
|
||||
|
||||
### Build Status ✅
|
||||
Backend compiles successfully:
|
||||
```bash
|
||||
cd /data/dev/bamort/backend
|
||||
go build -o /tmp/test-bamort ./cmd/main.go
|
||||
```
|
||||
|
||||
### Docker Status ✅
|
||||
All containers running:
|
||||
- bamort-backend-dev (port 8180)
|
||||
- bamort-frontend-dev (port 5173)
|
||||
- bamort-mariadb-dev
|
||||
- bamort-phpmyadmin-dev (port 8081)
|
||||
|
||||
## Migration Instructions
|
||||
|
||||
### Running the Migration
|
||||
To populate the `learning_skill_category_difficulties` table from existing data:
|
||||
|
||||
```go
|
||||
// In backend/maintenance/handlers.go or via admin endpoint
|
||||
import "bamort/maintenance"
|
||||
|
||||
func MigrateSkillData(c *gin.Context) {
|
||||
if err := maintenance.MigrateSkillCategoriesToRelations(database.DB); err != nil {
|
||||
c.JSON(500, gin.H{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
c.JSON(200, gin.H{"message": "Migration completed successfully"})
|
||||
}
|
||||
```
|
||||
|
||||
Or add to routes:
|
||||
```go
|
||||
// In backend/maintenance/routes.go
|
||||
maintGrp.POST("/migrate-skills", MigrateSkillData)
|
||||
```
|
||||
|
||||
Then call:
|
||||
```bash
|
||||
curl -X POST http://localhost:8180/api/maintenance/migrate-skills \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
## Files Modified/Created
|
||||
|
||||
### Backend
|
||||
- ✅ `backend/maintenance/skill_migration.go` (new)
|
||||
- ✅ `backend/maintenance/skill_migration_test.go` (new)
|
||||
- ✅ `backend/gsmaster/skill_enhanced_handlers.go` (new)
|
||||
- ✅ `backend/gsmaster/skill_enhanced_handlers_test.go` (new)
|
||||
- ✅ `backend/gsmaster/routes.go` (modified - added enhanced endpoints)
|
||||
|
||||
### Frontend
|
||||
- ✅ `frontend/src/components/maintenance/SkillView.vue` (replaced)
|
||||
- ✅ `frontend/src/assets/main.css` (appended styles)
|
||||
|
||||
### Backup
|
||||
- `frontend/src/components/maintenance/SkillView.vue.bak` (original)
|
||||
|
||||
## Best Practices Followed
|
||||
|
||||
### Backend (Go)
|
||||
- ✅ TDD - Tests written before implementation
|
||||
- ✅ KISS - Simple, straightforward solutions
|
||||
- ✅ Single Responsibility - Each function has clear purpose
|
||||
- ✅ Error Handling - Proper error propagation and logging
|
||||
- ✅ Transactions - Database consistency maintained
|
||||
- ✅ Idempotent migrations - Safe to run multiple times
|
||||
|
||||
### Frontend (Vue 3)
|
||||
- ✅ Options API - Consistent with existing codebase
|
||||
- ✅ Computed properties for filtering/sorting
|
||||
- ✅ No inline styles - All CSS in main.css
|
||||
- ✅ Proper API usage - Using utils/api.js with interceptors
|
||||
- ✅ Responsive design - Mobile-friendly layouts
|
||||
- ✅ User feedback - Loading states and error messages
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Potential Improvements
|
||||
1. Add batch edit capability for multiple skills
|
||||
2. Export/import skill definitions with categories
|
||||
3. Duplicate skill detection
|
||||
4. Category usage statistics
|
||||
5. Difficulty distribution visualization
|
||||
6. Undo/redo for edits
|
||||
7. Bulk category assignment
|
||||
|
||||
### Performance Optimizations
|
||||
1. Pagination for large skill lists
|
||||
2. Virtual scrolling for category checkboxes
|
||||
3. Debounced filter updates
|
||||
4. Cached category/difficulty lookups
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Frontend Not Loading Enhanced Skills
|
||||
Check browser console for errors. Verify:
|
||||
```javascript
|
||||
// In browser DevTools Console
|
||||
fetch('http://localhost:8180/api/maintenance/skills-enhanced', {
|
||||
headers: { 'Authorization': 'Bearer ' + localStorage.getItem('token') }
|
||||
})
|
||||
.then(r => r.json())
|
||||
.then(console.log)
|
||||
```
|
||||
|
||||
### Backend Tests Failing
|
||||
Ensure test database is prepared:
|
||||
```bash
|
||||
cd /data/dev/bamort/backend
|
||||
# Check if testdata directory exists
|
||||
ls -la ./testdata/
|
||||
```
|
||||
|
||||
### Migration Issues
|
||||
Check database state:
|
||||
```sql
|
||||
-- Count existing relationships
|
||||
SELECT COUNT(*) FROM learning_skill_category_difficulties;
|
||||
|
||||
-- Check for skills without relationships
|
||||
SELECT s.id, s.name, s.category, s.difficulty
|
||||
FROM gsm_skills s
|
||||
LEFT JOIN learning_skill_category_difficulties scd ON s.id = scd.skill_id
|
||||
WHERE scd.id IS NULL AND s.category IS NOT NULL;
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
Successfully enhanced the maintenance SkillView with:
|
||||
- ✅ Multi-category/difficulty support
|
||||
- ✅ Advanced filtering capabilities
|
||||
- ✅ Improved edit interface
|
||||
- ✅ Data migration utility
|
||||
- ✅ Comprehensive tests
|
||||
- ✅ Following TDD and KISS principles
|
||||
- ✅ Responsive design
|
||||
- ✅ Backward compatibility
|
||||
|
||||
All requirements met and tested. Ready for integration and deployment.
|
||||
@@ -0,0 +1,564 @@
|
||||
# BaMoRT Deployment Guide
|
||||
|
||||
This directory contains the deployment tool for BaMoRT. This guide explains the complete deployment workflow from preparing a new release to deploying it on the target system.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Deployment Tool Commands](#deployment-tool-commands)
|
||||
- [Pre-Deployment Checklist](#pre-deployment-checklist)
|
||||
- [Step-by-Step Deployment Process](#step-by-step-deployment-process)
|
||||
- [1. Development System: Prepare Release](#1-development-system-prepare-release)
|
||||
- [2. Development System: Version Management](#2-development-system-version-management)
|
||||
- [3. Development System: Create Deployment Package](#3-development-system-create-deployment-package)
|
||||
- [4. Git: Commit and Tag](#4-git-commit-and-tag)
|
||||
- [5. Target System: Pre-Deployment](#5-target-system-pre-deployment)
|
||||
- [6. Target System: Deployment](#6-target-system-deployment)
|
||||
- [7. Target System: Post-Deployment](#7-target-system-post-deployment)
|
||||
- [Rollback Procedure](#rollback-procedure)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Overview
|
||||
|
||||
The BaMoRT deployment process uses a multi-phase approach:
|
||||
|
||||
1. **Version Update**: Set new version numbers across the codebase
|
||||
2. **Package Preparation**: Export master data and system configurations
|
||||
3. **Git Management**: Commit, tag, and push to repository
|
||||
4. **Target Deployment**: Pull code, migrate database, import data, restart services
|
||||
5. **Validation**: Verify database schema, service health, and data integrity
|
||||
|
||||
The deployment tool (`backend/cmd/deploy/main.go`) provides several commands to manage this process safely.
|
||||
|
||||
## Deployment Tool Commands
|
||||
|
||||
Build the deployment tool first:
|
||||
|
||||
```bash
|
||||
export BASEDIR=PWD
|
||||
cd ./backend
|
||||
go build -o deploy cmd/deploy/main.go
|
||||
```
|
||||
|
||||
Available commands:
|
||||
|
||||
| Command | Description | Usage |
|
||||
|---------|-------------|-------|
|
||||
| `version` | Show version information | `./deploy version` |
|
||||
| `status` | Show current DB version and pending migrations | `./deploy status` |
|
||||
| `prepare` | Create deployment package with master data | `./deploy prepare [export_dir]` |
|
||||
| `deploy` | Run full deployment (backup → migrate → validate) | `./deploy deploy` |
|
||||
| `validate` | Validate database schema and data integrity | `./deploy validate` |
|
||||
| `help` | Show help message | `./deploy help` |
|
||||
|
||||
## Pre-Deployment Checklist
|
||||
|
||||
Before starting a deployment, ensure:
|
||||
|
||||
- [ ] All features are tested locally
|
||||
- [ ] All tests pass: `cd backend && go test ./...`
|
||||
- [ ] Frontend builds without errors
|
||||
- [ ] Database migrations are tested locally
|
||||
- [ ] Breaking changes are documented
|
||||
- [ ] You have access to the target system
|
||||
- [ ] Target system has sufficient disk space (>2GB free) mostly for docker images
|
||||
- [ ] Docker is running on target system
|
||||
- [ ] You know the new version number (semantic versioning: MAJOR.MINOR.PATCH)
|
||||
|
||||
## Step-by-Step Deployment Process
|
||||
|
||||
### 1. Development System: Prepare Release
|
||||
|
||||
Ensure your development environment is clean and up-to-date:
|
||||
|
||||
```bash
|
||||
# Navigate to project root
|
||||
cd $BASEDIR
|
||||
|
||||
# Ensure you're on the main branch
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# Verify all changes are committed
|
||||
git status
|
||||
|
||||
# Run tests
|
||||
cd backend && go test ./...
|
||||
cd ../frontend && npm run test
|
||||
```
|
||||
|
||||
### 2. Development System: Version Management
|
||||
|
||||
Update the version number across all components using the automated script:
|
||||
|
||||
```bash
|
||||
cd $BASEDIR
|
||||
|
||||
# Update both backend and frontend to same version
|
||||
./scripts/update-version.sh 0.1.38
|
||||
|
||||
# Or update to different versions
|
||||
./scripts/update-version.sh 0.1.38 0.2.0
|
||||
|
||||
# Or use auto-commit mode (sets version AND commits)
|
||||
./scripts/update-version.sh 0.1.38 auto
|
||||
```
|
||||
|
||||
This script updates:
|
||||
- `backend/config/version.go` - Backend application version
|
||||
- `frontend/src/version.js` - Frontend application version
|
||||
- `frontend/package.json` - NPM package version
|
||||
- `backend/VERSION.md` - Backend version documentation
|
||||
- `frontend/VERSION.md` - Frontend version documentation
|
||||
|
||||
**Manual version update** (if not using script):
|
||||
|
||||
Edit `backend/config/version.go`:
|
||||
```go
|
||||
const Version = "0.1.38"
|
||||
```
|
||||
|
||||
Edit `frontend/src/version.js`:
|
||||
```js
|
||||
export const VERSION = '0.1.38'
|
||||
```
|
||||
|
||||
Edit `frontend/package.json`:
|
||||
```json
|
||||
{
|
||||
"version": "0.1.38"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Development System: Create Deployment Package
|
||||
|
||||
Create a deployment package containing all master data and system configurations:
|
||||
|
||||
```bash
|
||||
cd ./backend
|
||||
|
||||
# Build the deployment tool
|
||||
go build -o deploy cmd/deploy/main.go
|
||||
|
||||
# Check current database status
|
||||
./deploy status
|
||||
|
||||
# Create deployment package (exports to ./export_temp by default)
|
||||
./deploy prepare
|
||||
|
||||
# Or specify custom export directory
|
||||
./deploy prepare /path/to/export_dir
|
||||
```
|
||||
|
||||
The deployment package includes:
|
||||
- Master data (skills, spells, equipment definitions, etc.)
|
||||
- System configurations
|
||||
- Database structure metadata
|
||||
- Version information
|
||||
|
||||
**Important**: The deployment package does NOT include user data (characters, user accounts). User data remains on the target system and is migrated during deployment.
|
||||
|
||||
Package location: `backend/export_temp/`
|
||||
|
||||
### 4. Git: Commit and Tag
|
||||
|
||||
Commit all version changes and create a git tag:
|
||||
|
||||
```bash
|
||||
cd $BASEDIR
|
||||
|
||||
# If using auto-commit mode, skip this section
|
||||
# Otherwise, commit manually:
|
||||
|
||||
# Add version files
|
||||
git add backend/config/version.go
|
||||
git add frontend/src/version.js
|
||||
git add frontend/package.json
|
||||
git add backend/VERSION.md
|
||||
git add frontend/VERSION.md
|
||||
|
||||
# Commit with descriptive message
|
||||
git commit -m "Bump version to 0.1.38"
|
||||
|
||||
# Create annotated tag
|
||||
git tag -a v0.1.38 -m "Release version 0.1.38
|
||||
|
||||
Features:
|
||||
- Feature 1 description
|
||||
- Feature 2 description
|
||||
|
||||
Bug Fixes:
|
||||
- Fix 1 description
|
||||
- Fix 2 description
|
||||
|
||||
Breaking Changes:
|
||||
- None (or list breaking changes)
|
||||
"
|
||||
|
||||
# Push commits and tags
|
||||
git push origin main
|
||||
git push origin v0.1.38
|
||||
```
|
||||
|
||||
**Tag naming convention**:
|
||||
- Standard release: `v0.1.38`
|
||||
- Backend-specific: `backend-v0.1.38` (if versioned separately)
|
||||
- Frontend-specific: `frontend-v0.1.38` (if versioned separately)
|
||||
|
||||
### 5. Target System: Pre-Deployment
|
||||
|
||||
SSH into the target system and prepare for deployment:
|
||||
|
||||
```bash
|
||||
# SSH to production server
|
||||
ssh user@production-server
|
||||
|
||||
# Navigate to project directory
|
||||
cd $BASEDIR # Or production install location
|
||||
|
||||
# Check Docker status
|
||||
docker ps
|
||||
|
||||
# Check disk space (need >2GB free)
|
||||
df -h .
|
||||
|
||||
# Check current running version
|
||||
curl http://localhost:8182/api/system/health | jq .
|
||||
|
||||
# Verify database connectivity
|
||||
docker exec bamort-backend /app/deploy status
|
||||
```
|
||||
|
||||
**Pre-deployment checks**:
|
||||
- [ ] All services are running (`docker ps`)
|
||||
- [ ] Sufficient disk space available (`df -h`)
|
||||
- [ ] Database is accessible
|
||||
- [ ] No pending migrations or issues
|
||||
|
||||
### 6. Target System: Deployment
|
||||
|
||||
Run the deployment script on the target system:
|
||||
|
||||
```bash
|
||||
cd $BASEDIR
|
||||
|
||||
# Option 1: Deploy without deployment package (code + migrations only)
|
||||
./scripts/deploy-production.sh v0.1.38
|
||||
|
||||
# Option 2: Deploy with deployment package (code + migrations + master data)
|
||||
./scripts/deploy-production.sh v0.1.38 deployment_package_0.1.38.tar.gz
|
||||
```
|
||||
|
||||
**Deployment will prompt for confirmation**:
|
||||
```
|
||||
⚠️ WARNING: This will deploy to PRODUCTION
|
||||
Type 'DEPLOY' to continue:
|
||||
```
|
||||
|
||||
**The script performs these steps automatically**:
|
||||
|
||||
1. **Pre-flight checks**
|
||||
- Verify disk space (minimum 2GB required)
|
||||
- Verify Docker is running
|
||||
- Verify MariaDB is accessible
|
||||
|
||||
2. **Backup current database**
|
||||
- Creates timestamped backup in `backups/` directory
|
||||
- Format: `pre-deploy-v0.1.38-20260117-143022.sql`
|
||||
- Aborts deployment if backup fails
|
||||
|
||||
3. **Checkout version**
|
||||
- Fetches from git origin
|
||||
- Checks out the specified tag (e.g., `v0.1.38`)
|
||||
|
||||
4. **Build Docker images**
|
||||
- Builds new backend and frontend containers
|
||||
- Uses production Dockerfiles
|
||||
|
||||
5. **Stop frontend**
|
||||
- Stops frontend container to prevent user access during migration
|
||||
- Backend remains running
|
||||
|
||||
6. **Run database migrations**
|
||||
- Executes pending database migrations
|
||||
- Automatically rolls back on migration failure
|
||||
- Restores backup if rollback occurs
|
||||
|
||||
7. **Import master data** (if deployment package provided)
|
||||
- Extracts deployment package
|
||||
- Copies master data to backend container
|
||||
- Imports system data (skills, spells, equipment, etc.)
|
||||
|
||||
8. **Restart backend**
|
||||
- Restarts backend container with new code
|
||||
- Ensures clean state
|
||||
|
||||
9. **Health checks**
|
||||
- Waits for backend to start (max 120 seconds)
|
||||
- Verifies API endpoint responds
|
||||
- Checks version compatibility
|
||||
- Validates database schema
|
||||
|
||||
10. **Start frontend**
|
||||
- Starts frontend container
|
||||
- Verifies frontend accessibility
|
||||
|
||||
11. **Final validation**
|
||||
- Verifies all services are running
|
||||
- Reports deployment status
|
||||
|
||||
**Deployment log**: Saved to `logs/deploy-YYYYMMDD-HHMMSS.log`
|
||||
|
||||
### 7. Target System: Post-Deployment
|
||||
|
||||
After successful deployment, perform these validation steps:
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
docker ps
|
||||
|
||||
# View logs
|
||||
docker logs bamort-backend --tail=100
|
||||
docker logs bamort-frontend --tail=100
|
||||
|
||||
# Check system health
|
||||
curl http://localhost:8182/api/system/health | jq .
|
||||
|
||||
# Verify database version
|
||||
docker exec bamort-backend /app/deploy status
|
||||
|
||||
# Validate database schema
|
||||
docker exec bamort-backend /app/deploy validate
|
||||
```
|
||||
|
||||
**Manual Testing**:
|
||||
1. Open the application in a browser
|
||||
2. Login with test account
|
||||
3. Navigate through main features
|
||||
4. Create/edit a character
|
||||
5. Generate a PDF export
|
||||
6. Check responsive behavior on mobile
|
||||
|
||||
|
||||
## Rollback Procedure
|
||||
|
||||
If deployment fails or critical issues are discovered:
|
||||
|
||||
### Automatic Rollback
|
||||
|
||||
The deployment script automatically rolls back if:
|
||||
- Database backup fails
|
||||
- Git checkout fails
|
||||
- Docker build fails
|
||||
- Database migration fails
|
||||
- Backend fails to start within 60 seconds
|
||||
- Version incompatibility detected
|
||||
|
||||
Automatic rollback performs:
|
||||
1. Stops all containers
|
||||
2. Checks out previous version (main branch)
|
||||
3. Restarts containers
|
||||
4. Displays rollback instructions for database
|
||||
|
||||
### Manual Rollback
|
||||
|
||||
If you need to rollback manually:
|
||||
|
||||
```bash
|
||||
cd $BASEDIR
|
||||
|
||||
# Stop all services
|
||||
docker-compose -f docker/docker-compose.yml down
|
||||
|
||||
# Restore database backup
|
||||
BACKUP_FILE="backups/pre-deploy-v0.1.38-20260117-143022.sql"
|
||||
cat "$BACKUP_FILE" | docker exec -i bamort-mariadb mysql -u bamort -p bamort
|
||||
|
||||
# Checkout previous version
|
||||
git checkout v0.1.37 # Or main branch
|
||||
|
||||
# Rebuild and restart services
|
||||
docker-compose -f docker/docker-compose.yml build
|
||||
docker-compose -f docker/docker-compose.yml up -d
|
||||
|
||||
# Verify services
|
||||
docker ps
|
||||
curl http://localhost:8182/api/system/health | jq .
|
||||
```
|
||||
|
||||
### Post-Rollback
|
||||
|
||||
After rollback:
|
||||
1. Identify root cause of deployment failure
|
||||
2. Fix issues in development environment
|
||||
3. Test thoroughly
|
||||
4. Increment version number
|
||||
5. Retry deployment process
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: Version mismatch after deployment
|
||||
|
||||
**Symptoms**: Health check shows `"compatible": false`
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check versions
|
||||
docker exec bamort-backend /app/deploy status
|
||||
|
||||
# Check for pending migrations
|
||||
docker exec bamort-backend /app/deploy validate
|
||||
|
||||
# Run migrations manually if needed
|
||||
docker exec bamort-backend /app/deploy deploy
|
||||
```
|
||||
|
||||
### Problem: Backend won't start
|
||||
|
||||
**Symptoms**: Backend container exits immediately
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check logs
|
||||
docker logs bamort-backend
|
||||
|
||||
# Common causes:
|
||||
# 1. Database connection issues - check DATABASE_URL env var
|
||||
# 2. Missing environment variables - check .env file
|
||||
# 3. Port conflicts - check if port 8180 is in use
|
||||
|
||||
# Check database connectivity
|
||||
docker exec bamort-backend sh -c 'nc -zv mariadb 3306'
|
||||
```
|
||||
|
||||
### Problem: Frontend shows old version
|
||||
|
||||
**Symptoms**: UI displays previous version number
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Clear browser cache
|
||||
# Or force reload: Ctrl+Shift+R (Linux/Windows) or Cmd+Shift+R (Mac)
|
||||
|
||||
# Rebuild frontend container
|
||||
docker-compose -f docker/docker-compose.yml build frontend
|
||||
docker-compose -f docker/docker-compose.yml up -d frontend
|
||||
```
|
||||
|
||||
### Problem: Migration fails
|
||||
|
||||
**Symptoms**: Migration error during deployment
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check migration status
|
||||
docker exec bamort-backend /app/deploy status
|
||||
|
||||
# Check specific migration file
|
||||
# Migrations located in: backend/deployment/migrations/
|
||||
|
||||
# Test migration locally first
|
||||
cd $BASEDIR/backend
|
||||
DATABASE_TYPE=sqlite ./deploy deploy
|
||||
|
||||
# Fix migration code if needed
|
||||
# Rollback production deployment
|
||||
# Test fixed migration locally
|
||||
# Redeploy
|
||||
```
|
||||
|
||||
### Problem: Deployment package import fails
|
||||
|
||||
**Symptoms**: Master data import errors
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check deployment package contents
|
||||
tar -tzf deployment_package_0.1.38.tar.gz
|
||||
|
||||
# Verify package was created correctly
|
||||
cd $BASEDIR/backend
|
||||
./deploy prepare
|
||||
ls -lh export_temp/
|
||||
|
||||
# Import manually if needed
|
||||
docker cp export_temp/masterdata bamort-backend:/app/masterdata
|
||||
docker exec bamort-backend /app/deploy import-masterdata --path /app/masterdata --verbose
|
||||
```
|
||||
|
||||
### Problem: Insufficient disk space
|
||||
|
||||
**Symptoms**: Deployment fails at pre-flight check
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check disk usage
|
||||
df -h
|
||||
|
||||
# Clean up old Docker images
|
||||
docker system prune -a
|
||||
|
||||
# Clean up old backups (keep last 10)
|
||||
cd $BASEDIR/backups
|
||||
ls -lt *.sql | tail -n +11 | awk '{print $NF}' | xargs rm
|
||||
|
||||
# Clean up old logs
|
||||
cd $BASEDIR/logs
|
||||
find . -name "deploy-*.log" -mtime +30 -delete
|
||||
```
|
||||
|
||||
### Problem: Docker daemon not running
|
||||
|
||||
**Symptoms**: `Cannot connect to Docker daemon`
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Start Docker service
|
||||
sudo systemctl start docker
|
||||
|
||||
# Enable Docker on boot
|
||||
sudo systemctl enable docker
|
||||
|
||||
# Verify Docker status
|
||||
sudo systemctl status docker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Development System Commands
|
||||
```bash
|
||||
# Update version
|
||||
./scripts/update-version.sh 0.1.38 auto
|
||||
|
||||
# Create deployment package
|
||||
cd backend && go build -o deploy cmd/deploy/main.go
|
||||
./deploy prepare
|
||||
```
|
||||
|
||||
### Git Commands
|
||||
```bash
|
||||
git tag -a v0.1.38 -m "Release v0.1.38"
|
||||
git push origin main
|
||||
git push origin v0.1.38
|
||||
```
|
||||
|
||||
### Target System Commands
|
||||
```bash
|
||||
# Deploy
|
||||
./scripts/deploy-production.sh v0.1.38
|
||||
|
||||
# Rollback
|
||||
./scripts/rollback.sh backups/pre-deploy-v0.1.38-TIMESTAMP.sql
|
||||
|
||||
# Status check
|
||||
docker exec bamort-backend /app/deploy status
|
||||
docker exec bamort-backend /app/deploy validate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-17
|
||||
**Version**: 1.0
|
||||
**Maintainer**: BaMoRT Development Team
|
||||
Reference in New Issue
Block a user