Add deployment guide and scripts
This commit is contained in:
parent
be197fce1c
commit
09df2a93b7
2 changed files with 187 additions and 0 deletions
106
DEPLOY_GUIDE.md
Normal file
106
DEPLOY_GUIDE.md
Normal file
|
|
@ -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`
|
||||
81
deploy_all.sh
Executable file
81
deploy_all.sh
Executable file
|
|
@ -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! 🎉"
|
||||
Loading…
Reference in a new issue