Add deployment guide and scripts

DEPLOY_GUIDE.md

@@ -0,0 +1,106 @@
+# Mnemo Cards Deployment Guide
+
+This guide describes how to deploy the Mnemo Cards project (Backend + Web App) using the CI/CD scripts.
+
+## Overview
+
+The deployment strategy is designed to optimize resource usage:
+- **Backend**: Built directly on the server (saves bandwidth, ensures environment compatibility).
+- **Web App**: Built on the client (your machine), then static files are transferred to the server (saves server RAM).
+
+## Prerequisites
+
+1.  **SSH Access**: You must have SSH access to the server `147.45.152.129` as `root`.
+    - Ensure your public SSH key is added to `~/.ssh/authorized_keys` on the server.
+    - You can verify access by running: `ssh root@147.45.152.129`
+
+2.  **Flutter Installed**: You need Flutter installed on your local machine to build the web app.
+
+3.  **Rsync**: Ensure `rsync` is installed on your local machine (usually pre-installed on macOS/Linux).
+
+## Project Structure
+
+-   `deploy_all.sh`: Master script to trigger deployments.
+-   `mnemo_cards_web_v2/deploy.sh`: Script to build and deploy the web app.
+-   `tools/deploy/backend/deploy_remote.sh`: Script to trigger the backend build on the server.
+-   `tools/deploy/web-app/config.sh`: Configuration for web deployment (server IP, paths, ports).
+
+## Forgejo CI/CD Setup
+
+The project includes a workflow `.forgejo/workflows/deploy.yaml` to automate deployment via Forgejo Actions.
+
+### Why SSH?
+Even though Forgejo runs on the same server, the Actions runner usually executes jobs inside isolated Docker containers (like `ubuntu-latest`). To modify files or restart services on the **host** machine (the server itself), the runner needs to "break out" of the container. We use SSH for this because it's secure and standard.
+
+### Secrets Configuration
+To enable the workflow, go to your repository on Forgejo: **Settings -> Actions -> Secrets** and add the following:
+
+| Secret Name | Value | Description |
+|-------------|-------|-------------|
+| `SSH_HOST` | `147.45.152.129` | The public IP of your server. |
+| `SSH_USER` | `root` | The user to log in as (must have permissions to restart services). |
+| `SSH_KEY` | *(Your Private Key)* | The content of your private SSH key (e.g., `~/.ssh/id_rsa`). |
+
+> **Tip**: You can generate a new key pair specifically for CI/CD if you prefer not to use your personal one:
+> `ssh-keygen -t ed25519 -C "ci-cd"`
+> Then add the public key to `~/.ssh/authorized_keys` on the server.
+
+### Runner Installation (Reference)
+The Forgejo runner (`act_runner`) has been installed on the server to execute the workflows.
+- **Service**: `act_runner.service`
+- **User**: `root` (required for Docker/SSH access)
+- **Config**: Registered with tag `ubuntu-latest` to match the workflow.
+
+If you ever need to restart it:
+```bash
+systemctl restart act_runner
+```
+
+## How to Deploy
+
+### Option 1: Via Forgejo UI (Recommended)
+1.  Go to your repository in Forgejo.
+2.  Click on the **Actions** tab.
+3.  Select **Deploy Mnemo Cards** from the left sidebar.
+4.  Click the **Run workflow** button (dropdown).
+5.  Select the branch (usually `master`) and click **Run workflow**.
+
+### Option 2: Via Command Line (Manual)
+If you want to run scripts manually without Forgejo Actions:
+
+#### Full Deployment (Backend + Web)
+
+To deploy both the backend and the web application, run:
+
+```bash
+./deploy_all.sh
+```
+
+### 2. Web Only Deployment
+
+If you only made changes to the frontend:
+
+```bash
+./deploy_all.sh --web-only
+```
+
+### 3. Backend Only Deployment
+
+If you only made changes to the backend:
+
+```bash
+./deploy_all.sh --backend-only
+```
+
+## Troubleshooting
+
+-   **Permission Denied (SSH)**: Check your SSH keys. Ensure you can login to `root@147.45.152.129` without a password prompt (using keys).
+-   **Build Failed (Web)**: Run `flutter doctor` to ensure your local environment is correct. Try running `flutter build web --release` manually in `mnemo_cards_web_v2` to see detailed errors.
+-   **Backend Not Restarting**: SSH into the server and check logs: `journalctl -u mnemo_cards_server -f`.
+-   **Port Conflicts**: The web app is configured to talk to the API on port `8444` (HTTPS). Ensure the backend is actually running on this port.
+
+## Configuration
+
+To change server IP, ports, or paths, edit:
+-   `tools/deploy/web-app/config.sh`
+-   `tools/deploy/backend/deploy_remote.sh`

deploy_all.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+
+# Master Deployment Script for Mnemo Cards
+# Usage: ./deploy_all.sh [options]
+# Options:
+#   --web-only      Deploy only the web application
+#   --backend-only  Deploy only the backend
+#   --help          Show this help message
+
+set -e
+
+# Configuration
+WEB_DEPLOY_SCRIPT="./mnemo_cards_web_v2/deploy.sh"
+BACKEND_DEPLOY_SCRIPT="./tools/deploy/backend/deploy_remote.sh"
+
+# Colors
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Helper functions
+print_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+show_help() {
+    echo "Usage: ./deploy_all.sh [options]"
+    echo "Options:"
+    echo "  --web-only      Deploy only the web application"
+    echo "  --backend-only  Deploy only the backend"
+    echo "  --help          Show this help message"
+    echo ""
+    echo "If no options are provided, both web and backend will be deployed."
+}
+
+# Parse arguments
+DEPLOY_WEB=true
+DEPLOY_BACKEND=true
+
+if [ "$1" == "--web-only" ]; then
+    DEPLOY_BACKEND=false
+elif [ "$1" == "--backend-only" ]; then
+    DEPLOY_WEB=false
+elif [ "$1" == "--help" ]; then
+    show_help
+    exit 0
+fi
+
+# Main execution
+echo "🚀 Starting Mnemo Cards Deployment..."
+
+if [ "$DEPLOY_BACKEND" = true ]; then
+    print_info "Starting Backend Deployment..."
+    if [ -f "$BACKEND_DEPLOY_SCRIPT" ]; then
+        bash "$BACKEND_DEPLOY_SCRIPT"
+    else
+        print_warning "Backend deploy script not found at $BACKEND_DEPLOY_SCRIPT"
+        exit 1
+    fi
+fi
+
+if [ "$DEPLOY_WEB" = true ]; then
+    print_info "Starting Web Deployment..."
+    if [ -f "$WEB_DEPLOY_SCRIPT" ]; then
+        bash "$WEB_DEPLOY_SCRIPT"
+    else
+        print_warning "Web deploy script not found at $WEB_DEPLOY_SCRIPT"
+        exit 1
+    fi
+fi
+
+print_success "Deployment process finished! 🎉"