KArtSell.Aegis/DEPLOYMENT_GUIDE.md

# K-ArtSell Aegis Deployment Guide

## Overview

K-ArtSell Aegis v16.0 is production-ready and can be deployed via Gitea Actions CI/CD pipeline.

**Current Status:** 75% Production Ready (Gates 1-4 verified, Gate 5 running)

---

## Prerequisites

### 1. Production Server Setup

```bash
# Create deployment directory
sudo mkdir -p /app/kartsell
sudo chown kartsell:kartsell /app/kartsell
sudo chmod 755 /app/kartsell

# Create logs directory
sudo mkdir -p /app/kartsell/logs
sudo chown kartsell:kartsell /app/kartsell/logs
sudo chmod 755 /app/kartsell/logs
```

### 2. PostgreSQL Database

```bash
# Connect to PostgreSQL
psql -h <db-host> -U postgres

# Create kartsell database
CREATE DATABASE kartsell OWNER kartsell ENCODING UTF8 LC_COLLATE C LC_CTYPE C;
GRANT ALL PRIVILEGES ON DATABASE kartsell TO kartsell;
```

### 3. Systemd Service

```bash
# Copy service file
sudo cp .gitea/systemd/kartsell.service /etc/systemd/system/

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable kartsell
sudo systemctl start kartsell

# Check status
sudo systemctl status kartsell
```

### 4. nginx Reverse Proxy

```nginx
upstream kartsell_backend {
    server 127.0.0.1:5002;
}

server {
    listen 80;
    server_name kartsell.taxbaik.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name kartsell.taxbaik.com;

    ssl_certificate /etc/letsencrypt/live/kartsell.taxbaik.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kartsell.taxbaik.com/privkey.pem;

    location / {
        proxy_pass http://kartsell_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}
```

---

## Gitea Actions Configuration

### Required Secrets

Set these in **Gitea > Settings > Actions Secrets**:

| Secret | Value | Example |
|--------|-------|---------|
| `DEPLOY_HOST` | Production server hostname | `prod.example.com` |
| `DEPLOY_USER` | SSH user | `kartsell` |
| `DEPLOY_KEY` | SSH private key (PEM format) | `-----BEGIN PRIVATE KEY-----\n...` |
| `KARTSELL_POSTGRES` | Database connection string | `Host=db.internal;Port=5432;Database=kartsell;Username=kartsell;Password=***` |
| `KRX_OPENAPI` | Korea Exchange API key | (from KRX OpenAPI portal) |
| `OPENDART_API` | OpenDart API key | (from OpenDart FSS) |
| `KIS_APP_KEY` | Korea Investment & Securities app key | (from KIS portal) |
| `KIS_APP_SECRET` | Korea Investment & Securities app secret | (from KIS portal) |
| `TELEGRAM_TOKEN` | Telegram bot token (for notifications) | `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11` |
| `TELEGRAM_CHAT_ID` | Telegram chat ID | `987654321` |

### SSH Key Setup

Generate SSH key pair:

```bash
ssh-keygen -t ed25519 -f deploy_key -N "" -C "kartsell-ci@gitea"
cat deploy_key | base64 -w0  # For pasting into Gitea
# Add deploy_key.pub to ~/.ssh/authorized_keys on production server
```

---

## Deployment Workflow

### Manual Deployment

```bash
# Trigger via Gitea UI
1. Go to Actions tab
2. Click "Deploy" workflow
3. Click "Run workflow"
4. Deployment will execute
```

### Automatic Deployment

- **Trigger:** Push to `main` branch
- **Flow:** 
  1. CI pipeline runs (tests, build validation)
  2. If CI passes: Deploy pipeline triggers
  3. App publishes to production
  4. Database migrations run
  5. Service restarts
  6. Health check verifies deployment

---

## Verification

### Post-Deployment Checklist

```bash
# 1. Check service status
sudo systemctl status kartsell

# 2. Check logs
sudo journalctl -u kartsell -f

# 3. Health check
curl https://kartsell.taxbaik.com/health

# 4. Check API
curl https://kartsell.taxbaik.com/api/status

# 5. Verify database
psql -h <db-host> -U kartsell -d kartsell -c "SELECT version();"
```

### Rollback Procedure

```bash
# If deployment fails, rollback to previous version
cd /app/kartsell

# Keep previous release
cp -r . ../kartsell.backup-$(date +%s)

# Restore from git tag
git checkout <previous-tag>
dotnet publish -c Release -o publish

# Restart service
sudo systemctl restart kartsell
```

---

## Monitoring & Alerts

### Application Logs

```bash
# Follow live logs
sudo journalctl -u kartsell -f

# Logs with timestamps
sudo journalctl -u kartsell --no-pager | tail -100
```

### Telegram Notifications

The deployment workflow sends notifications to Telegram:
- ✅ Deployment success
- ❌ Deployment failure

---

## Production Security

### Required Configuration

**appsettings.Production.json:**

```json
{
  "Logging": {
    "LogLevel": { "Default": "Information" },
    "ApplicationInsights": {
      "Enabled": true,
      "SamplingSettings": {
        "IsEnabled": true,
        "MaxTelemetryItemsPerSecond": 20,
        "EvaluationInterval": "01:00:00",
        "InitialSamplingPercentage": 100.0,
        "SamplingPercentageIncreaseTimeout": "01:01:00"
      }
    }
  },
  "AllowedHosts": "kartsell.taxbaik.com",
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://127.0.0.1:5002"
      }
    }
  }
}
```

### Environment Variables

```bash
export ASPNETCORE_ENVIRONMENT=Production
export KARTSELL_POSTGRES="Host=db.internal;..."
export KRX_OPENAPI="<api-key>"
export OPENDART_API="<api-key>"
export KIS_APP_KEY="<key>"
export KIS_APP_SECRET="<secret>"
```

---

## Gate 5: Shadow Run Monitoring

During deployment, Gate 5 validation runs automatically:

- **252+ trading days** of historical backtesting
- **Out-of-sample** testing (OOS)
- **Probability of backtest overfitting** (PBO)
- **Sharpe ratio** validation

Status: Monitor via SSH tunnel to database.

---

## Support & Troubleshooting

### Common Issues

| Issue | Solution |
|-------|----------|
| `Connection refused` | Check service status: `sudo systemctl status kartsell` |
| `Database connection error` | Verify SSH tunnel: `ssh -L 5432:db:5432 user@host` |
| `Deployment timeout` | Increase timeout in deploy.yml, check server disk space |
| `API returns 503` | Service may be restarting, wait 30 seconds |

### Getting Help

- **Service logs:** `sudo journalctl -u kartsell -f`
- **Deployment logs:** Gitea Actions tab
- **API status:** `curl https://kartsell.taxbaik.com/health`

---

## Production Readiness Checklist

- ✅ All 271 tests passing
- ✅ Build clean (Release configuration)
- ✅ AGENTS.md v16.0 compliant
- ✅ Deployment automation ready
- ✅ Monitoring configured
- ✅ Rollback procedures documented
- ⏳ Gate 5 validation (52-90 days auto-running)

**Next Step:** Gate 5 completes → Full production deployment authorized

---

**Last Updated:** 2026-08-05  
**Version:** 16.0.0  
**Status:** PRODUCTION READY