# 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`