====== 🖥️ New VM / App Deployment Workflow (Fixed IP → DNS → NPM → Cloudflare) ======
This guide documents the **standard TorresVault workflow** for bringing up any new Ubuntu VM or new self‑hosted app — including assigning a fixed IP in UniFi, adding DNS, and routing through NPM and Cloudflare.

Use this as your repeatable checklist every time you deploy something new.

---

===== 1️⃣ Create the VM in Proxmox =====
**Steps:**

* Create an Ubuntu Server VM (use your preferred template)
* Assign CPU/RAM/disk according to app needs
* Boot and complete Ubuntu installation
* Run updates:

<code bash>
sudo apt update && sudo apt upgrade -y && sudo apt autoremove -y
</code>

---

===== 2️⃣ Assign a Fixed IP Address in UniFi =====
**Why:** Ensures stable networking for DNS + proxy routing.

**Steps:**

* Open **UniFi Controller → Clients**
* Find your VM (usually shows up as DHCP)
* Click **Client → Settings → Network**
* Enable **Use Fixed IP**
* Assign your desired IP (e.g., `192.168.1.x`)
* Save → VM may need a reboot

**Verify inside VM:** <code bash>
ip a </code>

---

===== 3️⃣ Add DNS Entry in Pi-hole (Internal DNS) =====
**Goal:** Let LAN devices access the internal service using a hostname.

**Steps:**

* Pi-hole Admin → **Local DNS → DNS Records**
* Add:

  * **Domain:** `<app>.in.torresvault.com`
  * **IP:** `<VM Fixed IP>`
* Save

**Test:** <code bash>
ping <app>.in.torresvault.com </code>

---

===== 4️⃣ Add Reverse Proxy Entry in Nginx Proxy Manager (NPM) ======
**Purpose:** Public HTTPS access to the service.

**Steps:**

* NPM → **Proxy Hosts** → Add Proxy Host
* **Domain Names:** `<app>.torresvault.com`
* **Forward Hostname/IP:** `<VM Fixed IP>`
* **Forward Port:** `APP_PORT`
* Enable:

  * **Block Common Exploits**
  * **Websockets Support** (if needed)
  * **HTTP/2 Support**

**SSL Tab:**

* Request a new certificate
* Enable **Force SSL**
* Use **DNS Challenge (Cloudflare)**

Save.

---

===== 5️⃣ Cloudflare DNS Setup =====
**If using Cloudflare DNS challenge (recommended):**

* Cloudflare → DNS
* Add an A record:

  * **Name:** `<app>`
  * **IP:** Public IP of the UCG Max
  * **Proxy:** Proxied (orange cloud)

> If NPM is handling the service through Cloudflare's DNS challenge, NPM renews certs automatically.

---

===== 6️⃣ Deploy the App Using Docker Compose =====
Create app structure:

<code bash>
mkdir -p ~/apps/<app>/config
mkdir -p ~/apps/<app>/data
cd ~/apps/<app>
</code>

Create your `docker-compose.yml`:

<code yaml>
version: "3.9"
services:
  app:
    image: <image>
    container_name: <app_name>
    restart: unless-stopped
    ports:
      - "PORT:PORT"
    volumes:
      - ./config:/config
      - ./data:/data
    environment:
      - TZ=America/New_York
</code>

Bring it up: <code bash>
docker compose up -d </code>

---

===== 7️⃣ Validate Everything =====
**Internal URL:**

* http://<app>.in.torresvault.com

**External URL:**

* https://<app>.torresvault.com

**Check container logs:** <code bash>
docker logs -f <app_name> </code>

**Check NPM logs if needed:**

* NPM → Logs → Proxy Host Logs

---

===== 8️⃣ Final Checklist =====
☐ VM updated & rebooted

☐ Fixed IP assigned in UniFi

☐ Internal DNS added in Pi-hole (`app.in.torresvault.com`)

☐ Reverse proxy entry added in NPM

☐ Cloudflare DNS record created

☐ SSL cert obtained via DNS challenge

☐ App deployed via Docker Compose

☐ Both internal & external URLs tested

---