☁️ aipy-cloud — Cloud AppImage Deployment Kit

Deploy aipy-pro (or any AppImage) to a cloud VM and connect from NetHunter via VNC over SSH tunnel.

---

📁 Structure

aipy-cloud/
├── .env.example              ← copy to .env, fill in values
├── requirements.txt          ← Python deps (paramiko, rich, click…)
├── bootstrap.sh              ← ONE-TIME: create venv + .env + SSH key
├── manage.py                 ← Python CLI: deploy / start / vnc / status…
├── scripts/
│   ├── nethunter.sh          ← Run from NetHunter: full interactive pipeline
│   ├── server_setup.sh       ← Run ON server: installs all deps + starts VNC
│   └── quick_deploy.sh       ← Single-command deploy (reads .env)
├── services/
│   └── aipy-pro.service      ← systemd unit (auto-start on reboot)
├── config/
│   └── vnc_xstartup          ← VNC desktop startup script
└── logs/                     ← Local log output

---

🚀 Quick Start

From NetHunter (interactive wizard — recommended)

chmod +x bootstrap.sh scripts/nethunter.sh scripts/server_setup.sh
./bootstrap.sh                 # creates venv + .env + SSH key
nano .env                      # fill in SERVER_IP, VNC_PASSWORD
./scripts/nethunter.sh         # uploads + deploys + opens VNC tunnel

From any Linux/macOS terminal

./bootstrap.sh                 # first time only
source .venv/bin/activate      # activate venv
nano .env                      # fill in SERVER_IP etc.

python manage.py deploy        # upload AppImage + install server deps
python manage.py start         # start VNC + AppImage on server
python manage.py vnc           # open SSH tunnel → connect VNC client

---

⚙️ .env Configuration

Variable	Default	Description
SERVER_IP	(required)	Cloud VM public IP
SERVER_USER	ubuntu	SSH username
SERVER_PORT	22	SSH port
SSH_KEY	~/.ssh/id_ed25519	Path to private key
APPIMAGE_LOCAL_PATH	~/Downloads/aipy-pro-*.AppImage	Local AppImage
VNC_PASSWORD	changeme123	Change this!
VNC_GEOMETRY	1280x720	VNC resolution
LOCAL_VNC_PORT	15901	Local port for SSH tunnel
USE_SSH_TUNNEL	true	Tunnel VNC over SSH (secure)
APPIMAGE_EXTRACT	false	Extract instead of FUSE (for strict VMs)

---

🖥️ manage.py Commands

python manage.py deploy        Upload AppImage + install all server deps
python manage.py start         Start VNC session + launch AppImage
python manage.py vnc           Open SSH tunnel, print VNC connection info
python manage.py stop          Stop AppImage + VNC on server
python manage.py status        Live status table (SSH, process, memory, disk)
python manage.py logs          Tail ~/aipy.log on server
python manage.py ssh           Open interactive SSH shell
python manage.py keycopy       Copy SSH public key to server
python manage.py service       Install aipy-pro as systemd service
python manage.py clean         Remove AppImage + logs from server

---

🔌 VNC Connection from NetHunter

After python manage.py vnc (or ./scripts/nethunter.sh):

1. Keep the SSH tunnel running in one terminal
2. Open bVNC or VNC Viewer on your phone
3. Connect to: localhost:15901
4. Password: value of VNC_PASSWORD in .env

---

🛠 Troubleshooting

Problem	Fix
libfuse2 missing	Script tries libfuse2 then libfuse3 automatically
AppImage won't start	Set APPIMAGE_EXTRACT=true in .env — uses --appimage-extract
VNC blank screen	Check ~/aipy.log on server; python manage.py logs
SSH key rejected	Run python manage.py keycopy or add key via cloud console
Port 5901 blocked	Keep USE_SSH_TUNNEL=true — tunnel goes over port 22
macOS bash error	brew install bash then /opt/homebrew/bin/bash nethunter.sh

---

☁️ Cloud Providers

Works with any Linux VM that has SSH access:

Provider	Free Tier	SSH User
Oracle Cloud	✅ Always Free (4 OCPU / 24GB)	ubuntu or opc
AWS EC2	✅ 12 months free (t2.micro)	ubuntu or ec2-user
Google Cloud	✅ $300 credit	your-username
Hetzner	✅ €20 credit	root
DigitalOcean	✅ $200 credit	root
Linode/Akamai	✅ $100 credit	root

---

🔒 Security Notes

• .env is set to chmod 600 — never commit it to git
• VNC is tunnelled over SSH — port 5901 stays closed
• SSH key authentication only — no password auth
• Run sudo ufw enable && sudo ufw allow 22 on the server