Alby96/Encelado
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor documentazione, versioning e deployment

Browse Source 
- Riorganizzato README.md con badge versione, changelog, guida rapida e istruzioni semplificate per Docker/Unraid
- Creato CHANGELOG.md secondo standard Keep a Changelog/SemVer
- Aggiunto script bump-version.ps1 per gestione automatica versioni e tagging Git
- Aggiornate guide deployment: PUBLISHING_GUIDE.md, UNRAID_INSTALL.md e README.md in /deployment
- Modificato unraid-template.xml: porta WebUI configurabile (default 8888), volumi e variabili ambiente semplificati
- Aggiornata PROJECT_STRUCTURE.md con nuova struttura e best practices
- Migliorata chiarezza, professionalità e automazione del workflow di rilascio
This commit is contained in:
Alberto Balbo
2025-12-21 18:31:00 +01:00
parent 121324dfc7
commit 0e64afa1f2
8 changed files with 417 additions and 1606 deletions
Download Patch File Download Diff File Expand all files Collapse all files

520
TradingBot/deployment/UNRAID_INSTALL.md
View File

@@ -53,17 +53,19 @@ wget -O /boot/config/plugins/dockerMan/templates-user/TradingBot.xml \
- **Name**: `TradingBot` (già impostato)
- **Repository**: `gitea.encke-hake.ts.net/alby96/encelado/tradingbot:latest` (già impostato)
**Porta WebUI** (Importante!):
- **WebUI Port**: `8080` (cambia se occupata, es. `8081`, `9000`, etc.)
- Questa è la porta per accedere all'interfaccia web
**Porta WebUI** (Visibile e Configurabile!):
- **WebUI HTTP Port**: `8888` (porta default - cambia se occupata)
- Questa è la porta HOST per accedere all'interfaccia web
- La porta CONTAINER rimane sempre 8080 (non modificare)
- Alternative comuni se 8888 occupata: `8881`, `9999`, `7777`
**Volume Dati**:
- **AppData**: `/mnt/user/appdata/tradingbot` (già impostato)
- Puoi cambiare se preferisci altra directory
**Variabili Ambiente** (Avanzate - opzionali):
**Variabili Ambiente** (Avanzate - espandi se necessario):
- **ASPNETCORE_ENVIRONMENT**: `Production` (non modificare)
- **ASPNETCORE_URLS**: `http://+:8080` (non modificare)
- **ASPNETCORE_URLS**: `http://+:8080` (non modificare - porta interna container)
- **TZ**: `Europe/Rome` (cambia per altro timezone)
5. Click **Apply**
@@ -71,25 +73,27 @@ wget -O /boot/config/plugins/dockerMan/templates-user/TradingBot.xml \
Unraid farà:
- ? Pull immagine da Gitea Registry
- ? Crea container con nome "TradingBot"
- ? Configura porta WebUI (default 8080)
- ? Configura porta WebUI (default 8888 ? host, 8080 ? container)
- ? Crea volume per persistenza dati
- ? Start automatico
### Step 3: Accedi WebUI
**Metodo A: Click su WebUI Icon**
**Metodo A: Click su WebUI Icon** ??
1. **Docker tab** ? Trova container **TradingBot**
2. Nella colonna "WebUI", click sull'**icona globe** ??
3. Si aprirà la dashboard nel browser
2. Nella riga del container, a destra, vedrai l'**icona globe** ??
3. Click sull'icona ? Si apre automaticamente `http://192.168.30.23:8888`
**Metodo B: URL Manuale**
```
http://192.168.30.23:8080
http://192.168.30.23:8888
```
(Sostituisci `8080` con la porta che hai configurato)
(Sostituisci `8888` con la porta HOST che hai configurato)
?? **IMPORTANTE**: La porta nel browser deve essere quella HOST (8888 default), NON la porta container (8080)
Dovresti vedere la **Dashboard TradingBot**! ??
@@ -215,413 +219,90 @@ Schedula: Settimanale o manualmente quando serve.
### Cambiare Porta WebUI
Se la porta `8080` è già occupata o vuoi usarne un'altra:
La porta **default è 8888** (host) ? **8080** (container).
Se la porta 8888 è occupata o vuoi usarne un'altra:
#### **Via Template (Prima Installazione)**
Durante Step 2 dell'installazione:
- **WebUI Port**: Cambia da `8080` a porta desiderata (es. `8081`, `9000`, `8888`)
- **WebUI HTTP Port**: Cambia da `8888` a porta desiderata (es. `8881`, `9999`, `7777`)
- ?? Modifica SOLO la porta HOST (a sinistra)
- NON modificare la porta Container (deve restare 8080)
#### **Via Edit (Container Esistente)**
1. **Docker tab** ? Container **TradingBot**
2. Click **Edit** (icona matita)
2. Click **Edit** (icona matita/wrench)
3. Trova sezione **Port Mappings**
4. Modifica **Host Port** (es. da `8080` a `8081`)
5. **IMPORTANTE**: Non modificare **Container Port** (deve restare `8080`)
6. Click **Apply**
7. Container si riavvierà automaticamente
4. Vedrai: **Host Port** `8888` ? **Container Port** `8080`
5. Modifica **Host Port** (es. da `8888` a `8881`)
6. **IMPORTANTE**: NON modificare **Container Port** (deve restare `8080`)
7. Click **Apply** in fondo
8. Container si riavvierà automaticamente
#### **Accesso con Nuova Porta**
```
http://192.168.30.23:NUOVA_PORTA
http://192.168.30.23:NUOVA_PORTA_HOST
```
Esempio con porta `8081`:
Esempio con porta `8881`:
```
http://192.168.30.23:8081
http://192.168.30.23:8881
```
### Porte Comuni Disponibili
Se `8080` è occupata, prova queste:
- `8081` - Spesso libera
- `9000` - Usata da Portainer ma se non hai Portainer è libera
- `8888` - Buona alternativa
- `7070` - Altra opzione
- `3000` - Se libera
Se `8888` è occupata, prova queste alternative:
| Porta | Uso Comune | Probabilità Libera |
|-------|------------|-------------------|
| `8881` | Alternative port | ????? Alta |
| `9999` | Generic services | ???? Alta |
| `7777` | Custom apps | ???? Alta |
| `8889` | Next to 8888 | ??? Media |
| `3000` | Dev servers | ?? Bassa (spesso occupata) |
| `8080` | ? NON usare | Troppo comune, quasi sempre occupata |
**Check porta disponibile**:
```bash
netstat -tulpn | grep :8080
# Se restituisce risultato, porta occupata
# Se vuoto, porta libera
# Su Unraid via SSH
netstat -tulpn | grep :8888
# Se restituisce risultato ? porta occupata
# Se vuoto ? porta libera ?
```
---
### Differenza HOST vs CONTAINER Port
## ?? GESTIONE CONTAINER
### Start/Stop/Restart
**Docker tab** ? Container **TradingBot**:
- ?? **Start**: Avvia container
- ?? **Pause**: Pausa (mantiene in memoria)
- ?? **Stop**: Ferma completamente
- ?? **Restart**: Riavvia
- ??? **Remove**: Elimina container (dati persistenti restano)
### View Logs
**Docker tab** ? Container **TradingBot** ? Click **icona logs** (terminale)
Oppure via SSH:
```bash
docker logs TradingBot -f
# -f = follow (real-time)
# Ctrl+C per uscire
```
### Console Access
**Docker tab** ? Container **TradingBot** ? Click **icona console** (bash)
Oppure via SSH:
```bash
docker exec -it TradingBot sh
# sh invece di bash (Alpine Linux base)
```
### Statistics
**Docker tab** ? Container **TradingBot** ? Click **icona stats** (grafico)
Mostra:
- **CPU**: Utilizzo percentuale
- **Memory**: RAM utilizzata/disponibile
- **Network I/O**: Traffico in/out
- **Block I/O**: Lettura/scrittura disco
---
## ?? ACCESSO WEBUI
### Locale (Unraid LAN)
?? **IMPORTANTE da capire**:
```
http://192.168.30.23:8080
HOST Port (8888) ? CONTAINER Port (8080)
?? Porta su Unraid ?? Porta interna Docker
?? Quella nel BROWSER ?? Fissa, NON modificare
?? Configurabile ?? Hardcoded nell'app
?? Esempio: 8888 ?? Sempre 8080
```
Sostituisci:
- `192.168.30.23` con IP del tuo Unraid
- `8080` con porta configurata
### Via Tailscale
Se hai configurato Tailscale su Unraid:
**Esempio configurazione corretta**:
```
http://unraid.encke-hake.ts.net:8080
Browser: http://192.168.30.23:8888
?? Usa porta HOST
Docker: 8888 (host) ? 8080 (container)
?? Mapping ?? App interna
```
### Via Hostname Unraid
Se hai configurato hostname:
```
http://tower:8080
```
(Sostituisci `tower` con hostname del tuo Unraid)
### Reverse Proxy (Accesso HTTPS)
Se usi **Nginx Proxy Manager** o **Swag**:
```nginx
# Nginx Proxy Manager
Upstream: http://192.168.30.23:8080
Domain: tradingbot.tuo-dominio.com
SSL: Let's Encrypt
```
Poi accedi via:
```
https://tradingbot.tuo-dominio.com
```
---
## ?? SICUREZZA
### Best Practices
? **Porta non esposta pubblicamente** (solo LAN o VPN)
? **Volume dati protetto** (`/mnt/user/appdata/tradingbot/`)
? **Registry privato** (Gitea richiede login)
? **Certificati validi** (Tailscale)
? **User non-root** (già configurato nel Dockerfile)
? **Health checks** attivi per monitoring
### Backup Dati
#### **Manuale**
```bash
# Backup
tar -czf /mnt/user/backups/tradingbot-$(date +%Y%m%d).tar.gz \
/mnt/user/appdata/tradingbot
# Restore
tar -xzf /mnt/user/backups/tradingbot-20241217.tar.gz -C /mnt/user/appdata/
```
#### **Con CA Backup Plugin**
1. **Apps** ? Installa "**CA Backup / Restore Appdata**"
2. **Settings** ? **CA Backup/Restore**
3. Aggiungi `/mnt/user/appdata/tradingbot` alla lista
4. Configura schedule automatico (es. giornaliero alle 2:00 AM)
---
## ?? TROUBLESHOOTING
### WebUI Non Accessibile
**Checklist Diagnostica**:
1. ? **Container Running?**
```bash
docker ps | grep TradingBot
# Deve mostrare: Up X minutes (healthy)
```
2. ? **Porta Corretta?**
```bash
docker port TradingBot
# Output: 8080/tcp -> 0.0.0.0:8080
```
3. ? **Health Check?**
```bash
docker inspect TradingBot | grep -A5 Health
# Status deve essere "healthy"
```
4. ? **Test Locale**:
```bash
curl http://localhost:8080/
# Deve restituire HTML
```
5. ? **Check Logs**:
```bash
docker logs TradingBot --tail 50
# Cerca errori
```
**Soluzioni Comuni**:
#### Errore: "Cannot access WebUI"
**Causa**: Porta host occupata o container non started
**Fix**:
```bash
# 1. Verifica porta libera
netstat -tulpn | grep :8080
# 2. Se occupata, edit container e cambia porta
# Docker tab ? Edit ? Port 8080 ? 8081 ? Apply
# 3. Restart container
docker restart TradingBot
```
#### Errore: "Connection refused"
**Causa**: Container started ma app non ready
**Fix**:
```bash
# Attendi 40 secondi (start period)
sleep 40
# Poi testa
curl http://192.168.30.23:8080/
```
#### Errore: "Unhealthy" status
**Causa**: Health check fallisce
**Fix**:
```bash
# Check logs per errori app
docker logs TradingBot
# Possibili cause:
# - Porta interna sbagliata in ASPNETCORE_URLS
# - App crashed al startup
# - Manca volume /app/data
# Ricrea container:
docker stop TradingBot
docker rm TradingBot
# Reinstalla da template
```
### Container Non Si Avvia
**Check logs**:
```bash
docker logs TradingBot
```
**Problemi comuni**:
#### Porta occupata
```
Error: address already in use
```
**Fix**: Cambia **Host Port** in configurazione container (Edit ? Port Mappings)
#### Pull failed
```
Error: unauthorized: authentication required
```
**Fix**:
```bash
docker login gitea.encke-hake.ts.net
# Inserisci credenziali
```
#### Image not found
```
Error: manifest not found
```
**Fix**: Verifica immagine esista su Gitea Packages:
```
https://gitea.encke-hake.ts.net/Alby96/Encelado/-/packages
```
### Performance Issues
**Check risorse**:
```bash
docker stats TradingBot
```
**Limiti raccomandati**:
- **CPU**: 1-2 cores
- **Memory**: 512MB - 1GB
**Configura limiti** (Edit ? Extra Parameters):
```
--cpus="1.5" --memory="768m"
```
---
## ?? CHECKLIST INSTALLAZIONE
### Pre-Install
- [ ] Unraid 6.10+ installato
- [ ] Docker service attivo
- [ ] Porta 8080 (o alternativa) disponibile
- [ ] `docker login gitea.encke-hake.ts.net` successful
- [ ] Internet attivo per pull immagine
### Install
- [ ] Template XML scaricato su Unraid
- [ ] Container creato da template
- [ ] Porta WebUI configurata
- [ ] Volume AppData creato
- [ ] Container status: **running**
### Post-Install
- [ ] Health check: **healthy** (dopo 40 sec)
- [ ] WebUI accessibile (http://IP:PORT)
- [ ] Dashboard carica correttamente
- [ ] Settings modificabili e salvabili
- [ ] Bot avviabile dalla UI
---
## ?? VANTAGGI UNRAID NATIVO
? **Zero dipendenze** (no Portainer, no docker-compose)
? **WebUI Unraid integrata** (gestione familiare)
? **Auto-start** (container parte con Unraid)
? **Backup integrato** (con plugin CA)
? **Update semplice** (2 click: Stop ? Update ? Start)
? **Template riutilizzabile** (reinstall in 1 minuto)
? **Health monitoring** integrato
? **Logs accessibili** dalla UI
---
## ?? WORKFLOW COMPLETO
### Sviluppo (PC)
```
1. ?? Visual Studio ? Codice
2. ?? Build ? Publish (Docker profile)
3. ? Automatico: Push Gitea Registry
4. ?? git push origin main
```
### Deploy (Unraid)
```
1. ?? Docker tab ? TradingBot
2. ?? Stop
3. ?? Force Update (pull latest)
4. ?? Start
5. ? Done! (~ 1 minuto)
```
**Tempo totale**: ~2 minuti dal commit al running!
---
## ?? RISORSE
### Links Utili
| Risorsa | URL |
|---------|-----|
| **Template XML** | `https://gitea.encke-hake.ts.net/Alby96/Encelado/raw/branch/main/TradingBot/deployment/unraid-template.xml` |
| **Repository Git** | `https://gitea.encke-hake.ts.net/Alby96/Encelado` |
| **Docker Image** | `gitea.encke-hake.ts.net/alby96/encelado/tradingbot:latest` |
| **Packages** | `https://gitea.encke-hake.ts.net/Alby96/Encelado/-/packages` |
| **Support/Issues** | `https://gitea.encke-hake.ts.net/Alby96/Encelado/issues` |
### Comandi Utili
```bash
# Status container
docker ps -a | grep TradingBot
# Logs real-time
docker logs -f TradingBot
# Statistics
docker stats TradingBot --no-stream
# Health check
docker inspect TradingBot --format='{{.State.Health.Status}}'
# Restart
docker restart TradingBot
# Update
docker pull gitea.encke-hake.ts.net/alby96/encelado/tradingbot:latest
# Remove (mantiene dati)
docker rm -f TradingBot
```
**Cosa NON fare**:
- ? Cambiare porta Container da 8080 a altro
- ? Modificare `ASPNETCORE_URLS` (deve restare `http://+:8080`)
- ? Usare porta Host 8080 (conflitto con container)
**Cosa puoi fare**:
- ? Cambiare porta Host da 8888 a qualsiasi altra libera
- ? Usare porta Host diversa per ogni app
- ? Accedere con `http://IP:PORTA_HOST`
---
@@ -640,8 +321,73 @@ wget -O /boot/config/plugins/dockerMan/templates-user/TradingBot.xml \
# 3. Install via UI
# Docker tab ? Add Container ? TradingBot template ? Apply
# 4. Access
# Click WebUI icon or http://192.168.30.23:8080
# 4. Access WebUI
# Metodo A: Click icona ?? nella Docker tab
# Metodo B: http://192.168.30.23:8888
```
**?? TradingBot pronto su Unraid!**
---
## ?? Nota sulla Porta
**Default**: Porta HOST `8888` (invece di 8080)
**Perché 8888?**
- Porta 8080 è troppo comune e spesso occupata
- 8888 è quasi sempre libera su Unraid
- Facile da ricordare (quattro 8)
- WebUI icon funziona automaticamente
**Se 8888 è occupata**: Cambia in fase di installazione o dopo via Edit
---
## ?? ACCESSO WEBUI
### Locale (Unraid LAN)
```
http://192.168.30.23:8888
```
Sostituisci:
- `192.168.30.23` con IP del tuo Unraid
- `8888` con porta HOST configurata (se diversa)
### Via Tailscale
Se hai configurato Tailscale su Unraid:
```
http://unraid.encke-hake.ts.net:8888
```
### Via Hostname Unraid
Se hai configurato hostname:
```
http://tower:8888
```
(Sostituisci `tower` con hostname del tuo Unraid e `8888` con porta configurata)
### Reverse Proxy (Accesso HTTPS)
Se usi **Nginx Proxy Manager** o **Swag**:
```nginx
# Nginx Proxy Manager
Upstream: http://192.168.30.23:8888
Domain: tradingbot.tuo-dominio.com
SSL: Let's Encrypt
```
Poi accedi via:
```
https://tradingbot.tuo-dominio.com
```
?? **Nota**: Il reverse proxy si connette alla porta HOST (8888), non container (8080)