From 0a04e0817df3efb14796df45b9cbbe9446eed603 Mon Sep 17 00:00:00 2001
From: renato97 <renato97@gitea.cbcren.online>
Date: Wed, 28 Jan 2026 23:29:03 -0300
Subject: [PATCH] docs: Add Deployment Guideline

---
 Deploy-Guideline.md | 136 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 Deploy-Guideline.md

diff --git a/Deploy-Guideline.md b/Deploy-Guideline.md
new file mode 100644
index 0000000..783aed0
--- /dev/null
+++ b/Deploy-Guideline.md
@@ -0,0 +1,136 @@
+# 🚀 Deployment Guideline: Finanzas Personales (Next.js + Telegram Bot)
+
+This document contains step-by-step instructions to deploy the "Finanzas Personales" application to a Linux VPS (Ubuntu/Debian recommended).
+
+## 1. Prerequisites
+-   **VPS**: A server with Ubuntu 22.04 or later.
+-   **Domain**: A domain pointing to your VPS IP (e.g., `finanzas.tusitio.com`).
+-   **Gitea Access**: Ensure the VPS can pull from your private Gitea repository.
+
+## 2. Server Setup (Run as root/sudo)
+
+```bash
+# Update system
+apt update && apt upgrade -y
+
+# Install Node.js 18+ (using NVM is recommended, but apt works for deployment)
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+apt install -y nodejs nginx git
+
+# Install Process Manager (PM2)
+npm install -g pm2
+```
+
+## 3. Clone Repository & Install Dependencies
+
+```bash
+# Navigate to web directory
+cd /var/www
+
+# Clone your repo (Use your Gitea token if private)
+git clone https://<YOUR_GITEA_URL>/<USER>/finanzas.git
+cd finanzas
+
+# Install dependencies
+npm install
+
+# Build the Next.js app
+npm run build
+```
+
+## 4. Environment Configuration
+Since we use a custom `server-settings.json`, you need to configure it manually on the server once.
+
+```bash
+# Create the settings file manually (or copy from local if you have sw access)
+nano server-settings.json
+```
+
+Paste your JSON configuration (get this from your local `server-settings.json`):
+```json
+{
+  "telegram": {
+    "botToken": "YOUR_BOT_TOKEN",
+    "chatId": "YOUR_CHAT_ID"
+  },
+  "aiProviders": [
+    {
+      "id": "uuid...",
+      "name": "Service Name",
+      "endpoint": "https://api...",
+      "token": "sk-...",
+      "model": "gpt-4o"
+    }
+  ]
+}
+```
+
+## 5. Startup with PM2 (Keep Apps Alive)
+
+We need to run two processes: The Next.js Web App and the Telegram Bot.
+
+```bash
+# 1. Start Next.js (Port 3000)
+pm2 start npm --name "finanzas-web" -- start -- -p 3000
+
+# 2. Start Telegram Bot
+pm2 start npm --name "finanzas-bot" -- run bot
+
+# Save list so they revive on reboot
+pm2 save
+pm2 startup
+```
+
+## 6. Nginx Reverse Proxy (Expose to Internet)
+
+Configure Nginx to safely expose port 3000 to the web.
+
+```bash
+nano /etc/nginx/sites-available/finanzas
+```
+
+Add this content:
+```nginx
+server {
+    listen 80;
+    server_name finanzas.tusitio.com; # REPLACE THIS
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+    }
+}
+```
+
+Enable site and restart Nginx:
+```bash
+ln -s /etc/nginx/sites-available/finanzas /etc/nginx/sites-enabled/
+nginx -t
+systemctl restart nginx
+```
+
+## 7. SSL Certificate (HTTPS)
+Use Certbot to secure your site for free.
+
+```bash
+apt install -y certbot python3-certbot-nginx
+certbot --nginx -d finanzas.tusitio.com
+```
+
+---
+
+## 8. Updates
+When you push new code to Gitea, update the server:
+
+```bash
+cd /var/www/finanzas
+git pull
+npm install
+npm run build
+pm2 restart finanzas-web
+pm2 restart finanzas-bot
+```