106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# 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`
|