mnemo_cards/DEPLOY_GUIDE.md

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:

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:

./deploy_all.sh

2. Web Only Deployment

If you only made changes to the frontend:

./deploy_all.sh --web-only

3. Backend Only Deployment

If you only made changes to the backend:

./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